diff options
| -rw-r--r-- | content/notes/customizing-forgejo.md | 127 |
1 files changed, 127 insertions, 0 deletions
diff --git a/content/notes/customizing-forgejo.md b/content/notes/customizing-forgejo.md new file mode 100644 index 0000000..f02df7a --- /dev/null +++ b/content/notes/customizing-forgejo.md @@ -0,0 +1,127 @@ ++++ +date = '2026-02-21T23:42:55+08:00' +draft = false +title = '自定义 Forgejo 的前端界面' ++++ + +[Forgejo](https://forgejo.org/) 是基于 [Gitea](https://about.gitea.com/) 开发的，用 Go 语言编写的轻量级远程 Git 服务，功能很丰富，可以视作 GitHub 的自托管、开源替代。自建的 Forgejo 实例如果和别人的看起来一模一样，未免太没个性，故决定自定义。 + +## 环境 + +我使用 Docker 部署 Forgejo，使用 `docker compose` 管理容器，所以不能直接在宿主机上修改 Forgejo 的文件，要把宿主机上的文件挂载到容器内。在容器内部，Forgejo 会读取 `/data` 目录下的文件。 + +Forgejo 的官方文档提供了 `docker-compose.yml` 的例子： + +```yaml +networks: + forgejo: + external: false + +services: + server: + image: codeberg.org/forgejo/forgejo:13 + container_name: forgejo + environment: + - USER_UID=1000 + - USER_GID=1000 + restart: always + networks: + - forgejo + volumes: + - ./forgejo:/data + - /etc/localtime:/etc/localtime:ro + ports: + - '3000:3000' + - '222:22' +``` + +关注这一行： + +```yaml + volumes: + - ./forgejo:/data +``` + +这里的意思是：把宿主机上的 `./forgejo` 目录挂载到容器内的 `/data` 目录中。简单来说，如果你是用官方提供的 `docker-compose.yml` 安装的 Forgejo，只需要把 `./forgejo` 当成 `/data` 目录就好了。 + +如果你没有使用 Docker，或者从源代码构建 Forgejo，这篇笔记不适用你的情况。 + +## 更换 Logo + +根据 [Forgejo 的官方文档](https://forgejo.org/docs/next/contributor/customization/#changing-the-logo)，要覆盖 Forgejo 默认的 Logo，需要在 `$FORGEJO_CUSTOM/public/assets/img` 放置这几个文件： + +- `public/assets/img/logo.svg` - 用于站点、应用图标 +- `public/assets/img/logo.png` - 用于 Open Graph 和主页 +- `public/assets/img/favicon.svg` - 用于 favicon +- `public/assets/img/favicon.png` - 有些浏览器不支持 SVG 类型的 favicon，用一个 PNG 图片作为回退 + +撰写这篇笔记时，我使用的 Forgejo 版本是 `13.0.5+gitea-1.22.0`，此时 `$FORGEJO_CUSTOM` 的默认值是 `/data/gitea`，如果你不修改这个环境变量，你就需要把上述文件放在宿主机的 `.forgejo/gitea/public/assets/img/` 目录下。 + +如果没有这个目录，需要字形创建。 + +创建完成之后重启 Docker 容器，清除缓存，查看效果。 + +```shell +docker compose down +docker compose up -d +``` + +## 更改首页模板 + +Forgejo 的首页长这样，总之…… 很难看。 + + + +用上一小节类似的方法，在 `$FORGEJO_CUSTOM/templates/` 目录下创建特定名称的模板文件，就能替换 Forgejo 使用的模板。想知道自己要替换的模板名称叫什么，可以到 [Forgejo 的源代码](https://codeberg.org/forgejo/forgejo/src/branch/forgejo/templates)去找。这里我们要修改的是首页，所以是 `home.tmpl`。 + +创建 `.forgejo/gitea/templates/home.tmpl`，复制源代码中 [home.tmpl](https://codeberg.org/forgejo/forgejo/src/branch/forgejo/templates/home.tmpl) 的内容，做自己想要的修改。下面这个例子删掉了首页的大部分内容和描述文本，只留下站点 Logo 和站点名。 + +```html +{{template "base/head" .}} +<div role="main" aria-label="{{if .IsSigned}}{{ctx.Locale.Tr "dashboard"}}{{else}}{{ctx.Locale.Tr "home"}}{{end}}" class="page-content home"> + <div class="tw-mb-8 tw-px-8"> + <div class="center"> + <img class="logo" width="220" height="220" src="{{AssetUrlPrefix}}/img/logo.svg" alt="{{ctx.Locale.Tr "logo"}}"> + <div class="hero"> + <h1 class="ui icon header title"> + {{AppDisplayName}} + </h1> + </div> + </div> + </div> +</div> +{{template "base/footer" .}} +``` + +保存，重启 Docker 容器，访问实例测试效果。 + +## 自定义 CSS + +Forgejo 的 CSS 文件和图片一样属于静态资源，存在于 `assets` 目录下，具体来说是 `$FORGEJO_CUSTOM/public/assets/css/`。所有的主题文件都以 `theme-` 开头，比如默认的 `theme-forgejo-auto.css`。假设我们要创建一个名为 `foo` 的主题，就要创建 `$FORGEJO_CUSTOM/public/assets/css/theme-foo.css`。 + +这边建议复制 `theme-forgejo-auto.css`，以此基础进行修改。要得到这个文件，可以直接访问： + +``` +https://<你的_FORGEJO_域名>/assets/css/theme-forgejo-auto.css +``` + +~~里面有两百多个 CSS 变量，慢慢改吧（~~ 如果没有特别精细的需求，比如只是想换个主题色，可以直接扔给 LLM 改。 + +准备好 CSS 文件之后，要让 Forgejo 知道有个名为 `foo` 的主题存在。修改 `app.ini` 配置文件，位置一般在 `/data/gitea/conf/app.ini`，对应宿主机上的 `.forgejo/gitea/conf/app.ini`。添加 UI 相关的配置： + +```toml +[ui] +THEMES = gitea,arc-green,forgejo-dark,forgejo-light,forgejo-auto,foo +DEFAULT_THEME = foo +``` + +其中 `THEMES` 告诉 Forgejo 可用的主题有哪些，这些主题会显示在用户的设置项里，用户可以自行选择主题。`DEFAULT_THEME` 就是默认选择的主题，未登录的访客看到的也是这个主题。 + +完成后重启 Docker 容器，应该能看到改动生效了。 + +## 参考资料 + +- https://forgejo.org/docs/next/contributor/customization/ +- https://blog.maximlucas.dev/posts/2025-08-28-theming-forgejo/ +- https://blog.jakobs.systems/en/blog/20251117-forgejo-customization/ + |