# 场景组件

> 使用本地内容与数据，配置完整的顺序阅读、版本发布、Landing 页面与 Book 出版流程。

---

LLMS index: [llms.txt](/zh/llms.txt)

---

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

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

## 选择场景 {#choose-a-scenario}

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

## 共同保证 {#shared-guarantees}

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

## 采用之前 {#before-adoption}

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

```go
require github.com/pgsty/oink v0.4.1
```

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

既有 Oink 站点请先阅读 [0.4.0 升级指南](/zh/docs/upgrade/v0-4/)。

---

Section pages:

- [顺序阅读与数学公式](/zh/docs/scenarios/reading/): 配置文档、Book 与博客共用的翻页体系，并使用本地服务端 KaTeX 渲染数学公式。
- [版本发布与下载](/zh/docs/scenarios/releases/): 在不调用远程 API 的前提下，让发布事实、归档链接、校验和以及滚动/固定版本下载渠道保持一致。
- [Landing 页面](/zh/docs/scenarios/landing/): 使用本地、多语言数据与 Oink 严格校验的分区注册表，组合可复用的全宽产品页面。
- [Book 出版](/zh/docs/scenarios/book/): 使用同一棵导航树、编号组件、稳定交叉引用、生成式索引与整本打印 HTML 出版长篇内容。