参与主题
把自制 Hugo 主题提交到社区主题目录:先做出一份能被别人用起来的主题并本地验证,再按主题仓库的要求开拉取请求;附本站主题的分层做法。
开始之前,你需要
- 本地有可用的 Hugo:
hugo version有输出(标准版即可)。 - 有一个 GitHub 账号,本机
git可用,并且会把本地仓库推送到自己的 GitHub 仓库。 - 手上已经有一个能渲染出页面的自制主题;如果还没有,先按下面的「先做出一份能被别人用起来的主题」把骨架跑通。
读完之后你能
- 用
hugo new theme生成主题骨架,并在一个干净站点里看到它真正生效; - 判断自己的主题是否已经具备「给别人用」的条件:README、许可、可复现的示例配置;
- 走完提交流程:派生主题仓库 → 改一处 → 本地验证 → 提交 → 开 PR;
- 说清本站的两个主题各管什么、为什么中文排版单独放一层;
- 避开四个最容易让 PR 返工的问题:目录结构不合要求、缺 README、缺许可、本地没验证。
这一页解决什么问题
这一页回答的是「我写了一个主题,怎么让别人也能用上」。上游原文只写了两步(读提交指南、开拉取请求)——因为提交动作确实只有两步。但真正会卡住人的是提交之前:主题在你自己站点里跑得好好的,装到别人的站点里却可能什么都不显示;或者 PR 开出去,被要求先补 README 与许可。
所以这一页分两段:先把主题做成「别人能用」的样子并在本地验证,再走提交流程。第二段与上游一致,第一段是本站补齐的部分。
看看别人做了什么
社区为 Hugo 创建了大量主题。可以访问 themes.gohugo.io 浏览这些主题,找到适合自己站点的样式与结构。
如果你已经构建了一个主题,并希望回馈 Hugo 社区,可以把它分享出来,提交到社区主题目录,供其他用户浏览与使用。主题是社区生态的一部分,创建或改进主题也是参与 Hugo 项目的方式之一。
先花十分钟看目录是有用的:找一个和你风格接近的已收录主题,进它的仓库看三件事——根目录有哪些文件、README 写了什么、示例站点放在哪个目录。这三样就是审查者对你的主题的第一印象。
先做出一份能被别人用起来的主题
这一段是本地化增补,目的是让「提交」这一步不返工。
第 1 步:生成骨架
不要手敲目录。用命令生成,Hugo 会连同默认模板与原型一起给你:
hugo new theme my-theme你应当看到什么:当前目录下出现 my-theme/,里面有 archetypes/、assets/、content/、data/、i18n/、layouts/、static/ 与 hugo.toml。为什么必须用命令:手敲出来的空目录既不会报错也不会起作用,容易误判成「主题装好了」。
第 2 步:在一个干净站点里试装
最容易翻车的一步在这里:主题在你自己的站点里能用,不代表在别人的站点里能用——你的站点里可能有一些主题暗中依赖的东西。所以要新建一个最小站点,只装这一个主题:
hugo new project demo-site && cd demo-site把主题放进去——themes/my-theme/,或者用 Hugo 模块引入自己的仓库。然后让站点用上它:
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,看他能不能在十分钟内把主题跑起来。跑不起来,就还不到提交的时候。
提交主题
提交自己的主题只需要两步:
社区主题站点由主题仓库构建和维护,提交所需的格式要求与注意事项都写在它的 README 中,提交前请先完整阅读,以免因格式不符而需要返工。
提交时走的那套 GitHub 流程
提交指南会告诉你「改哪个文件、写什么内容」;「怎么改、怎么验证、怎么提交」是通用的,步骤如下:
-
克隆你的派生仓库,进入目录。
-
新建分支,名字要能看出意图:
bashgit checkout -b add-my-theme -
按指南修改。通常是往指定位置加一条描述你主题的记录(具体字段以指南为准)。
-
本地验证:把改完的仓库按指南的说明跑一遍构建,确认没有报错。
-
提交并写清楚这个 PR 做了什么:
bashgit add -A git commit -m "Add my-theme to the theme site" -
推送到你的派生仓库。
-
开 PR,正文里附上主题仓库地址、在线演示地址与一张截图。
-
项目维护者会审查你的 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 字体栈、行距、断行),带一个开关参数 |
组合方式是配置里的一行:
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 就能跑起来的东西;本站的两层主题结构,可以作为你拆分关注点的现成参考。