把 Hugo 带到中文世界
Hugo 中文文档 884 页译文 · 64 个章节页 · 附教学层与英文原文对照
Hugo 官方文档全部 19 个一级章节、948 页的社区简体中文翻译(非官方),附英文原文链接,便于对照阅读。
- 884页译文
- 64个章节页
- 267页教学说明
- 26个实测踩坑
你想做什么?
按任务选入口,不必先读完整个目录。每一页都标了难度与预计用时。
常用入口
站内被引用最多的几个页面——多数模板问题都落在这里。
全部章节
19 个章节与上游一一对应;带「页数」的是参考章节,可以只当字典查。
- 技能包把建站经验打包给 AI 编码代理:一份可复用的 Hugo 技能包,含 26 个真实踩坑、SEO、多主题、日期与短代码的参考手册。 0 项
- 动态说清本站「动态」章节的范围——只有这一页索引,没有逐条发布说明——并给出查看官方发布说明的入口与升级前的六步检查清单。 0 项
- 方法在模板中使用这些方法:Page、Site、Pages、Resource、Menu 等对象上的方法。 12 项
- 函数在模板与原型中使用的全部函数与方法。 30 项
- 入门从零开始搭建并运行一个 Hugo 站点:快速开始、安装、基本用法、目录结构与配置。 3 项
- 内容管理内容管理章节总览:内容格式、前置元数据、内容组织与页面资源;含本章阅读顺序与最容易配错的几处索引。 22 项
- 命令Hugo 命令行界面的整体结构与各命令索引。 44 项
- 托管与部署把 Hugo 生成的 public/ 变成线上可访问的站点:三条命令行部署路线与十一个托管平台,每页都给出完整步骤、要填的变量与失败排查 … 14 项
- Hugo Pipes用资源管道把 assets 目录里的文件取得、转换、压缩、加指纹并发布出去。本章给出环境依赖、阅读顺序与常见报错的排查入口。 9 项
- Hugo 模块用模块管理站点的内容、呈现与行为:讲清模块解决什么问题、挂载与导入怎么用,并给出可运行示例、验证方法与常见坑。 4 项
- 模板用模板把内容、资源与数据渲染为发布页面:本章给出完整学习路径,每页都带最小可运行示例与可检验的验证方法。 13 项
- 渲染钩子用模板覆盖 Markdown 元素到 HTML 的转换:模板放在哪里、怎么命名、能输出什么,以及配错时该怎么查。 8 项
- 短代码Hugo 内置短代码总览:标准记法与 Markdown 记法的渲染顺序差异、参数规则、12 个内置短代码的参数与输出,示例可直接复制到自 … 11 项
- 可运行示例本站的示例不是贴出来的代码:每个示例都是 layouts 里真实执行的模板,输出由构建时现场产出;声明与参数写在内容页的前置元数据里,新 … 0 项
- 配置Hugo 配置怎么组织、按什么顺序查找与合并、如何按环境覆盖;含「改了没生效」的排查路径与常见坑。 33 项
- 安装Hugo 的发行版差异、各平台安装方式、从源码构建、验证安装与升级方法,以及装不上或装错时怎么排查。 4 项
- 故障排查构建失败、页面缺失或输出不对时的分诊台:先按症状定位,再按「可能原因 → 怎么确认 → 怎么修」处理,并给出本章的阅读顺序。 6 项
- 关于介绍 Hugo 的定位与特性、隐私保护、许可说明与安全模型。 4 项
- 速查Hugo 常用语法、配置与术语的速查索引。 7 项
- 工具创建与管理 Hugo 站点的第三方工具:编辑器插件、可视化 CMS、站内搜索与迁移工具的选型、最小可用步骤与验证方法。 5 项
- 参与贡献参与 Hugo 项目与该中文文档站的三条路径:开发、文档、主题;先分清「改哪个仓库」,再按最小可验证的步骤提交第一个拉取请求。 3 项
本站是社区维护的 Hugo 官方文档简体中文翻译(非官方,站点 https://hugozh.cn/),覆盖上游全部 19 个一级章节——从入门、安装、配置,到内容管理、模板、渲染钩子、短代码、资源管道、模块、托管部署、命令、故障排查与速查。每一页都对应官方英文站点的一页,页面底部保留原文链接,便于随时对照核实。
与单纯直译不同,本站给学习成本最高的页面补了一层教学层(难度、预计用时、前置条件、读完之后能做到什么),并为 313 个函数、268 个方法与 158 条术语补上「什么时候用、怎么用、边界在哪」。这些内容的取用方式见技能包与面向 AI 代理的出口。
译文由 亦幸 和 DeepSeek Harness 整理,仅供学习参考。Hugo 迭代较快,如与官方英文原文有出入,请以官方文档为准。
完成度与范围
上游的全部一级章节均已翻译,并与上游页面 1:1 对应:313 页函数参考、268 页方法参考、159 条术语表,以及速查、命令、配置等各章。未纳入正文的只有上游 news/(其索引页已译,无 news 正文)与 _common/ 文档片段目录(片段内容已随引用它的页面内联译出)。
个别页面上游的默认值由 code-toggle 等数据块提供,本站以文字说明为主;需要精确默认值时请看该页 source 指向的官网页面。
遇到问题去哪儿
- 构建报错或页面不符合预期 → 故障排查 按症状分诊;
- 命令行参数不清楚 → 命令;
- 提问与交流 → Hugo 官方论坛(设有中文分类,可在分类列表中查找)。提问前请先读求助指南,并附上
hugo env输出与最小复现示例。
翻译与术语约定
专有名词首次出现时以「中文(english)」形式标注,其后沿用同一译法,以保证全站一致。主要约定如下:
| 英文 | 本站译法 | 说明 |
|---|---|---|
| front matter | 前置元数据(front matter) | 文件顶部用 +++/--- 包裹的元数据块,正文中亦直接写作 front matter |
| page bundle | 页面包 | 把页面与其资源放在同一目录的组织方式 |
| branch bundle | 分支包 | 以 _index.md 为入口的页面包 |
| leaf bundle | 叶子包 | 以 index.md 为入口的页面包 |
| shortcode | 短代码(shortcode) | 在内容中调用模板的函数式标记 |
| archetype | 原型(archetype) | hugo new content 生成新文件时套用的模板 |
| partial | 局部模板(partial) | 可被其他模板复用的模板片段 |
| render hook | 渲染钩子(render hook) | 覆盖 Markdown 元素默认渲染方式的模板 |
| taxonomy | 分类法(taxonomy) | 标签、分类等结构化归类机制 |
| section | section(内容区块) | content/ 下的顶层目录,保留英文以免与「章节」混淆 |
构建本站源码
本站是一个自包含的 Hugo 项目:无需外部主题、无需联网即可构建(要求 Hugo 0.147+,标准版即可)。完整说明见仓库中的 README。
# 在仓库根目录执行
hugo server # 本地预览,默认 http://localhost:1313/
hugo server -D # 连同草稿一起预览
hugo # 生成静态站点到 public/版权与免责
- 原文版权归 Hugo 项目及其文档贡献者所有,原文仓库为 gohugoio/hugoDocs。
- 本站译文仅用于学习与交流,不构成对官方文档的替代。
- 如果你是文档作者并希望调整或移除某处译文,请以官方文档为准并联系本站维护者处理。