chuan/gitea-themes

Fork 0

Files

T

chuan 0bc1b0d2d0 docs: 更新

2026-05-18 09:46:02 +08:00

4.9 KiB

Raw Permalink Blame History

Gitea 主题使用说明

本文档说明如何在 Gitea 中使用已经编译好的主题包。

主题内容

编译后的发布包中会包含一个 custom/ 目录，主要内容如下：

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 的自定义目录。

常见路径如下：

/data/gitea/custom

复制完成后，文件结构应类似：

/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] 区域启用主题：

[ui]
THEMES = github-dev,github-dev-dark
DEFAULT_THEME = github-dev-dark

如果希望默认使用亮色主题，可以改成：

[ui]
THEMES = github-dev,github-dev-dark
DEFAULT_THEME = github-dev

修改后重启 Gitea。

首页和探索页配置

如果希望未登录用户默认进入探索页，并隐藏探索页里的用户、组织和代码入口，可以在 app.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 环境变量，等价写法是：

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 中的：

[service.explore]
DISABLE_USERS_PAGE = true

能直接编辑 app.ini 时，建议优先使用 app.ini 写法；Docker 环境变量更适合容器编排或不方便直接改配置文件的场景。

Docker 使用方式

如果 Gitea 通过 Docker 部署，需要把 custom/ 目录挂载到容器内的 Gitea custom 目录。

示例：

volumes:
  - ./custom/public:/data/gitea/public
  - ./custom/templates:/data/gitea/templates
  - ./custom/options:/data/gitea/options

也可以直接把完整 custom 目录挂载到 Gitea 的 custom 根目录，具体取决于你的部署方式和现有目录结构。

环境变量配置示例：

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 后，可以检查页面源码或网络请求中是否加载了以下文件：

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

4.9 KiB Raw Permalink Blame History