创作内容
本栏覆盖 OINK 支持的全部内容类型:文档页、博客文章、书籍、Expo 图片相册、发布下载页与 OpenAPI 参考。它们共用同一套 Markdown 与 front matter,各自在此基础上增加专属排版约定。
一页文档的构成
每页文档都是一个独立的 Markdown 文件。文件开头两行 --- 之间是 YAML front matter,用于声明页面元数据(title、linkTitle、description、weight),下方正文直接使用标准 Markdown 与 OINK 原生组件:
存为 content/docs/install.zh.md,运行 hugo server 后页面出现在 /zh/docs/install/,左侧栏会出现「安装」条目。
常用排版速查
日常最常用的组件均基于原生 Markdown 与 Goldmark 属性块,无需记忆复杂的短代码:
| 常用能力 | 写法示例 | 详细指南 |
|---|---|---|
| 显式标题锚点 | ## 前提条件 {#prerequisites} |
编写页面 |
| 提示框 / 折叠块 | > [!NOTE](及 TIP、IMPORTANT、WARNING、CAUTION、DETAILS) |
提示块 |
| 代码标签页 | 相邻代码围栏带 ```bash {tab="macOS"} |
标签页 |
| 步骤列表 | 有序列表紧跟一行 {.steps} |
步骤列表 |
| 导航卡片 | 链接无序列表紧跟一行 {.cards} |
卡片网格 |
| 参数字典表 | Markdown 表格紧跟一行 {.fields} |
参数表 |
| 带图注或尺寸的图片 |  紧跟一行 {width="800" caption="..."} |
图片 |
| 目录文件树 | ```filetree 代码围栏内写缩进列表 |
文件树 |
内容类型与对应页面
| 你要写的 | 去哪页 |
|---|---|
| 一页文档:front matter、标题锚点、链接、图片、草稿 | 编写页面 |
目录树与侧栏:_index.md、weight、图标、折叠、多根侧栏 |
组织内容 |
| 查某个 front matter 键是什么意思 | 页面参数 |
| 一篇博客、发布公告、RSS | 博客与文章 |
| 一本书:章节编号、图表式例、交叉引用、整本打印 | 书籍出版 |
| 图片相册:目录结构、元数据、布局与图片查看器 | Expo 相册 |
| 一个发布下载页:版本卡片、资产表、校验和 | 发布与下载页 |
| 一份 OpenAPI 参考页 | API 文档 |
| 中英双语写作:对等文件、锚点对齐、缺译回退 | 多语言 |
| 某个组件的语法与参数 | 组件总览 |
新建一页文档:文件放在哪、front matter 写什么、标题锚点为什么要手写、链接与图片怎么写、页尾会自动出现什么。
目录结构就是侧栏树:_index.md 与 weight、栏目首页样式、图标与折叠、隐藏页面、把文档放在任意路径。
front matter 全表:主题读取的页面键与 1.x 兼容 no-op,按侧栏、外壳、搜索、输出、页尾、Book、Expo、Landing、发布页分组。
开一个博客栏目:目录约定、文章的 front matter、封面图、按日期排序的列表页与 RSS。
用 type: book 把一棵目录树变成一本书:章节编号、图表式例编号、交叉引用、生成式索引与整本打印。
创建图片相册,补充可选元数据,选择布局,并使用图片查看器。
把版本号、标签、归档链接、校验和与安装命令写成本地事实,再让发布卡片、资产表、下载区块和索引页从同一份记录推导出来。
把 OpenAPI 规范放进站点,用随主题分发的 Swagger UI 或 Redoc 渲染成可浏览的接口文档,不连 CDN。