内容 on OINK

创作内容

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

这一章讲怎么写。可用的组件在组件参考，站点级配置在站点配置。

本章内容

组织内容：内容树、分区、页面包、front matter
写作规范：Markdown 约定、告警、链接、双语写作
图片与媒体：Logo、favicon、图标与图片
分类与标签：taxonomy 配置与多语言支持

组织内容

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

Oink 根据 Hugo 内容树生成文档侧栏，因此目录结构也是读者体验的一部分，而不只是源码组织细节。先明确读者需要解决的问题，再建立能够快速找到答案的最小层级。

从读者目标出发

为新读者提供一条从产品背景到首次成功操作的短路径；为回访读者提供直达操作指南、参考资料与故障排查的入口。一套实用文档通常需要：

说明范围与产品边界的概览；
能得到可运行结果的快速上手路径；
围绕常见工作的任务指南；
参数、API 与兼容性的参考页面；
覆盖常见故障的诊断与恢复说明。

当示例能够直接复制或对比时，它们很有价值，但不应取代解释行为的操作步骤与参考资料。

使用可预测的内容类型

每个页面只聚焦一种读者意图：

内容类型	读者的问题
概览	这是什么，什么时候应该使用？
教程	怎样得到第一个可运行结果？
操作指南	怎样完成一项具体任务？
参考	有哪些字段、命令或接口？
解释	系统为什么采用这种行为？
故障排查	怎样诊断故障并恢复？

不要为了复刻组织架构而建立空的一级目录。只有当多篇页面共享稳定的读者目标时，才增加新的分区。

保持浅层结构

优先使用简短明确的 URL，不要建立过深的分类树。通过页面权重安排学习顺序，并让同一分区的权重保持一致间隔，便于插入新页面。每个可导航页面都应提供图标与精简描述，让侧栏和分区索引便于扫描。

Hugo 页面包与分区模型详见添加内容，侧栏行为详见导航与菜单。

同步规划多语言内容

在同一目录中同时创建英文源页面与简体中文译文。页面顺序、读者意图、示例与稳定标题 ID 应保持一致。两种语言的篇幅不必相同，但必须传达等价信息。

检查完整访问路径

移动或新增页面后，检查文档首页、分区索引、侧栏、面包屑、前后页导航、本地搜索与全部首页链接。发布前应构建两种语言，并验证渲染后的片段链接。

内容根目录

站点内容位于 content/ 目录下。多语言站点既可以分别使用 content/en/、content/zh/ 等内容根目录，也可以在同一棵挂载目录中使用语言后缀。本仓库采用后一种形式：

TEXT

content/docs/content/
├── adding-content.md
└── adding-content.zh.md

英文文件是源页面，.zh.md 文件是对应的简体中文译文。Hugo 解析语言后缀后，二者具有相同的逻辑路径。

Hugo 内容技巧

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

Oink 是一款 Hugo 主题，因此普通 Markdown 与 Hugo 内容模型仍是创作基础。遵循以下约定，可以让页面在翻译、重组或部署到子路径后继续保持清晰与稳定。

链接到发布后的路由

面向读者的链接应指向规范发布 URL，而不是相邻源码文件路径。/zh/docs/content/ 这样的根相对链接便于全站审计。如果链接需要在源码移动后继续跟随目标页面，可以使用 Hugo 的 ref 或 relref 短代码：

MARKDOWN

[站点配置]({{< ref "/docs/configure/overview" >}})

移动页面后，应为旧公开路径添加 alias，并把所有站内链接更新为新的规范路由。不要让 alias 长期承担站点导航职责。链接与图片行为详见添加内容。

让 front matter 提供有效信息

每个可导航页面都需要清晰的 title、精简的 description、经过安排的 weight 与合适的 Font Awesome icon。描述只用一句话，并确保在普通桌面内容卡片中可以单行显示。只有当导航标签确实需要与页面标题不同时，才添加 linkTitle。

英文是主要源语言；简体中文译文以 .zh.md 形式与其并置。面向读者的元数据必须与正文一样认真翻译。

保持标题 ID 稳定

多语言页面或经常被引用的页面应使用显式标题 ID：

MARKDOWN

## 故障恢复 {#failure-recovery}

对应中文标题使用同一个 ID。重命名标题时，只要语义没有改变，就应继续保留已经公开的 ID。

Logo 与图片

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

添加品牌标识

Oink 默认使用 assets/icons/logo.svg 作为品牌图标。通过 params.logo 可以替换它；如果页头应显示完整字标，而不是“图标 + 站点标题”，则设置 params.wordmark：

YAML

params:
  logo: icons/product.svg
  wordmark: images/product-wordmark.svg

两个参数都可以指向 Hugo asset 或公开路径。需要主题处理的文件优先放入 assets/；必须原样复制的文件放入 static/。源 SVG 应紧贴图形边缘裁切，以便页头、侧栏和页脚采用一致尺寸。

品牌字体、尺寸与项目 SCSS 的说明请参阅外观与风格。

使用图标

Oink 内置 Font Awesome Free，并从站点本地提供字体。为页面 front matter 设置 icon，即可给页面及其导航入口提供稳定的视觉提示：

YAML

---
title: 部署站点
---

请使用内置免费图标集中的图标。主题 VENDOR.json 记录了准确的依赖版本；菜单图标规则请参阅导航与菜单。

添加 favicon

Oink 不强制使用某个产品 favicon，而是发现消费端站点 static/ 目录中采用约定名称的文件，并在每个页面中添加对应的 <link> 元素。