From 0bc1b0d2d0974060da6ece2ed43cfdf12f4af532 Mon Sep 17 00:00:00 2001
From: chuan <haeer98@outlook.com>
Date: Mon, 18 May 2026 09:46:02 +0800
Subject: [PATCH] =?UTF-8?q?docs:=20=E6=9B=B4=E6=96=B0?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 docs/usage.md | 167 ++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 167 insertions(+)
 create mode 100644 docs/usage.md

diff --git a/docs/usage.md b/docs/usage.md
new file mode 100644
index 0000000..89c47ec
--- /dev/null
+++ b/docs/usage.md
@@ -0,0 +1,167 @@
+# Gitea 主题使用说明
+
+本文档说明如何在 Gitea 中使用已经编译好的主题包。
+
+## 主题内容
+
+编译后的发布包中会包含一个 `custom/` 目录，主要内容如下：
+
+```text
+custom/
+  public/assets/css/theme-github-dev.css
+  public/assets/css/theme-github-dev-dark.css
+  templates/
+  options/
+```
+
+其中：
+
+- `theme-github-dev.css` 是亮色主题。
+- `theme-github-dev-dark.css` 是暗色主题。
+- `templates/` 是模板覆盖文件，用于调整部分页面结构。
+- `options/` 是语言和其他 Gitea 自定义配置资源。
+
+## 安装到 Gitea
+
+将发布包中的 `custom/` 目录复制到 Gitea 的自定义目录。
+
+常见路径如下：
+
+```text
+/data/gitea/custom
+```
+
+复制完成后，文件结构应类似：
+
+```text
+/data/gitea/custom/public/assets/css/theme-github-dev.css
+/data/gitea/custom/public/assets/css/theme-github-dev-dark.css
+/data/gitea/custom/templates/
+/data/gitea/custom/options/
+```
+
+如果你的 Gitea 使用了不同的 custom 路径，请以 Gitea 实际配置为准。
+
+## 配置主题
+
+编辑 Gitea 的 `app.ini`，在 `[ui]` 区域启用主题：
+
+```ini
+[ui]
+THEMES = github-dev,github-dev-dark
+DEFAULT_THEME = github-dev-dark
+```
+
+如果希望默认使用亮色主题，可以改成：
+
+```ini
+[ui]
+THEMES = github-dev,github-dev-dark
+DEFAULT_THEME = github-dev
+```
+
+修改后重启 Gitea。
+
+## 首页和探索页配置
+
+如果希望未登录用户默认进入探索页，并隐藏探索页里的用户、组织和代码入口，可以在 `app.ini` 中加入：
+
+```ini
+[server]
+LANDING_PAGE = explore
+
+[service.explore]
+DISABLE_USERS_PAGE = true
+DISABLE_ORGANIZATIONS_PAGE = true
+DISABLE_CODE_PAGE = true
+```
+
+这些配置的作用是：
+
+- `LANDING_PAGE = explore`：把站点首页设置为探索页。
+- `DISABLE_USERS_PAGE = true`：隐藏探索页中的用户页面。
+- `DISABLE_ORGANIZATIONS_PAGE = true`：隐藏探索页中的组织页面。
+- `DISABLE_CODE_PAGE = true`：隐藏探索页中的代码搜索页面。
+
+如果使用 Docker 环境变量，等价写法是：
+
+```yaml
+environment:
+  - GITEA__server__LANDING_PAGE=explore
+  - GITEA__service_0x2E_explore__DISABLE_USERS_PAGE=true
+  - GITEA__service_0x2E_explore__DISABLE_ORGANIZATIONS_PAGE=true
+  - GITEA__service_0x2E_explore__DISABLE_CODE_PAGE=true
+```
+
+其中 `_0x2E_` 表示英文句点 `.`，所以 `GITEA__service_0x2E_explore__DISABLE_USERS_PAGE` 对应 `app.ini` 中的：
+
+```ini
+[service.explore]
+DISABLE_USERS_PAGE = true
+```
+
+能直接编辑 `app.ini` 时，建议优先使用 `app.ini` 写法；Docker 环境变量更适合容器编排或不方便直接改配置文件的场景。
+
+## Docker 使用方式
+
+如果 Gitea 通过 Docker 部署，需要把 `custom/` 目录挂载到容器内的 Gitea custom 目录。
+
+示例：
+
+```yaml
+volumes:
+  - ./custom/public:/data/gitea/public
+  - ./custom/templates:/data/gitea/templates
+  - ./custom/options:/data/gitea/options
+```
+
+也可以直接把完整 custom 目录挂载到 Gitea 的 custom 根目录，具体取决于你的部署方式和现有目录结构。
+
+环境变量配置示例：
+
+```yaml
+environment:
+  - GITEA__ui__THEMES=github-dev,github-dev-dark
+  - GITEA__ui__DEFAULT_THEME=github-dev-dark
+  - GITEA__server__LANDING_PAGE=explore
+  - GITEA__service_0x2E_explore__DISABLE_USERS_PAGE=true
+  - GITEA__service_0x2E_explore__DISABLE_ORGANIZATIONS_PAGE=true
+  - GITEA__service_0x2E_explore__DISABLE_CODE_PAGE=true
+```
+
+修改挂载或环境变量后，需要重启容器。
+
+## 用户切换主题
+
+启用后，用户可以在 Gitea 的主题设置中选择：
+
+- `GitHub Light`
+- `GitHub Dark`
+
+如果站点启用了本主题提供的模板覆盖，顶部导航栏也会显示亮色和暗色主题切换按钮。
+
+## 注意事项
+
+- 主题名必须使用 `github-dev` 和 `github-dev-dark`，不要改成 `gitea`、`gitea-auto`、`arc-green` 等 Gitea 内置主题名。
+- CSS 文件名必须保持为 `theme-github-dev.css` 和 `theme-github-dev-dark.css`。
+- `templates/` 和 `options/` 建议与 CSS 一起安装，否则部分页面结构、按钮或中文文案可能不完整。
+- 安装或更新主题后必须重启 Gitea，否则新主题、模板或语言文件可能不会立即生效。
+- 如果浏览器仍显示旧样式，清理浏览器缓存或强制刷新页面。
+- 如果 Gitea 已经有其他自定义模板，复制 `templates/` 前需要检查是否会覆盖现有文件。
+- 该主题按 Gitea `1.26.1` 版本维护。用于其他 Gitea 版本时，模板覆盖可能需要额外检查。
+
+## 验证是否生效
+
+重启 Gitea 后，可以检查页面源码或网络请求中是否加载了以下文件：
+
+```text
+/assets/css/theme-github-dev.css
+/assets/css/theme-github-dev-dark.css
+```
+
+如果页面没有加载对应 CSS，请重点检查：
+
+- `custom/` 是否放到了正确的 Gitea custom 路径。
+- `[ui].THEMES` 是否包含 `github-dev` 和 `github-dev-dark`。
+- `[ui].DEFAULT_THEME` 是否填写了已启用的主题名。
+- Docker 挂载路径是否和容器内 Gitea 路径一致。