docs: new note

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 的首页长这样，总之…… 很难看。
+
+![](https://r2.eltr.ac/jar/forgejo-homepage.png)
+
+用上一小节类似的方法，在 `$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/
+