# Hugo 中文文档

> Hugo 官方文档全部 19 个一级章节、948 页的社区简体中文翻译（非官方），附英文原文链接，便于对照阅读。

- 站点：https://hugozh.cn/
- 官方上游：https://gohugo.io/
- 性质：社区维护的非官方中文翻译；如有出入以官方英文原文为准
- 语言：简体中文（zh-CN）

## 分主题入口
- [技能包](https://hugozh.cn/skill/)：把建站经验打包给 AI 编码代理：一份可复用的 Hugo 技能包，含 26 个真实踩坑、SEO、多主题、日期与短代码的参考手册。（Markdown：https://hugozh.cn/skill/index.md）
- [动态](https://hugozh.cn/news/)：说清本站「动态」章节的范围——只有这一页索引，没有逐条发布说明——并给出查看官方发布说明的入口与升级前的六步检查清单。（Markdown：https://hugozh.cn/news/index.md）
- [方法](https://hugozh.cn/methods/)：在模板中使用这些方法：Page、Site、Pages、Resource、Menu 等对象上的方法。（Markdown：https://hugozh.cn/methods/index.md）
- [函数](https://hugozh.cn/functions/)：在模板与原型中使用的全部函数与方法。（Markdown：https://hugozh.cn/functions/index.md）
- [入门](https://hugozh.cn/getting-started/)：从零开始搭建并运行一个 Hugo 站点：快速开始、安装、基本用法、目录结构与配置。（Markdown：https://hugozh.cn/getting-started/index.md）
- [内容管理](https://hugozh.cn/content-management/)：内容管理章节总览：内容格式、前置元数据、内容组织与页面资源；含本章阅读顺序与最容易配错的几处索引。（Markdown：https://hugozh.cn/content-management/index.md）
- [命令](https://hugozh.cn/commands/)：Hugo 命令行界面的整体结构与各命令索引。（Markdown：https://hugozh.cn/commands/index.md）
- [托管与部署](https://hugozh.cn/host-and-deploy/)：把 Hugo 生成的 public/ 变成线上可访问的站点：三条命令行部署路线与十一个托管平台，每页都给出完整步骤、要填的变量与失败排查入口。（Markdown：https://hugozh.cn/host-and-deploy/index.md）
- [Hugo Pipes](https://hugozh.cn/hugo-pipes/)：用资源管道把 assets 目录里的文件取得、转换、压缩、加指纹并发布出去。本章给出环境依赖、阅读顺序与常见报错的排查入口。（Markdown：https://hugozh.cn/hugo-pipes/index.md）
- [Hugo 模块](https://hugozh.cn/hugo-modules/)：用模块管理站点的内容、呈现与行为：讲清模块解决什么问题、挂载与导入怎么用，并给出可运行示例、验证方法与常见坑。（Markdown：https://hugozh.cn/hugo-modules/index.md）
- [模板](https://hugozh.cn/templates/)：用模板把内容、资源与数据渲染为发布页面：本章给出完整学习路径，每页都带最小可运行示例与可检验的验证方法。（Markdown：https://hugozh.cn/templates/index.md）
- [渲染钩子](https://hugozh.cn/render-hooks/)：用模板覆盖 Markdown 元素到 HTML 的转换：模板放在哪里、怎么命名、能输出什么，以及配错时该怎么查。（Markdown：https://hugozh.cn/render-hooks/index.md）
- [短代码](https://hugozh.cn/shortcodes/)：Hugo 内置短代码总览：标准记法与 Markdown 记法的渲染顺序差异、参数规则、12 个内置短代码的参数与输出，示例可直接复制到自己的站点。（Markdown：https://hugozh.cn/shortcodes/index.md）
- [可运行示例](https://hugozh.cn/examples/)：本站的示例不是贴出来的代码：每个示例都是 layouts 里真实执行的模板，输出由构建时现场产出；声明与参数写在内容页的前置元数据里，新增示例只改 content。（Markdown：https://hugozh.cn/examples/index.md）
- [配置](https://hugozh.cn/configuration/)：Hugo 配置怎么组织、按什么顺序查找与合并、如何按环境覆盖；含「改了没生效」的排查路径与常见坑。（Markdown：https://hugozh.cn/configuration/index.md）
- [安装](https://hugozh.cn/installation/)：Hugo 的发行版差异、各平台安装方式、从源码构建、验证安装与升级方法，以及装不上或装错时怎么排查。（Markdown：https://hugozh.cn/installation/index.md）
- [故障排查](https://hugozh.cn/troubleshooting/)：构建失败、页面缺失或输出不对时的分诊台：先按症状定位，再按「可能原因 → 怎么确认 → 怎么修」处理，并给出本章的阅读顺序。（Markdown：https://hugozh.cn/troubleshooting/index.md）
- [关于](https://hugozh.cn/about/)：介绍 Hugo 的定位与特性、隐私保护、许可说明与安全模型。（Markdown：https://hugozh.cn/about/index.md）
- [速查](https://hugozh.cn/quick-reference/)：Hugo 常用语法、配置与术语的速查索引。（Markdown：https://hugozh.cn/quick-reference/index.md）
- [工具](https://hugozh.cn/tools/)：创建与管理 Hugo 站点的第三方工具：编辑器插件、可视化 CMS、站内搜索与迁移工具的选型、最小可用步骤与验证方法。（Markdown：https://hugozh.cn/tools/index.md）
- [参与贡献](https://hugozh.cn/contribute/)：参与 Hugo 项目与该中文文档站的三条路径：开发、文档、主题；先分清「改哪个仓库」，再按最小可验证的步骤提交第一个拉取请求。（Markdown：https://hugozh.cn/contribute/index.md）

## 机器可读资源

- 全站页面清单（JSON，含标题/摘要/章节/官方原文/更新时间）：https://hugozh.cn/pages.json
- 全站页面清单（XML）：https://hugozh.cn/sitemap.xml
- LLM 入口文件：https://hugozh.cn/llms.txt
- 每个内容页的 Markdown：在页面 URL 后接 `index.md`

---


本站是社区维护的 [Hugo](https://gohugo.io/) 官方文档简体中文翻译（**非官方**，站点 <https://hugozh.cn/>），覆盖上游**全部 19 个一级章节**——从入门、安装、配置，到内容管理、模板、渲染钩子、短代码、资源管道、模块、托管部署、命令、故障排查与速查。每一页都对应官方英文站点的一页，页面底部保留原文链接，便于随时对照核实。

与单纯直译不同，本站给学习成本最高的页面补了一层**教学层**（难度、预计用时、前置条件、读完之后能做到什么），并为 313 个函数、268 个方法与 158 条术语补上「什么时候用、怎么用、边界在哪」。这些内容的取用方式见[技能包](/skill/)与[面向 AI 代理的出口](/llms.txt)。

> 译文由 [亦幸](https://github.com/hencter) 和 [DeepSeek Harness](https://www.deepseek.com/) 整理，仅供学习参考。Hugo 迭代较快，如与官方英文原文有出入，请以官方文档为准。

## 完成度与范围

上游的全部一级章节均已翻译，并与上游页面 **1:1 对应**：313 页函数参考、268 页方法参考、159 条术语表，以及速查、命令、配置等各章。未纳入正文的只有上游 `news/`（其索引页已译，无 news 正文）与 `_common/` 文档片段目录（片段内容已随引用它的页面内联译出）。

个别页面上游的**默认值由 `code-toggle` 等数据块提供**，本站以文字说明为主；需要精确默认值时请看该页 `source` 指向的官网页面。

## 遇到问题去哪儿

- **构建报错或页面不符合预期** → [故障排查](/troubleshooting/) 按症状分诊；
- **命令行参数不清楚** → [命令](/commands/)；
- **提问与交流** → [Hugo 官方论坛](https://discourse.gohugo.io)（设有中文分类，可在分类列表中查找）。提问前请先读[求助指南](https://discourse.gohugo.io/t/requesting-help/9132)，并附上 `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](https://github.com/hencter/hugozh/blob/main/README.md)。

```bash
# 在仓库根目录执行
hugo server          # 本地预览，默认 http://localhost:1313/
hugo server -D       # 连同草稿一起预览
hugo                 # 生成静态站点到 public/
```

## 版权与免责

- 原文版权归 Hugo 项目及其文档贡献者所有，原文仓库为 [gohugoio/hugoDocs](https://github.com/gohugoio/hugoDocs)。
- 本站译文仅用于学习与交流，不构成对官方文档的替代。
- 如果你是文档作者并希望调整或移除某处译文，请以官方文档为准并联系本站维护者处理。

