参与贡献

参与主题

把自制 Hugo 主题提交到社区主题目录:先做出一份能被别人用起来的主题并本地验证,再按主题仓库的要求开拉取请求;附本站主题的分层做法。

难度
入门
预计用时
提交本身约 20 分钟;把主题打磨到可提交状态取决于主题本身

开始之前,你需要

  • 本地有可用的 Hugo:hugo version 有输出(标准版即可)。
  • 有一个 GitHub 账号,本机 git 可用,并且会把本地仓库推送到自己的 GitHub 仓库。
  • 手上已经有一个能渲染出页面的自制主题;如果还没有,先按下面的「先做出一份能被别人用起来的主题」把骨架跑通。

读完之后你能

  • 用 hugo new theme 生成主题骨架,并在一个干净站点里看到它真正生效;
  • 判断自己的主题是否已经具备「给别人用」的条件:README、许可、可复现的示例配置;
  • 走完提交流程:派生主题仓库 → 改一处 → 本地验证 → 提交 → 开 PR;
  • 说清本站的两个主题各管什么、为什么中文排版单独放一层;
  • 避开四个最容易让 PR 返工的问题:目录结构不合要求、缺 README、缺许可、本地没验证。

接着读:主题组件 · 目录结构 · 参与贡献

这一页解决什么问题

这一页回答的是「我写了一个主题,怎么让别人也能用上」。上游原文只写了两步(读提交指南、开拉取请求)——因为提交动作确实只有两步。但真正会卡住人的是提交之前:主题在你自己站点里跑得好好的,装到别人的站点里却可能什么都不显示;或者 PR 开出去,被要求先补 README 与许可。

所以这一页分两段:先把主题做成「别人能用」的样子并在本地验证,再走提交流程。第二段与上游一致,第一段是本站补齐的部分。

看看别人做了什么

社区为 Hugo 创建了大量主题。可以访问 themes.gohugo.io 浏览这些主题,找到适合自己站点的样式与结构。

如果你已经构建了一个主题,并希望回馈 Hugo 社区,可以把它分享出来,提交到社区主题目录,供其他用户浏览与使用。主题是社区生态的一部分,创建或改进主题也是参与 Hugo 项目的方式之一。

先花十分钟看目录是有用的:找一个和你风格接近的已收录主题,进它的仓库看三件事——根目录有哪些文件、README 写了什么、示例站点放在哪个目录。这三样就是审查者对你的主题的第一印象。

先做出一份能被别人用起来的主题

这一段是本地化增补,目的是让「提交」这一步不返工。

第 1 步:生成骨架

不要手敲目录。用命令生成,Hugo 会连同默认模板与原型一起给你:

bash
hugo new theme my-theme

你应当看到什么:当前目录下出现 my-theme/,里面有 archetypes/、assets/、content/、data/、i18n/、layouts/、static/ 与 hugo.toml。为什么必须用命令:手敲出来的空目录既不会报错也不会起作用,容易误判成「主题装好了」。

第 2 步:在一个干净站点里试装

最容易翻车的一步在这里:主题在你自己的站点里能用,不代表在别人的站点里能用——你的站点里可能有一些主题暗中依赖的东西。所以要新建一个最小站点,只装这一个主题:

bash
hugo new project demo-site && cd demo-site

把主题放进去——themes/my-theme/,或者用 Hugo 模块引入自己的仓库。然后让站点用上它:

toml
theme = 'my-theme'

你应当看到什么:执行 hugo server -D 后打开终端提示的地址(默认 http://localhost:1313/),页面带上你主题的样式与结构。-D 会把标记为草稿(draft: true)的内容一起渲染,方便你立刻看到示例文章。

这一步必须能通过,再往下走。主题在干净站点里报错或不显示,通常是两种情况:

症状 真因 怎么修
页面能开但没有任何样式 样式文件没被打包进去,或模板里引用的路径不对 确认 CSS 放在主题的 assets/(走资源管道)或 static/(原样复制),并检查模板里的引用方式
页面能开但内容和默认站点一样 主题根本没被用上:theme 没写、写错名字,或主题目录名字与 theme 的值不一致 核对 theme = '...' 与 themes/ 下的目录名逐字相同
构建报模板找不到 主题里的模板目录结构不符合 Hugo 的查找规则 对照目录结构与模板查找顺序

第 3 步:补齐「给别人用」必需的三样

要补的东西 为什么必须
README 别人打开你的仓库,第一个看的就是它:主题做什么、怎么装、有哪些配置项、截图在哪
许可(LICENSE) 没有许可,别人在法律上不能安心使用你的主题
最小可用的示例配置 你主题里读的每个 params,都要在 README 或示例里写清楚;否则别人装上是「一片空白」

判断标准很简单:找一位没看过你主题的同事(或者隔一周后的你自己),只给 README,看他能不能在十分钟内把主题跑起来。跑不起来,就还不到提交的时候。

提交主题

提交自己的主题只需要两步:

  1. 阅读提交指南;
  2. 在主题仓库中开一个拉取请求。

社区主题站点由主题仓库构建和维护,提交所需的格式要求与注意事项都写在它的 README 中,提交前请先完整阅读,以免因格式不符而需要返工。

提交时走的那套 GitHub 流程

提交指南会告诉你「改哪个文件、写什么内容」;「怎么改、怎么验证、怎么提交」是通用的,步骤如下:

  1. 派生主题仓库 https://github.com/gohugoio/hugoThemesSiteBuilder。

  2. 克隆你的派生仓库,进入目录。

  3. 新建分支,名字要能看出意图:

    bash
    git checkout -b add-my-theme
  4. 按指南修改。通常是往指定位置加一条描述你主题的记录(具体字段以指南为准)。

  5. 本地验证:把改完的仓库按指南的说明跑一遍构建,确认没有报错。

  6. 提交并写清楚这个 PR 做了什么:

    bash
    git add -A
    git commit -m "Add my-theme to the theme site"
  7. 推送到你的派生仓库。

  8. 开 PR,正文里附上主题仓库地址、在线演示地址与一张截图。

  9. 项目维护者会审查你的 PR,可能会要求修改。维护者合并 PR 之后,你可以删除该分支。

你应当看到什么:每一步之后都能用一条命令确认——git branch --show-current 确认分支、git log --oneline -1 确认提交、git push 的输出里出现创建 PR 的链接。看不到就停下来查,不要靠猜。

本站(中文文档站)的主题是怎么做的

这一段是本地化增补。本站自己也有一套主题,做法可以直接借鉴——它不是「一个大主题」,而是两层:

层 位置 管什么
项目约束层 layouts/ 只放跨主题共用的骨架约束(基础模板与必须提供的局部模板名)
基础主题 themes/hugo-docs-theme/ 版式:页面模板、局部模板、main.css、代码高亮配色、脚本
中文叠加层 themes/hugo-docs-theme-zh/ 只做中文排版(CJK 字体栈、行距、断行),带一个开关参数

组合方式是配置里的一行:

toml
theme = ["hugo-docs-theme-zh", "hugo-docs-theme"]

为什么要把中文排版单独拆一层:拆开之后,任何中文站点都能只加这一层来改善排版,而不必换掉自己原来的主题;反过来,改版式也不会碰到中文排版规则。这是「一个主题一个关注点」的直接收益,也是你设计自己的主题时值得抄的一条经验。

改动时按层选地方(本站的实际约定):换配色改基础主题的 CSS 变量,换中文排版改叠加层,只有「所有主题都必须一致」的约束才写进项目层。

一个与本页直接相关的结论:本站的两个主题都由 hugo new theme 命令生成,随后删掉了生成的示例模板、示例文章与示例菜单——示例文件要清理干净再提交,尤其是会自动生效的示例菜单项,否则会出现在使用者的导航里。

其他主题目录

除了官方社区主题站点,还可以在下列主题目录中浏览或提交主题:

常见坑

症状 真因 怎么修
主题在自己站点能用,别人装上「一片空白」 主题依赖了你站点里的配置、内容或资源,而没写进 README 在干净站点里只装主题重跑一遍,见第 2 步
页面能开但没有任何样式 CSS 放在主题外,或模板引用的路径不对 样式放主题的 assets/ 或 static/,并核对模板里的引用
页面内容和默认站点一样 theme 没写、写错,或目录名与 theme 的值不一致 让 theme 的值与 themes/ 下的目录名逐字相同
PR 被要求返工:目录结构或字段不符 没有按提交指南组织文件 先完整读提交指南再动手
PR 被要求先补 README 或 LICENSE 主题还不能「被别人独立使用」 按第 3 步补齐
提交里混进了生成物或示例残留 把 public/、resources/ 或示例文章一起提交了 只提交源码,并在 .gitignore 里忽略构建产出;清理示例菜单项
本地没构建就开了 PR 跳过了验证 提交前至少跑一次构建,见第 2 步

主题本身出了问题(页面不渲染、模板找不到、样式丢失),到故障排查按现象查;模板的查找规则见模板查找顺序。

补充说明

主题通常放在项目的 themes/ 目录中,也可以通过 Hugo 模块引入;无论采用哪种方式使用主题,都不影响向社区主题目录提交。

对本页读者的一句话总结:提交只需两步,但「值得被收录」需要先把主题做成别人照着 README 就能跑起来的东西;本站的两层主题结构,可以作为你拆分关注点的现成参考。