使用 OINK 创作优美的内容
使用 OINK 创作优美的内容
《使用 OINK 创作优美的内容》是与 OINK 参考文档配套的动手实战教程。参考文档说明每个参数和组件的用法; 本书则围绕同一个 Starter 站点,从首次本地预览一步步带你完成双语内容创作、外观定制与生产发布。
阅读方式
从第 1 章:跑起第一个站点开始。全书六章沿用同一个 Starter 仓库,依次完成本地预览、新建双语页面、组合正文与组件、定制品牌与首页、选择内容发布形态, 以及上线前的生产构建校验。下方对象索引同时展示了 Book 的出版能力,可用于快速定位书中的插图、 表格、公式与代码示例。
目录
图目录
表目录
- 表 2-1 — 同一个显式顺序被导航、翻页与生成目录共同使用。
- 表 6-1 — 从本地预览到线上部署的四个验证阶段,以及各阶段留给下一步确认的事项。
- 表 A-1 — 同一棵内容树可以生成多种面向不同用途的 Book 输出。
公式目录
示例目录
1 从一个能运行的站点开始
好的教程首先要给读者一个看得见的结果。对 OINK 而言,这个结果是由 Hugo Extended 在本地提供的官方 Starter——此时还没有改标识、配色、语言组合或内容架构。
明确结果
完成本章时,你应该拥有英文、中文、法语首页,可用的 Docs、Blog、Book 路由,本地搜索, 以及颜色模式控件。这条小基线足以在后续工作中区分内容问题、主题问题与部署问题。

安装前置工具
安装 Git、Go 1.27.3 或更高版本,以及 Hugo Extended 0.168.0。样式通过 Hugo Extended 内置的 LibSass 编译,无需额外安装 Sass 编译器或 Node.js。如果基于较早的 Starter 模板创建仓库, 请一并将 GitHub Actions workflow 中的 Hugo 版本更新到 0.168.0。
启动本地预览
真实项目应通过 GitHub 的 Use this template 操作创建仓库。只在本地评估原始模板时, 克隆并启动 Hugo:
打开 Hugo 输出的地址,修改 data/home/en.yaml 里的一句话,再确认浏览器已经显示变更。
一个能对内容修改作出响应的预览,比终端里只显示“服务已启动”更有证明力。
记录基线
在开始定制前,记录四个事实:Hugo 版本、go.mod 中的主题版本、正在评审的 commit,
以及你实际打开的路由。第 2 章会在不丢失这条基线的前提下,把运行中的站点组织成内容树。
完整分层流程见使用 OINK Starter,不采用模板的安装方式见 从零建站。
2 为内容建立结构
对普通站点而言,OINK 不会另外维护一份导航数据库。内容树就是侧栏树,同一个顺序还会驱动翻页器 与 Book 目录。读者不应该对“下一页是什么”得到三个不同答案。
从读者的问题出发
一级分区应使用读者能辨认的任务或主题命名。小型工程站点通常需要上手指南、参考文档、 运维指南与变更记录。只有当一个目录能为若干页面提供有意义的共享上下文时,才应创建它。
继续使用第 1 章的 Starter,保留已有示例。本章在现有 Docs 分区下新增一篇英文页面及其 中文译文。法语可以保持启用;本练习只添加下面两种语言的对页。
搭建内容树
本练习涉及的文件;其它 Starter 文件保持不变
- content/
- docs/
- _index.md已有分区根页
- _index.zh.md已有中文根页
- preview-check.md新增页面
- preview-check.zh.md新增译文
- docs/
按下面的完整内容创建两个文件。分区根页已经存在,不要替换它们。
译文以 .zh.md 后缀放在英文源文件旁边。这两页没有图片或下载资源,使用独立 Markdown
文件即可;页面拥有这些资源时,再使用页面包。
明确写出顺序
现有栏目权重之间留有空档。新页面使用 25,可以插入相邻栏目之间,而不必重新编号;两种译文保持相同权重。新建内容树时,以 10 为间隔也能留下类似空间:
| 项目 | 权重 | 为什么放在这里 |
|---|---|---|
| 快速上手 | 10 | 建立可运行的基线 |
| 创作内容 | 20 | 在可运行站点上继续搭建 |
| 定制站点 | 30 | 在结构之后改变呈现 |
| 运行维护 | 40 | 验证并发布结果 |
建立稳定地址
任何可能被其它页面引用的标题,都要显式写出 ID。英文页面与中文页面虽然显示不同的标题, 却使用同一个 ID。这会让链接、页内目录与整书打印在两种语言中始终对齐。
保持 hugo server 运行,打开 /docs/preview-check/ 与 /zh/docs/preview-check/。
两页都应出现在各自的 Docs 侧栏中,语言切换应打开对应译文;两页标题的锚点均为
#check-preview。保留这两个文件,第 3 章继续修改它们。
3 组合出值得阅读的页面
组件应该帮助论证,而不是与内容争夺注意力。先写普通正文,只有当读者需要比较、验证、复制 或停下来思考时,才引入额外结构。
让每个内容块只做一件事
如果你无法用一句话解释某个组件为什么应该出现在这里, 那就先保留普通正文,直到需求变得明确。
用提示块表达前置条件或风险,用表格对齐重复字段,用代码块放置读者可以执行的材料, 只在形状或空间关系承载了正文无法表达的信息时才使用图片。
从一份小型页面契约开始
继续修改第 2 章的 content/docs/preview-check.zh.md,用下面的完整示例替换内容。
保留预览服务运行,在第二个终端的站点仓库目录中执行页面里的构建命令。
在 preview-check.md 中用英文补上相同任务与命令,保留 weight: 25 和
#check-preview,本地 URL 使用 /docs/preview-check/。标题命名任务,摘要说明结果,
提示块解释命令在哪执行。再次打开双语页面并检查语言切换,再继续添加组件。
不用装饰数量衡量质量
有用的页面需要同时平衡三项独立属性:
这里刻意使用乘法:视觉精美无法弥补错误命令,准确的正文在读者找不到或无法按步骤执行时, 同样会失败。
串联引用与检查
用 示例 3-1 作为源码模式, 再用 公式 3.1 作为评审问题。接下来进入第 4 章:塑造阅读体验,继续定制站点身份、视觉预设与首页布局。
组件参考的起点是组件。只有当教程引入了某项真实需求时, 才需要阅读对应组件的独立页面。
4 塑造阅读体验
设计应该在内容树跑通之后开始。本章在你的 Starter 仓库中把品牌标识、视觉预设、首页编排、 导航层级与双语对齐连成一套完整的阅读体验。
建立视觉层级
先处理标题、导语、正文、层级标题与局部导航。在加入色彩或装饰前,读者就应该明白下一个动作由哪个区域承接。 OINK 提供层级,站点变量提供身份。
打开 Starter 仓库中的 hugo.yaml,修改站点名称、规范 URL、默认视觉预设与品牌强调色:
保存后刷新 http://localhost:1313/。YAML 锚点会一次性更新所有已启用语言的站名,顶栏右侧的外观菜单则允许读者在亮色和暗色模式下自由切换 paper、slate、ink 与 terminal 四套风格。
编排首页
首页由 data/home/ 下的数据文件驱动。YAML 分区列表应讲清楚几件事:项目是什么、面向谁,以及读者下一步可以做什么。
编辑 data/home/zh.yaml,把首屏主按钮指向你在第 2 章和第 3 章编写的验证页面:
保持导航可预期
顶部菜单、外壳根切换器、侧栏、页内大纲与翻页器各自回答不同问题。请在桌面端与移动端同时检查它们, 并确保两种语言显示同一套内容顺序:
- 顶部导航栏(栏目根页的
menus.main):在顶层内容区(Docs、Blog、Book)之间切换。 - 左侧栏(目录树 +
weight):展示当前页面在所属栏目中的位置。 - 右侧页内大纲(页面
##与###标题):在当前页面内部快速跳转。 - 底部翻页器:按侧栏顺序前往上一篇或下一篇。
同时设计两种语言
从一开始就把各语言版本当作对等页面来设计。在 data/home/en.yaml 中同步更新英文首屏配置,让英文读者也能通过相同入口直达 /docs/preview-check/:
注意 url: docs/preview-check/ 使用相对语言根的路径——OINK 会在英文下自动解析为 /docs/preview-check/,在中文下自动解析为 /zh/docs/preview-check/。更多视觉参数与落地页区块用法,请参考品牌与外观、首页与落地页与多语言。
5 发布不止于参考页面的内容
同一个站点可以发布多种知识,而不必把它们强行塞进同一种布局。内容类型选择页面外壳, front matter 变体则在同一外壳内调整呈现。
让内容类型匹配读者
- Docs 回答任务或参考问题,并显示它在内容树中的位置。
- Blog 是带日期、作者、分类法、订阅源与分享能力的文章。
- Case 说明真实站点如何应用主题。
- Book 章节组成有意设计的阅读顺序,并提供稳定交叉引用。
- 发布注记把版本、迁移方法与验证证据连接起来。
配置 Blog 家族
普通 Blog 分区可以选择水平条目(list)、规则卡片(cards)、紧凑表格(table)
或封面画廊(gallery)。OINK 1.4.0 已支持这四种布局。博客布局指南
介绍了配置方法、读者切换与画廊的三种内部排布。
需要沉浸式开场的分区仍然保留同一类型,只改变四个相互独立的呈现键:
这与沉浸式阅读使用的是同一套配置,共享标准的 blog
模板、订阅源与分类页面。
把样例变成 Case 案例
Case 索引采用 Blog 卡片布局;每篇案例页先介绍站点定位、源码仓库、多语言结构、内容规模与所用到的 OINK 特性,再附上线上链接,方便读者在访问外部站点前先了解其实现方式。
让 Book 与 Docs 相互补充
参考页面保持完备,并能独立搜索。教程则从参考中选出一条路径,每次只引入一项决策, 在读者需要完整参数表时再链接回参考文档。
为了体会版本发布公告与常青文档树如何分工协作,可以在 Starter 仓库中新建 content/blog/release/0.2.0.zh.md(及对应的英文 0.2.0.md),并直接链接到第 3 章编写的操作指南:
打开 http://localhost:1313/zh/blog/release/0.2.0/:发布公告负责交代变更在 何时、为何 上线,而 /zh/docs/preview-check/ 则始终作为读者随时查阅的 操作手册。
6 有把握地交付
文档站点的交付通常包含四个阶段:本地预览、锁定或升级主题模块、执行干净的生产构建,以及推送到托管平台上线。 按顺序检查每个阶段,能在构建或部署出错时快速定位原因。
按阶段检查发布流程
| 阶段 | 已验证的内容 | 仍需继续确认的事项 |
|---|---|---|
| 本地预览 | 页面、导航与内容修改可在 hugo server 中正常渲染 |
生产环境 baseURL、草稿过滤与干净的模块状态 |
| 主题模块版本 | hugo mod graph 在 go.mod 与 go.sum 中解析到目标公开标签 |
站点内容与覆盖项能否在该版本下通过生产构建 |
| 生产构建 | 内容、配置与 go.mod 在 --environment production 下构建通过 |
托管平台工作流、CDN 缓存与线上公开路由 |
| 线上部署 | CI 工作流成功完成,主要公开路由均可正常访问 | 代表性页面在桌面端与窄屏下的实际排版表现 |
验证最小且有效的范围
在自己的 Starter 仓库中,先执行一次干净的生产构建,再触发部署工作流:
确认 hugo mod graph 解析到 go.mod 中预期的公开版本,再按Starter 部署步骤操作。
普通 Starter 站点不需要 npm 构建脚本或同级主题目录。如果同时在修改 OINK 主题本身,
可按主题开发流程进行联调。
审阅真正渲染出的结果
自动检查能发现坏链接、重复 ID、无效短代码与无障碍回归,而版面与可读性仍需肉眼审阅。 请在桌面与窄屏宽度下抽查具有代表性的中英文页面,涵盖 Hero 裁切、宽表格、导航、主题切换控件、 代码块以及整书打印视图。
整理发布记录
发起 Pull Request 或升级主题版本时,对照 表 6-1
记录当前使用的 Hugo 版本、go.mod 中的主题版本、构建输出以及抽查过的页面路由。
在变更说明中附上这份简短清单,方便团队审阅与回滚排查。
A Front Matter 模式
这些模式刻意保持精简。先复制建立内容契约所需的字段;只有在真实的读者需求出现时, 才加入额外的展示选项。
Book 栏目根页
根页声明 Book 外壳与生成输出。它不需要章节编号;编号属于阅读顺序中真正出现的内容。
Book 章节
使用 book_status: draft 表达可见的编辑状态。它与 Hugo 的 draft: true 不同:
页面会保留在普通构建中,审阅者仍然可以阅读尚未完成的章节。
沉浸式 Blog 文章
文章仍然属于 Blog 家族,Feed、作者、系列与分享能力都会保留;以上字段只改变阅读呈现。
生成输出矩阵
| 输出 | 范围 | 典型用途 |
|---|---|---|
| HTML | 单个根页或章节 | 阅读、导航与搜索 |
| 完整的 Book | 审阅、打印与 PDF 转换 | |
| markdown | 保留源码结构的 Book | 导出与下游处理 |
Book 根页生成的目录、插图、表格、公式与示例索引会一起证明这些契约。中英文页面必须对齐 显式标题 ID 与对象 ID,确保每种格式都保留相同的引用关系。