分类: 创作内容

一页接口文档由一份 OpenAPI 规范加一个 shortcode 构成。Swagger UI 与 Redoc 两个运行时随主题分发（版本分别是 5.32.13 与 2.5.3，见仓库 VENDOR.json），页面用到才加载，构建与浏览都不访问外部服务。 三个步骤：把规范文件放进 static/，新建一页写上 shortcode，需要专用外壳时把页面 type 改成 swagger。 规范文件的位置 规范文件放在 static/ 下，原样发布到站点根，两个 shortcode 得到的都是浏览器 …

OINK 把发布事实集中在两处本地数据：页面 front matter 的 release_url 指明这一页对应哪个 GitHub 发布，data/download/<key>.yaml 记录安装方式。发布卡片、资产表、下载区块与索引页都从这两处推导。构建期不访问 GitHub，也不声称某个标签或资产已经存在。 本页自带演示用的发布事实 front matter 里放了一个 release_url（OINK v0.4.0），下面的卡片、资产表与下载区块都是真实渲染。校验和与资产文件名是构造的 …

一本书是一棵 type: book 的内容树：目录决定章节顺序，front matter 决定章节编号，图 / 表 / 式 / 例各带一个手写编号与稳定锚点。交叉引用在四种输出里都能解析，书根页面可以生成整本打印 HTML。 前提两条：站点的 markup.goldmark 已开启属性行与 passthrough（见组件总览）；params.ui.shell_types 保留 book（主题默认包含）。 一本书的目录 书根是一个普通的 Hugo section，章是它的子目录，节是章里的页面。没 …

博客文章与文档页的正文写法相同，区别在外壳：文章带日期、作者、标签与封面图，列表按年份倒序排列，栏目带 RSS。本页覆盖博客栏目的建立、文章 front matter、封面图、列表分页与 Feed。 博客目录结构 博客是 content/ 下的一个栏目，type: blog 使它使用博客外壳。子目录按发布方与受众划分，文章平铺其中。不要建年份目录，年份分组由列表页自动生成： 本站的 content/blog/ content/blog/_index.md#type: blog + …

本页是页面级参数的全表，只列 OINK 主题会读取的键。Hugo 自身的 front matter 字段（slug、url、build、sitemap、expiryDate 等）照常可用，语义见 Hugo 文档。站点级参数（hugo.yml 里的 params.*）见配置总览。 表格说明 优先级从高到低： 页面自己的 front matter； 最近一层 cascade（多层 cascade 都设了同一个键时，离页面最近的那一层生效）； hugo.yml 里的站点参数。 「默认」列标「站点值」的 …

本栏覆盖 OINK 支持的几种内容类型：文档页、博客文章、书籍、发布下载页、OpenAPI 参考。它们共用同一套 Markdown 与 front matter，各自另有约定。 一页文档的构成 一页文档是一个 Markdown 文件。文件开头两行 --- 之间是 front matter，即页面元数据：标题、侧栏短名、描述、排序。其余部分是正文，内容为普通 Markdown 加 OINK 的原生组件。下面是一个完整页面： content/docs/install.zh.md --- title: …

OINK 不需要单独配置导航：content/ 下的目录结构就是侧栏树。本页覆盖目录与文件的摆放、栏目首页、排序、图标、折叠、隐藏，以及多根侧栏。 目录就是侧栏 一个目录是一个栏目（Hugo 称 section），目录里的 Markdown 文件是它的页面，嵌套目录是它的子栏目。侧栏按这棵树逐层渲染，顺序由 weight 决定，标签取 linkTitle，缺省时取 title。左侧这棵树的源码如下： content/docs/ 的前两层 content/docs/_index.zh.md#栏目根 …

本页覆盖一页文档的完整写法：文件位置、front matter、标题锚点、链接、图片、草稿与页尾。前提是站点已能本地构建，尚未搭起时先看十分钟上手。 新建一页 页面是 content/ 下的 Markdown 文件，URL 由它在 content/ 里的位置决定：content/docs/install.md 发布为 /docs/install/。中文译文是同目录下的 .zh.md 同名文件，与英文页共享同一条逻辑路径。 没有附带资源的页面写成单个文件。页面带图片、cast、示例配置这类资源时改 …