场景组件 on OINK

顺序阅读与数学公式

Mon, 01 Jan 0001 00:00:00 +0000

Oink 0.4.0 为手册、Book 与博客定义了明确的阅读序列，并把服务端数学公式渲染纳入正式内容路径。

docs、book 与 blog 内容类型默认启用翻页。站点只使用其中一部分时，可以显式替换这个集合：

YAML

params:
  ui:
    pager:
      types: [docs, book, blog]

只允许这三个类型名。页面或分区可以使用布尔型 front matter 退出序列：

YAML

---
pager: false
---

交互式 HTML 只渲染实际存在的上一页或下一页，并在页面 <head> 中添加匹配的 <link rel="prev"> 与 <link rel="next">。print、Markdown 和 RSS 不包含翻页标记或关系。

理解阅读顺序

文档与 Book 按 侧栏同一导航根 做前序遍历：分区首页先于其可见子项，普通子项按 weight 排序。站点使用 data/docs_nav.json 显式定义内容树时，这棵树同时是侧栏与翻页的权威来源。

以下条目可以显示在导航中，但不会成为翻页目的地：

使用 toc_hide 隐藏的页面；
使用 manualLink 或 manualLinkRelref 的纯链接占位页面；
标记为 sidebar_divider: true 的不可点击分组行。

博客保留 Hugo 的分区时间顺序，刻意不沿用手册树顺序。

版本发布与下载

Mon, 01 Jan 0001 00:00:00 +0000

Oink 把不可变的发布事实与呈现方式分开。发布页面拥有版本与仓库身份，本地下载数据拥有分发渠道；卡片、列表、校验和表、文档页与 Landing 页面都从这些记录推导，不必在多个模板中重复复制 URL 与命令。

定义发布事实

在页面 front matter 中添加严格的 release Map：

YAML

release:
  product: Pig
  version: 1.7.0
  repo: pgsty/pig
  tag: v1.7.0
  date: 2026-08-14
  prev: v1.6.0
  checksums: SHA256SUMS

version 与 repo 必填。省略 tag 时推导为 v{version}；省略 date 时使用页面日期。可选的 product、prev 与 checksums 用于补全记录。未知键、错误类型或不符合 owner/name 形式的仓库都会让构建失败。

简单的 GitHub 发布也可以使用精确标签 URL 简写：

YAML

release: https://github.com/pgsty/pig/releases/tag/v1.7.0

Oink 在本地推导仓库、发布、归档、diff、校验和与资产链接。构建时不调用 GitHub，也不会声称某个标签或资产已经远程存在。

Landing 页面

Mon, 01 Jan 0001 00:00:00 +0000

Landing 页面是使用全宽场景外壳的普通 Hugo 内容页。它保留站点顶部导航栏、命令面板与已配置页脚，同时移除文档侧栏和目录栏。内容仍然位于本地并由服务端渲染，不需要前端构建或远程事实 API。

首页继续使用 data/home/<lang>.yaml，但内部已经与普通 Landing 页面共用渲染器与分区契约。

创建 Landing 页面

创建普通内容文件，并指定本地数据键：

YAML

---
title: 定价
layout: landing
landing: pricing
outputs: [HTML, print, markdown]
---

把中英文叙事数据放在独立文件中：

TEXT

data/
└── landing/
    └── pricing/
        ├── en.yaml
        └── zh.yaml

非首页 Landing 按以下顺序解析数据：

直接写在页面 front matter 中的 sections；
data/landing/<key>/<精确语言>.yaml；
data/landing/<key>.yaml 中的精确语言记录；
英文或无后缀的本地记录。

叙事内容优先使用分语言文件。共享事实字段可以依次使用精确语言后缀、主语言后缀与无后缀回退；语言标签中的 - 会规范化为 _。例如先尝试 title_zh_cn，再尝试 title_zh，最后使用 title。不接受 camelCase 后缀别名。

Book 出版

Mon, 01 Jan 0001 00:00:00 +0000

Oink 的 Book 能力扩展现有文档外壳，沿用内容树或 data/docs_nav.json、面包屑导航、翻页与感知输出的组件体系，不会引入第二份章节清单或平行导航实现。

创建 Book 根页面

分区 Book 声明类型、请求所需输出，并把类型级联到后代：

YAML

---
title: 系统手册
type: book
book_kind: book
book_number: B
outputs: [HTML, print, markdown]
cascade:
  type: book
---

即使站点启用了侧栏根切换器，Book 根始终是当前一级分区，因此导航不会泄漏到同级文档或博客。站点覆盖 params.ui.shell_types 时，请保留 book。

必须显式请求 print：Oink 不会擅自给消费站增加昂贵的聚合输出。分区 Book 对应 Hugo 的 section 输出类型；只有 Book 位于站点根时才使用 home：

YAML

outputs:
  section: [HTML, print]
params:
  ui:
    shell_types: [docs, book, blog, swagger]
    sidebar_headings: 3
    book_draft_banner: true

sidebar_headings 接受 false、表示二级标题的 true，或 2 到 4 之间的最大标题层级；它会把当前页的 Hugo fragment 树投射到章节行下。所有需要引用的标题都应使用显式 ID：

场景组件

Mon, 01 Jan 0001 00:00:00 +0000

场景组件解决的是一项完整的出版任务，而不是页面中的一个片段。每种场景都用一套严格契约，协同组织内容、本地数据、导航、运行时加载、无障碍与非 HTML 输出。

它与组件参考互为补充：查单个写作原语时看组件参考；当任务跨越多个页面、文件或输出格式时看本章。

选择场景

场景	适用任务	主要事实来源
顺序阅读	手册、Book 或博客需要可靠的阅读顺序	侧栏/内容树与页面元数据
版本发布与下载	发布事实、资产与安装路径必须保持一致	front matter 与 `data/download/`
Landing 页面	产品页面需要可复用的全宽分区	`data/landing/` 或内联分区数据
Book 出版	长篇内容需要编号、引用与整本打印	既有 Book 内容树与稳定页面 ID

共同保证

本地事实：正常构建不会通过远程 API 获取发布状态、star、价格、截图、头像或其他易变事实。
静态优先：渐进增强前的 HTML 已包含完整内容；页面只加载自己确实使用的 JavaScript。
严格输入：参数、标识符、URL、校验和或数据记录非法时，构建会在对应源码位置失败。
感知输出：HTML、print、Markdown 与 RSS 要么得到明确的呈现，要么有意省略只用于交互的内容。
单一导航事实源：可见内容树同时驱动翻页、Book 目录与整本打印顺序。
多语言安全：共享事实按文档规定的后缀回退；叙事数据可以按语言独立维护。

采用之前

请固定拥有这些契约的最低版本：

require github.com/pgsty/oink v0.4.1

使用 Hugo Extended 0.160.1 或更新版本。一次采用一种场景，构建所有已配置输出，并检查每种语言。本地构建、公开主题标签、站点版本固定与线上部署是不同的证据门禁，不要互相代替。

既有 Oink 站点请先阅读 0.4.0 升级指南。

场景组件 on OINK

顺序阅读与数学公式

启用或收窄翻页范围

理解阅读顺序

版本发布与下载

定义发布事实

Landing 页面

创建 Landing 页面

Book 出版

创建 Book 根页面

场景组件

选择场景

共同保证

采用之前