168 lines
4.9 KiB
Markdown
168 lines
4.9 KiB
Markdown
# 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 路径一致。
|