跳转到主要内容

使用 OINK 创作优美的内容

一本实战教程:用 OINK 创作清晰、优美且易于维护的技术内容。

使用 OINK 创作优美的内容

一本实战教程:用 OINK 创作清晰、优美且易于维护的技术内容。

《使用 OINK 创作优美的内容》是与 OINK 参考文档配套的动手实战教程。参考文档说明每个参数和组件的用法; 本书则围绕同一个 Starter 站点,从首次本地预览一步步带你完成双语内容创作、外观定制与生产发布。

阅读方式

从第 1 章:跑起第一个站点开始。全书六章沿用同一个 Starter 仓库,依次完成本地预览、新建双语页面、组合正文与组件、定制品牌与首页、选择内容发布形态, 以及上线前的生产构建校验。下方对象索引同时展示了 Book 的出版能力,可用于快速定位书中的插图、 表格、公式与代码示例。

目录

图目录

  1. 图 1-1 — 文档站效果示意。你的 Starter 预览使用中性示例内容;第一个里程碑是能打开并修改的站点。

表目录

  1. 表 2-1 — 同一个显式顺序被导航、翻页与生成目录共同使用。
  2. 表 6-1 — 从本地预览到线上部署的四个验证阶段,以及各阶段留给下一步确认的事项。
  3. 表 A-1 — 同一棵内容树可以生成多种面向不同用途的 Book 输出。

公式目录

  1. 公式 3.1 — 清晰度、准确性或一致性中任何一项降为零,整个页面就会失败。

示例目录

  1. 示例 3-1 — 同一页面现在明确了前置条件、命令与可见结果。

1 从一个能运行的站点开始

安装前置工具,启动本地预览,在调整设计前先建立可见的基线。

好的教程首先要给读者一个看得见的结果。对 OINK 而言,这个结果是由 Hugo Extended 在本地提供的官方 Starter——此时还没有改标识、配色、语言组合或内容架构。

明确结果

完成本章时,你应该拥有英文、中文、法语首页,可用的 Docs、Blog、Book 路由,本地搜索, 以及颜色模式控件。这条小基线足以在后续工作中区分内容问题、主题问题与部署问题。

OINK 文档站首页示意
图 1-1 文档站效果示意。你的 Starter 预览使用中性示例内容;第一个里程碑是能打开并修改的站点。

安装前置工具

安装 Git、Go 1.27.3 或更高版本,以及 Hugo Extended 0.168.0。样式通过 Hugo Extended 内置的 LibSass 编译,无需额外安装 Sass 编译器或 Node.js。如果基于较早的 Starter 模板创建仓库, 请一并将 GitHub Actions workflow 中的 Hugo 版本更新到 0.168.0。

$ go version
go version go1.27.3 darwin/arm64
$ hugo version
hugo v0.168.0+extended+withdeploy darwin/arm64

启动本地预览

真实项目应通过 GitHub 的 Use this template 操作创建仓库。只在本地评估原始模板时, 克隆并启动 Hugo:

$ git clone https://github.com/pgsty/oink-starter.git my-docs
$ cd my-docs
$ hugo server

打开 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新增译文

按下面的完整内容创建两个文件。分区根页已经存在,不要替换它们。

content/docs/preview-check.md
---
title: Verify a local preview
description: Check that a documentation edit reaches the browser.
weight: 25
---

## Check the preview {#check-preview}

Open this page locally, change this sentence, and confirm the browser updates.
content/docs/preview-check.zh.md
---
title: 验证本地预览
description: 确认文档修改已经显示在浏览器中。
weight: 25
---

## 检查预览 {#check-preview}

在本地打开本页,修改这句话,再确认浏览器已显示新内容。

译文以 .zh.md 后缀放在英文源文件旁边。这两页没有图片或下载资源,使用独立 Markdown 文件即可;页面拥有这些资源时,再使用页面包。

明确写出顺序

现有栏目权重之间留有空档。新页面使用 25,可以插入相邻栏目之间,而不必重新编号;两种译文保持相同权重。新建内容树时,以 10 为间隔也能留下类似空间:

项目 权重 为什么放在这里
快速上手 10 建立可运行的基线
创作内容 20 在可运行站点上继续搭建
定制站点 30 在结构之后改变呈现
运行维护 40 验证并发布结果
表 2-1 同一个显式顺序被导航、翻页与生成目录共同使用。

建立稳定地址

任何可能被其它页面引用的标题,都要显式写出 ID。英文页面与中文页面虽然显示不同的标题, 却使用同一个 ID。这会让链接、页内目录与整书打印在两种语言中始终对齐。

保持 hugo server 运行,打开 /docs/preview-check/ 与 /zh/docs/preview-check/。 两页都应出现在各自的 Docs 侧栏中,语言切换应打开对应译文;两页标题的锚点均为 #check-preview。保留这两个文件,第 3 章继续修改它们。

完整规则见编写页面与组织内容。

3 组合出值得阅读的页面

把正文、提示块、代码、媒体、表格与数学公式组合在一起,而不把页面变成组件目录。

组件应该帮助论证,而不是与内容争夺注意力。先写普通正文,只有当读者需要比较、验证、复制 或停下来思考时,才引入额外结构。

让每个内容块只做一件事

先写出那句话

如果你无法用一句话解释某个组件为什么应该出现在这里, 那就先保留普通正文,直到需求变得明确。

用提示块表达前置条件或风险,用表格对齐重复字段,用代码块放置读者可以执行的材料, 只在形状或空间关系承载了正文无法表达的信息时才使用图片。

从一份小型页面契约开始

继续修改第 2 章的 content/docs/preview-check.zh.md,用下面的完整示例替换内容。 保留预览服务运行,在第二个终端的站点仓库目录中执行页面里的构建命令。

示例 3-1 同一页面现在明确了前置条件、命令与可见结果。
content/docs/preview-check.zh.md
---
title: 验证本地预览
description: 确认文档修改已显示在浏览器中,构建成功并完成告警审阅。
weight: 25
---

## 检查预览 {#check-preview}

> [!NOTE] 保持预览服务运行
> 在第二个终端中进入站点仓库,再执行下方构建。

```bash
hugo --environment production
```

命令应正常退出。刷新本页
`http://localhost:1313/zh/docs/preview-check/`,确认新提示块与命令已显示在浏览器中。

在 preview-check.md 中用英文补上相同任务与命令,保留 weight: 25 和 #check-preview,本地 URL 使用 /docs/preview-check/。标题命名任务,摘要说明结果, 提示块解释命令在哪执行。再次打开双语页面并检查语言切换,再继续添加组件。

不用装饰数量衡量质量

有用的页面需要同时平衡三项独立属性:

Q=Cclarity×Aaccuracy×Kconsistency Q = C_{clarity} \times A_{accuracy} \times K_{consistency}
公式 3.1 清晰度、准确性或一致性中任何一项降为零,整个页面就会失败。

这里刻意使用乘法:视觉精美无法弥补错误命令,准确的正文在读者找不到或无法按步骤执行时, 同样会失败。

串联引用与检查

用 示例 3-1 作为源码模式, 再用 公式 3.1 作为评审问题。接下来进入第 4 章:塑造阅读体验,继续定制站点身份、视觉预设与首页布局。

组件参考的起点是组件。只有当教程引入了某项真实需求时, 才需要阅读对应组件的独立页面。

4 塑造阅读体验

把稳固的内容结构变成一份可辨识、响应式且双语对齐的出版物。

设计应该在内容树跑通之后开始。本章在你的 Starter 仓库中把品牌标识、视觉预设、首页编排、 导航层级与双语对齐连成一套完整的阅读体验。

建立视觉层级

先处理标题、导语、正文、层级标题与局部导航。在加入色彩或装饰前,读者就应该明白下一个动作由哪个区域承接。 OINK 提供层级,站点变量提供身份。

打开 Starter 仓库中的 hugo.yaml,修改站点名称、规范 URL、默认视觉预设与品牌强调色:

hugo.yaml
title: &siteTitle Acme Docs
baseURL: https://docs.acme.example/

params:
  ui:
    preset: paper
    preset_menu: [paper, slate, ink, terminal]
    dark_mode: true
    theme_color: '#245f94'
    typography: system

保存后刷新 http://localhost:1313/。YAML 锚点会一次性更新所有已启用语言的站名,顶栏右侧的外观菜单则允许读者在亮色和暗色模式下自由切换 paper、slate、ink 与 terminal 四套风格。

编排首页

首页由 data/home/ 下的数据文件驱动。YAML 分区列表应讲清楚几件事:项目是什么、面向谁,以及读者下一步可以做什么。

编辑 data/home/zh.yaml,把首屏主按钮指向你在第 2 章和第 3 章编写的验证页面:

data/home/zh.yaml
sections:
  - hero
  - cards
  - cta

hero:
  align: center
  eyebrow: Acme · 开源工程文档
  title_lines:
    - words: [{ text: 清晰可靠的 }]
    - words: [{ text: Acme 运维指南。 }]
  lead: 通过可直接复制的示例,在生产环境中安装、配置并运行 Acme。
  actions:
    - label: 验证本地预览
      url: docs/preview-check/
      icon: fa-solid fa-rocket
      style: primary
    - label: 浏览文档
      url: docs/
      style: ghost

保持导航可预期

顶部菜单、外壳根切换器、侧栏、页内大纲与翻页器各自回答不同问题。请在桌面端与移动端同时检查它们, 并确保两种语言显示同一套内容顺序:

  • 顶部导航栏(栏目根页的 menus.main):在顶层内容区(Docs、Blog、Book)之间切换。
  • 左侧栏(目录树 + weight):展示当前页面在所属栏目中的位置。
  • 右侧页内大纲(页面 ## 与 ### 标题):在当前页面内部快速跳转。
  • 底部翻页器:按侧栏顺序前往上一篇或下一篇。

同时设计两种语言

从一开始就把各语言版本当作对等页面来设计。在 data/home/en.yaml 中同步更新英文首屏配置,让英文读者也能通过相同入口直达 /docs/preview-check/:

data/home/en.yaml
hero:
  eyebrow: Acme · Open Source Documentation
  title: Clear operational guides for Acme.
  lead: Install, configure, and run Acme in production with copy-ready examples.
  actions:
    - label: Verify Local Preview
      url: docs/preview-check/
      icon: fa-solid fa-rocket
      style: primary
    - label: Browse Docs
      url: docs/
      style: ghost

注意 url: docs/preview-check/ 使用相对语言根的路径——OINK 会在英文下自动解析为 /docs/preview-check/,在中文下自动解析为 /zh/docs/preview-check/。更多视觉参数与落地页区块用法,请参考品牌与外观、首页与落地页与多语言。

5 发布不止于参考页面的内容

用 Docs、Blog、Case、Book 与发布页面分别回答读者的不同需求。

同一个站点可以发布多种知识,而不必把它们强行塞进同一种布局。内容类型选择页面外壳, front matter 变体则在同一外壳内调整呈现。

让内容类型匹配读者

  • Docs 回答任务或参考问题,并显示它在内容树中的位置。
  • Blog 是带日期、作者、分类法、订阅源与分享能力的文章。
  • Case 说明真实站点如何应用主题。
  • Book 章节组成有意设计的阅读顺序,并提供稳定交叉引用。
  • 发布注记把版本、迁移方法与验证证据连接起来。

配置 Blog 家族

普通 Blog 分区可以选择水平条目(list)、规则卡片(cards)、紧凑表格(table) 或封面画廊(gallery)。OINK 1.4.0 已支持这四种布局。博客布局指南 介绍了配置方法、读者切换与画廊的三种内部排布。

需要沉浸式开场的分区仍然保留同一类型,只改变四个相互独立的呈现键:

type: blog
featured_image: hero
toc_style: flow
toc_taxonomies: false
sidebar_enabled: false

这与沉浸式阅读使用的是同一套配置,共享标准的 blog 模板、订阅源与分类页面。

把样例变成 Case 案例

Case 索引采用 Blog 卡片布局;每篇案例页先介绍站点定位、源码仓库、多语言结构、内容规模与所用到的 OINK 特性,再附上线上链接,方便读者在访问外部站点前先了解其实现方式。

让 Book 与 Docs 相互补充

参考页面保持完备,并能独立搜索。教程则从参考中选出一条路径,每次只引入一项决策, 在读者需要完整参数表时再链接回参考文档。

为了体会版本发布公告与常青文档树如何分工协作,可以在 Starter 仓库中新建 content/blog/release/0.2.0.zh.md(及对应的英文 0.2.0.md),并直接链接到第 3 章编写的操作指南:

content/blog/release/0.2.0.zh.md
---
title: Acme 0.2.0
date: 2026-10-28
description: 新增本地预览校验指南与中英双语首页直达入口。
tags: [发布, 预览]
---

Acme 0.2.0 在生产构建流程前加入了可重复执行的本地预览检查。

## 主要内容 {#highlights}

- 新增[验证本地预览](/zh/docs/preview-check/)操作指南。
- 更新中英文首页首屏按钮,支持一键直达验证流程。

打开 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 工作流成功完成,主要公开路由均可正常访问 代表性页面在桌面端与窄屏下的实际排版表现
表 6-1 从本地预览到线上部署的四个验证阶段,以及各阶段留给下一步确认的事项。

验证最小且有效的范围

在自己的 Starter 仓库中,先执行一次干净的生产构建,再触发部署工作流:

hugo --cleanDestinationDir --gc --minify --environment production \
  --printPathWarnings

确认 hugo mod graph 解析到 go.mod 中预期的公开版本,再按Starter 部署步骤操作。 普通 Starter 站点不需要 npm 构建脚本或同级主题目录。如果同时在修改 OINK 主题本身, 可按主题开发流程进行联调。

审阅真正渲染出的结果

自动检查能发现坏链接、重复 ID、无效短代码与无障碍回归,而版面与可读性仍需肉眼审阅。 请在桌面与窄屏宽度下抽查具有代表性的中英文页面,涵盖 Hero 裁切、宽表格、导航、主题切换控件、 代码块以及整书打印视图。

整理发布记录

发起 Pull Request 或升级主题版本时,对照 表 6-1 记录当前使用的 Hugo 版本、go.mod 中的主题版本、构建输出以及抽查过的页面路由。 在变更说明中附上这份简短清单,方便团队审阅与回滚排查。

完整的运维参考见预览站点、 部署站点与排查构建问题。

A Front Matter 模式

可复制调整的 Book 根页、章节、沉浸式 Blog 文章与整书输出契约。

这些模式刻意保持精简。先复制建立内容契约所需的字段;只有在真实的读者需求出现时, 才加入额外的展示选项。

Book 栏目根页

type: book
book_kind: book
outputs: [HTML, print, markdown]
cascade:
  type: book
  book_draft_banner: true

根页声明 Book 外壳与生成输出。它不需要章节编号;编号属于阅读顺序中真正出现的内容。

Book 章节

book_kind: chapter
book_number: 1
book_status: draft
weight: 10

使用 book_status: draft 表达可见的编辑状态。它与 Hugo 的 draft: true 不同: 页面会保留在普通构建中,审阅者仍然可以阅读尚未完成的章节。

沉浸式 Blog 文章

type: blog
authors: [oink, vonng]
featured_image: hero
toc_style: flow
toc_taxonomies: false
sidebar_enabled: false

文章仍然属于 Blog 家族,Feed、作者、系列与分享能力都会保留;以上字段只改变阅读呈现。

生成输出矩阵

输出 范围 典型用途
HTML 单个根页或章节 阅读、导航与搜索
print 完整的 Book 审阅、打印与 PDF 转换
markdown 保留源码结构的 Book 导出与下游处理
表 A-1 同一棵内容树可以生成多种面向不同用途的 Book 输出。

Book 根页生成的目录、插图、表格、公式与示例索引会一起证明这些契约。中英文页面必须对齐 显式标题 ID 与对象 ID,确保每种格式都保留相同的引用关系。