# Hugo 中文文档 > Hugo 官方文档全部 19 个一级章节、948 页的社区简体中文翻译(非官方),附英文原文链接,便于对照阅读。 - 站点:https://hugozh.cn/ - 官方上游:https://gohugo.io/(本站译文与上游页面 1:1 对应) - 许可:译文遵循上游 Apache-2.0;站点主题、构建脚本与 AI 技能包为 MIT - 性质:社区维护的**非官方**中文翻译;如有出入,以官方英文原文为准 - 语言:简体中文(zh-CN) ## 这份文档是什么,以及它和官方文档的不同 本站是 Hugo 官方文档的简体中文翻译,但**不止于直译**:在保留上游全部技术细节的前提下,额外补了一层 「教学层」——把官方默认读者已经懂、因而省略的上下文写出来:这个约束为什么存在、这一步做完应该看到什么、 出错时先查哪里。因此同一页对普通读者也能独立完成,不需要外部 AI 辅助。 对人类读者,教学信息渲染成正文开头的「阅读提示」面板(难度 / 预计用时 / 前置 / 读完能做什么 / 接着读); 对机器,同一份信息以引用块出现在该页 Markdown 版本的标题与摘要之后。**两者同源,不会分叉。** ## 分主题入口 - [技能包](https://hugozh.cn/skill/):把建站经验打包给 AI 编码代理:一份可复用的 Hugo 技能包,含 26 个真实踩坑、SEO、多主题、日期与短代码的参考手册。 - [动态](https://hugozh.cn/news/):说清本站「动态」章节的范围——只有这一页索引,没有逐条发布说明——并给出查看官方发布说明的入口与升级前的六步检查清单。 - [方法](https://hugozh.cn/methods/):在模板中使用这些方法:Page、Site、Pages、Resource、Menu 等对象上的方法。 - [函数](https://hugozh.cn/functions/):在模板与原型中使用的全部函数与方法。 - [入门](https://hugozh.cn/getting-started/):从零开始搭建并运行一个 Hugo 站点:快速开始、安装、基本用法、目录结构与配置。 - [内容管理](https://hugozh.cn/content-management/):内容管理章节总览:内容格式、前置元数据、内容组织与页面资源;含本章阅读顺序与最容易配错的几处索引。 - [命令](https://hugozh.cn/commands/):Hugo 命令行界面的整体结构与各命令索引。 - [托管与部署](https://hugozh.cn/host-and-deploy/):把 Hugo 生成的 public/ 变成线上可访问的站点:三条命令行部署路线与十一个托管平台,每页都给出完整步骤、要填的变量与失败排查入口。 - [Hugo Pipes](https://hugozh.cn/hugo-pipes/):用资源管道把 assets 目录里的文件取得、转换、压缩、加指纹并发布出去。本章给出环境依赖、阅读顺序与常见报错的排查入口。 - [Hugo 模块](https://hugozh.cn/hugo-modules/):用模块管理站点的内容、呈现与行为:讲清模块解决什么问题、挂载与导入怎么用,并给出可运行示例、验证方法与常见坑。 - [模板](https://hugozh.cn/templates/):用模板把内容、资源与数据渲染为发布页面:本章给出完整学习路径,每页都带最小可运行示例与可检验的验证方法。 - [渲染钩子](https://hugozh.cn/render-hooks/):用模板覆盖 Markdown 元素到 HTML 的转换:模板放在哪里、怎么命名、能输出什么,以及配错时该怎么查。 - [短代码](https://hugozh.cn/shortcodes/):Hugo 内置短代码总览:标准记法与 Markdown 记法的渲染顺序差异、参数规则、12 个内置短代码的参数与输出,示例可直接复制到自己的站点。 - [可运行示例](https://hugozh.cn/examples/):本站的示例不是贴出来的代码:每个示例都是 layouts 里真实执行的模板,输出由构建时现场产出;声明与参数写在内容页的前置元数据里,新增示例只改 content。 - [配置](https://hugozh.cn/configuration/):Hugo 配置怎么组织、按什么顺序查找与合并、如何按环境覆盖;含「改了没生效」的排查路径与常见坑。 - [安装](https://hugozh.cn/installation/):Hugo 的发行版差异、各平台安装方式、从源码构建、验证安装与升级方法,以及装不上或装错时怎么排查。 - [故障排查](https://hugozh.cn/troubleshooting/):构建失败、页面缺失或输出不对时的分诊台:先按症状定位,再按「可能原因 → 怎么确认 → 怎么修」处理,并给出本章的阅读顺序。 - [关于](https://hugozh.cn/about/):介绍 Hugo 的定位与特性、隐私保护、许可说明与安全模型。 - [速查](https://hugozh.cn/quick-reference/):Hugo 常用语法、配置与术语的速查索引。 - [工具](https://hugozh.cn/tools/):创建与管理 Hugo 站点的第三方工具:编辑器插件、可视化 CMS、站内搜索与迁移工具的选型、最小可用步骤与验证方法。 - [参与贡献](https://hugozh.cn/contribute/):参与 Hugo 项目与该中文文档站的三条路径:开发、文档、主题;先分清「改哪个仓库」,再按最小可验证的步骤提交第一个拉取请求。 ## 机器可读资源 - **首选**:每个内容页(含首页与各章节首页)都有 Markdown 版本,在页面 URL 后接 `index.md`, 例如 https://hugozh.cn/methods/page/section/index.md ;首页为 https://hugozh.cn/index.md - 全站页面清单(JSON):https://hugozh.cn/pages.json 字段:url / markdown / kind / title / description / section / sectionTitle / source / lastmod / role / difficulty / time / hasTeach / prereqCount / outcomeCount / hasSignature - 全站页面清单(XML):https://hugozh.cn/sitemap.xml - 订阅源:https://hugozh.cn/index.xml - 技能包(供 AI 编码代理使用的 Hugo 作业手册):https://hugozh.cn/skill/ - 技能包正文(Markdown):https://hugozh.cn/skill/SKILL.md - 技能包安装提示词(纯文本,复制给代理即可):https://hugozh.cn/skill/INSTALL-PROMPT.txt - 技能包踩坑清单(G1–G28,Markdown):https://hugozh.cn/skill/references/gotchas.md - 技能包清单(含每个文件的 sha256,13 个文件):https://hugozh.cn/skill/skill-manifest.json ## 页面角色(决定「怎么用这一页」) `pages.json` 的 `role` 字段给出机器可读的页面定位,用于决定是「照做」还是「查阅」: | role | 含义 | 建议用法 | | --- | --- | --- | | `tutorial` | 上手教程、安装、故障排查 | 按小标题顺序执行;每步都有「验证标准」,先满足再继续 | | `guide` | 流程/指南型章节页 | 找对应小节,取可运行示例后按需改写 | | `reference` | 函数 / 方法 / 命令 / 配置 | 查签名、参数、返回值与边界;不要凭签名臆测行为 | | `query` | 术语表与速查条目 | 对齐中英术语、取一行结论 | | `index` | 章节首页 | 拿本章范围与推荐阅读顺序 | `difficulty` / `time` / `hasTeach` 来自页面自身的教学块(与 HTML 面板同源):`hasTeach` 为真表示 该页有成体系的前置与目标说明,适合作为「先读这一页」的入口。 ## 抓取建议 - 优先取 `.md`:HTML 页面含完整导航(术语页里侧栏约占全文 2/3),Markdown 版本只有正文。 - 若必须解析 HTML:正文容器是 `main#main` 或 `article.doc`;函数与方法页的「签名/返回类型」在 `
` 内,位于 `.doc-body` **之外**,只抽 `.doc-body` 会丢签名; 教学面板是 `
`,同样位于 `.doc-body` 之外。 - 建立全站映射只需一次请求:取 `pages.json`(约 950 条,未压缩约 460 KB,gzip 后约 50 KB), 不要逐页猜路径。 - 技能包下的文件是**静态 Markdown / 纯文本**,直接 GET 即可,不要按 HTML 解析: 响应头是 `Content-Type: text/markdown; charset=utf-8`(`.txt` 为 `text/plain`、 清单为 `application/json`),没有 `Content-Disposition: attachment`,因此浏览器会内联显示原文。 想一次拿全 13 个文件与其哈希,读 `skill/skill-manifest.json` 的 `files[]`。 - 引用建议格式:`标题(Hugo 中文文档)· 更新于 YYYY-MM-DD · 官方原文 `。 ## 内容约定(便于切分与引用) - 每页正文从二级标题开始(页面标题由 front matter 提供,不在正文重复)。 - 代码块使用围栏并标注语言;函数与方法页在正文开头给出「签名 / 返回类型」结构化信息。 - 每页给出官方英文原文链接与最近更新时间(来自 Git 提交)。 - 术语表条目按术语排列,标题形如「中文(english)」,便于对齐英文检索词。 - 教学型页面在 Markdown 里同样使用固定小节名:「目标」「开始之前」「验证」「常见坑」「下一步」, 可按这些标题直接定位,不必先读全文。