# 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 路径一致。