Oink 发布注记

• 1: Oink 0.6.0：沉浸式博客、更稳健的构建、更精简的内部实现
• 2: Oink 0.5.0 — 组件 API v5 与收敛后的配置
• 3: Oink 0.4.0 — 面向完整发布流程的场景组件体系
• 4: Oink 0.3.0 — 写作、导航与更轻的页面
• 5: Oink 0.2.0：更丰富的内容与更精致的呈现
• 6: Oink 0.1.0：稳定的本地优先基础

1 - Oink 0.6.0：沉浸式博客、更稳健的构建、更精简的内部实现

Oink 0.6.0 保留 0.5 确立的组件 API，集中改进它周围的系统：长文阅读、博客发现、 来源标注、版本发布、构建韧性，以及主题自身的可维护性。

本版本没有新增 article 类型，也没有第二套页面外壳。沉浸式阅读只是现有博客外壳的 一种配置，因此文章仍处于原有列表、订阅源、分类、系列与翻页序列中。

概览

• 博客外壳新增全幅 hero 题图和随正文起步的流式大纲轨道。
• 博客发布新增作者主页与署名、系列顺序、列表/卡片/表格三种索引，以及本地优先分享条。
• 引入页面与译文可选用经过校验的来源标注。
• 主题不再调用 errorf：普通预览告警并安全降级，发布构建继续由 --panicOnWarning 严格把关。
• 发布信息收敛为一个 release_url，不再重复维护一张事实表。
• 重复模板计算、页面 bundle 和测试构建显著减少；Font Awesome 等公共创作资产不做裁剪。

沉浸式博客呈现

沉浸式页面由四个相互独立的 front matter 键组成：

featured_image: hero
toc_style: flow
toc_taxonomies: false
sidebar_enabled: false

把同样的键放入栏目 cascade，即可作用于其中的文章。若栏目索引本身也要采用这种呈现， 还应在栏目自己的 _index.md 上声明一次，因为 cascade 不作用于声明它的页面。

hero 把解析后的题图铺在开篇背后，并在正文开始前渐隐。常规导航栏仍然可用， 叠在图片上时带有渐隐蒙版。toc_style: flow 让大纲从正文起点开始，滚动后再吸附； toc_taxonomies: false 则移除轨道中的分类词云。 博客外壳默认不显示面包屑；需要时可在页面或 cascade 中设置 breadcrumb: true。

这些开关可以独立使用。没有图片时回到普通开篇；没有大纲且关闭词云时不渲染空轨道。 页面的博客归属与输出格式均不改变。

博客补完

题图

params.ui.featured_image 与页面键 featured_image 支持：

所有模式都复用列表缩略图与社交元数据使用的代表图片解析器。没有图片是合法状态， 非 HTML 输出继续保留静态、接近源码的形态。

作者

声明 taxonomies: {author: authors} 即可启用。作者 term 页就是作者主页： 标题是姓名，摘要与正文是简介，代表图片是头像。文章通过 authors: [vonng, oink] 指定作者，书写顺序会被保留。未使用该 taxonomy 时， 旧的 author: 字符串仍作为兼容回退。

系列

声明 taxonomies: {series: series} 即可启用。文章通过 series 加入一个或多个系列， 并可设置 series_weight。带权重的成员按权重升序排列，未加权成员随后按日期升序排列。 文章条带与系列 term 页共用同一个解析器，因此篇次与归档顺序不会漂移。

三种索引形态

列表与卡片共用年份分组与分页。单独发布的表格是完整、不分页的归档；开启读者切换后， 三种形态共用当前分页切片，不会在每个分页页重复整张归档。配置决定首屏形态， 本地偏好可以覆盖它。

分享

params.ui.share 是一个有序列表，可选 x、bluesky、mastodon、 facebook、linkedin、reddit、hackernews、telegram、 whatsapp、line、pinterest、weibo、chatgpt、claude、 email、copy。默认空列表；share: false 可关闭某一页。

分享条只使用平台意图链接与本地复制动作，不加载平台 SDK、iframe、计数器或第三方样式。

页面标注

upstream_link 是每页的来源 URL。配套事实包括 upstream_name、 upstream_copyright、upstream_license、upstream_notice、 upstream_ref 与 upstream_modified，可来自站点参数、data/upstreams 条目或 front matter。

事实不完整、许可证未知、URL 不安全或类型错误时，主题会告警并省略整行标注； 严格构建会拒绝该告警。upstream_link: "" 可让某页明确退出继承的来源标注。

params.ui.translation_notice 可选地指定权威语言。主题不会把它强加到页面 front matter 中；原生撰写的页面可用 translation_notice: false 退出。

告警替代预览宕机

主题中已经没有 errorf 调用。简单标量由 validate.html 统一校验， 组件自身的记录与标记仍由最了解它们的代码校验。

非法输入遵循同一条规则：

1. 告警并说明坏值以及安全回退或省略方式；
2. 不输出不安全、错误或容易误导的结果；
3. 普通 hugo server 继续工作；
4. --panicOnWarning 在 CI 与发布阶段阻止构建。

这样既保留严格门禁，也不会让单页笔误拖垮所有预览 URL。

大纲轨道

大纲在同一条 SVG 路径上显示可见范围与当前光标。光标携带 aria-current="location"；在减少动画或不支持注册属性的浏览器中， 它会安全回退，不会与高亮线脱节。

修复与精简

• 挂载内容不再把构建机路径写入编辑、历史或新建子页链接。
• data-* 与 aria-* 取值统一由一个 HTML 转义器输出。
• Algolia 凭据不完整时，不再渲染容器、CSS 或 JavaScript。
• Draw.io 只在页面存在 PNG/SVG 候选图时加载，同一 URL 只检查一次。
• 页面动作、翻页状态、语言目标与栏目子页按页面或站点复用结果，不再反复扫描全站。
• 不依赖语言的 feature bundle 可在不同语言页面之间共享。
• Fields 锚点由字段名派生，并在页内保持唯一。
• 打印聚合为标题与脚注增加命名空间，而常规页面 ID 不变。
• 非法输入 checker 把等价案例合并后，内容组件阶段启动 Hugo 的次数从 160 次降至 6 次， 同时保留每一条告警与回退断言。
• 已删除过期 CSS、i18n 键、废弃的独立 Article 外壳产物、重复 checker 代码和叙事式代码注释； 完整的 Font Awesome 支持范围保持不变。

配置

默认 shell 与 pager 类型列表在适用处仍由 docs、book、blog、swagger 组成，没有新增 article 类型。

迁移

从 0.5 升级时：

1. 若不希望使用 ISO 日期，请保留显式的本地化日期格式。
2. 确认发布命令带有 --panicOnWarning。
3. 把旧 release map 改为 release_url: https://github.com/<owner>/<repo>/releases/tag/<tag>。
4. 把 upstream_attribution 改为 upstream_link， 把 downstream_modified 改为 upstream_modified。
5. 不要把内容迁移为 type: article，请使用上文的博客呈现键。

迁移工具只自动处理 content Markdown 与受支持的 YAML front matter； 站点配置映射仍由维护者明确完成。从 0.4 升级时，继续执行既有顺序： report、migrate --write、check。

验证

0.6.0 正式版经过以下验证：

• Hugo Extended 0.160.1 与 0.164.0；
• 40 个 HTML/打印/Markdown/RSS/LLMS Golden；
• 85 个迁移测试与 38 个浏览器运行时测试；
• 严格示例站、Hugo Module、system 字体、旧字体覆盖与非法配置构建；
• 双语项目站构建及其非浏览器回归；
• 代表性大站性能测量与真实 EN/ZH 浏览器检查。

本地验证、提交、打标签、推送、消费站锁定与部署仍然是不同的发布状态。

完整变更集

v0.5.0 到 v0.6.0

2 - Oink 0.5.0 — 组件 API v5 与收敛后的配置

Oink 0.5.0 是 API 冻结版本。它包含 1.0 线将要冻结的全部变更：组件 API v5 （原生 Markdown 形态优先，29 个 shortcode 作为完整形态）、按三条规则收敛的配置键与 front matter 键、主题产出物统一的命名空间、0.x 兼容层与无人使用的 Docsy 遗留物的 删除，以及能把 0.4 站点改写到位的迁移工具。任何被退役的键、形态或 shortcode 都会让构建失败，并在错误信息里给出替代写法。

对每一个 0.4 站点来说这都是破坏性升级。请先看概览， 再看迁移指南；中间的参考章节逐项列出每一处变化的新旧形态。

概览

• 内容：大多数组件直接用 Markdown 写——> [!TYPE] 提示块、{.steps} / {.cards} 列表、{.fields} / {.matrix} / {caption=} / {#id num=} / {tab=} 表格、```filetree / ```gallery / ```echarts / ```infographic / ```checksums 数据围栏、相邻代码围栏成标签页、 带属性行的 Markdown 图片。0.4.2 的 53 个 shortcode 中 32 个删除或改名、8 个新增， 剩下 29 个作为完整形态。scripts/migrations/oink06.py 负责改写内容。
• 配置：三条规则——开关就是裸的特性名、单键 map 压平、front matter 键 = 站点键去掉 ui.。约四十个键改名或改形，每个旧键都会让构建失败并指出替代。 主题的全部默认值都声明在主题的 hugo.yaml 里。
• Front matter：不再有 ui: 块；页面覆盖用裸键（section_index: cards）， page_context_menu 与站点 map 同形，manualLink* 改为 manual_link*， hide_* / exclude_search 删除。
• 命名空间：主题 class 一律 td-*、data 属性 data-td-*、自定义属性 --td-*、 JS 全局 Oink*；oink-* 一族和 Docsy 遗留（leaf、has-child、nav-* …） 消失。提示块文案改为 callout_* i18n 键。
• 删除：home/** 适配 partial、outputformat.html、td/render-heading.html、 Docsy community 页面与 params.links、td/code-dark / td/color-adjustments-dark / td/gcs-search-dark / td/extra 这些 Sass 文件、.td-box* 与 -bg-* 调色 class、 Prism、Open Sans、click-to-copy.js、swaggerui（改名 swagger）。
• 行为：标题带自链接；print 内容每次构建只渲染一次（修了一个真实的竞态）； 三个可缓存的 JS bundle；print 页面加载 8 KB JS 而不是 100 KB；shell 动效在结构上 遵守 reduced-motion；giscus 调色板随主题发布并且只在渲染评论的页面加载。
• 迁移：内容与 front matter 走 oink06.py report → migrate --write → check， 然后构建——报错就是配置清单。
• 发布加固：API 冻结前进行了两轮对抗性评审，修复了客户端命名空间迁移、 动作注册表加载顺序、迁移输入 fail-closed、多实例 OpenAPI 嵌入、通用属性与图片 URL 策略，以及消费站配置预检。

组件 API v5

原生形态优先

v5 的原则：Markdown 块能表达的组件就用 Markdown 写；shortcode 只为块表达不了的 情形存在。渲染钩子识别原生形态，所有钩子共用一套属性策略。

29 个 shortcode：核心 14（tabs tab steps cards card fields field include kbd badge param comment contributors asciinema）、Book 10（fig tbl eq eg xref book-toc book-figures book-tables book-equations book-examples）、Release 3、 OpenAPI 2。嵌套名（tab、card、field）只在父级里合法；每个 shortcode 都校验 参数，未知参数导致构建失败（0.4 里 asciinema、redoc、swagger、param、 comment、steps 会静默接受任何参数）。

删除的 shortcode 与替代

每个条目上的 chip 是迁移工具键（scripts/migrations/oink06.py migrate --only <key>）； manual 表示报告会列出、需要人工修改。

相对 0.4.2 新增：tabs、cards、include、eg、book-tables、book-equations、 book-examples，以及改名而来的 swagger。card 与 tab 名字未变，但现在是 cards / tabs 的子元素，契约不同。

没有图片 shortcode：渲染钩子统一为 Markdown 图片、fig 与配置里的图片来源解析页面 资源、栏目资源、全局 assets 以及 static / 远程路径，并把图注、编号、链接与 Hugo 图片处理（command、options）都放在属性行上——imgproc 能做的它都能做。

块属性策略

所有渲染钩子（表格、图片、代码块、passthrough、引用块、标题）共用一套策略： 白名单键由钩子消费，class 经 token 校验后透传，data-* 与 aria-* 透传， style、on* 与任何未知键让构建失败。内容上的站点 CSS class 仍然合法； 内联样式和事件处理器永远到不了输出。

代码围栏

• {filename="x"} 改为 {title="x"}；同一围栏上 title 与 filename 互斥。
• Prism 路径删除。params.prism_syntax_highlighting、static/js/prism.js、 static/css/prism.css 不复存在；Chroma 加 params.highlight_classes（默认 true）是唯一的高亮器。Prism 无法与 tab、group、value、num、caption 共存，任何用了标签页或编号示例的 0.4 站点一开启它就已经构建失败。
• 复制控件依次遵循围栏上的 copy=all|command|true|false、会话类 lexer 默认值 （console、shell-session → command）、再是 all。params.ui.code_copy: false 只改站点默认值；显式写了 copy 的围栏仍按自己的写法。旧键 disable_click2copy_chroma 会静默压过作者的显式值。
• Docsy 的 click-to-copy.js（0.3 起从未加载）及其 .td-click-to-copy 样式删除。

配置

三条规则

1. 布尔开关就是裸的特性名：ui.annotation: true，不是 ui.annotation.enable， 也不是 ui.annotation_enabled。仅存的 _enabled 后缀是 ui.navbar_enabled、 ui.sidebar_enabled、ui.sidebar_root_enabled——它们的裸名会与同族兄弟键冲突。
2. 单键 map 压平成标量。只有拥有多个子设置的特性才保留 map——comments、 ui.feedback、ui.page_context_menu、ui.dark_mode、ui.command_palette、 ui.alt_site、taxonomy、print、search、plantuml、drawio、mermaid、 copyright、ui.taxonomy_icons——其中开关型的同时接受裸布尔 （comments: false、plantuml: false、dark_mode: true、feedback: true、 page_context_menu: false）。
3. front matter 键 = 站点键去掉 ui. 前缀，没有例外（见 Front matter）。

键名一律 snake_case、正向、按用途命名。camelCase 只在原样透传给外部运行时的地方 保留（comments.giscus.* 是 giscus 自己的属性名，mermaid.* 交给 mermaid.initialize()）。

任何旧键或旧形态都会让构建失败并指名替代——站点配置由 layouts/_partials/config-legacy.html 负责，页面由 layouts/_partials/front-matter-legacy.html 负责——升级就是按报错逐条替换。 没有任何东西被静默忽略。

改名与改形的站点键

主题的全部默认值现在都在主题 hugo.yaml 里声明并附取值域注释。以前只是模板回退、 现在正式声明的有：offline_search: false、offline_search_summary_length: 70、 ui.breadcrumb: true、ui.reading_time: false、ui.dark_mode: false、 ui.docs_sidebar_root: section、ui.sidebar_icon_policy: all、 ui.section_index_columns: 2、ui.code_copy: true、print.toc: true、 print.section_break_wordcount: 50、markmap: false、plantuml.enable: false、 drawio.enable: false、github_branch: main。两个默认值保持派生并如此记录： ui.quick_links（来自 docs_section 与 blog_section）和 ui.taxonomy_icons （内置 categories/tags 图标）。ui.sidebar_expand_levels（2）与 ui.sidebar_menu_truncate（2000）的模板回退与声明值一致。

保持不变、继续可用的 Docsy 键：github_repo、github_project_repo、github_branch、 github_subdir、path_base_for_github_subdir、time_format_blog、 time_format_default、version、versions、version_menu、 version_menu_pagelinks、archived_version、url_latest_version、copyright、 description、author、gcs_engine_id、search.algolia.*、mermaid、 plantuml.*、drawio.*、ui.sidebar_menu_compact、ui.sidebar_menu_foldable、 ui.sidebar_menu_truncate、ui.sidebar_cache_limit、ui.sidebar_root_enabled、 ui.feedback.{enable,reasons}。

大声失败，而非静默

同时配置多个搜索后端（offline_search、gcs_engine_id、search.algolia）现在会让 构建失败（以前只警告）。PlantUML 不设 plantuml.svg_image_url、Diagrams.net 不设 drawio.drawio_server、Algolia 缺任一凭据，与 0.4 一样构建失败。构建错误遵循同一 形状——<component>: <subject> <expectation>; got <value> at <position>——全小写、 位置只用一个介词、配置错误给出完整的 params. 路径；不再指向文档 URL。

Front matter

页面键 = 站点键去掉 ui. 前缀，front matter 里不再有 ui: 块。栏目 cascade 同理 （cascade: { params: { section_index: cards } } 或直接裸键）。一个解析器 （ui-param.html）为每个可按页覆盖的 params.ui.* 设置先读页面值、再读站点值： sidebar_menu_compact、sidebar_menu_foldable、sidebar_expand_levels、 sidebar_width_min、sidebar_width_max、sidebar_item_overflow、 sidebar_headings、sidebar_enabled、section_index、section_index_columns、 lastmod_commit、breadcrumb、scroll_spy、code_copy、keyboard_nav、 book_draft_banner；再加上显式页面键 navbar_enabled、navbar_autohide、 footer_style、annotation、feedback、image_zoom、reading_time、 page_context_menu、comments、page_width、reading_width。

未变的页面键：toc_hide、toc_root、notoc、no_print、no_list、simple_list、 hide_summary、sidebar_root_for、sidebar_divider、sidebar_expanded、 sidebar_root_menu、sidebar_root_link_self、search_keywords、search_boost、 pager、landing、sections、book_number、book_status、release、 release_products、release_group_by_product、upstream_attribution、 downstream_modified、byline、author、body_class。

scripts/migrations/oink06.py migrate --only frontmatter 会改写以上全部页面键， 包括 cascade: map 与列表里的。

模板、partial 与布局

删除项，以及复制或调用过它们的站点应改用什么：

有覆盖的站点还应知道的模板层变化：

• 侧栏两个来源——内容树与显式的 data/docs_nav.json——每一行都经 shell/sidebar-node.html 渲染。shell/config.html 仍是品牌、logo、栏目配置的 唯一解析器。
• 每个渲染内容的布局都调用 content/render.html 而不是 .Content （图片缩放候选扫描在那里进行）。
• Print：print/page-content.html 通过 partialCached 让每页的 print 内容在一次 构建里只渲染一次；print/render.html、print/content.html、book/print.html 与各 single.print.html 布局都读它。复制过 0.4 print 模板的站点应删掉副本—— 0.4 的流水线在"本身是 section 的章节被父级再次聚合"时会在页面 store 上竞态。
• 标题渲染钩子归主题所有。每个标题带 id 与悬停显示的自链接 （.td-heading-self-link，文案 ui_heading_self_link）；print 与 RSS 会剥掉链接。
• DocSearch 容器只有一个 #td-docsearch；写死的 #docsearch-0/1 两个 id 没有了。

样式与资源

一个命名空间

主题产出的一切都有前缀，scripts/check-namespace.py 守着这条线。站点里挂在旧名字 上的 CSS 或 JS 必须迁移：

Sass 与令牌

删除的 Sass 文件（站点 _styles_project.scss 若仍 import 会编译失败）： td/code-dark、td/color-adjustments-dark、td/gcs-search-dark、td/extra、 td/extra/bs-defaults、td/extra/buttons、td/extra/main-container、 td/extra/navbar、td/boxes（.td-box、.td-box--<color>、.td-box--height-*）、 td/colors（.-bg-<name>、.-text-<name>）。删除的变量：$td-box-colors、 $td-print-font-name、$td-enable-webfonts。

改名或新增的令牌：--td-book-content-norm → --td-book-content-normal （.td-book-content--norm → --normal）；--td-print-font-family 角色保留但在 两种预设下都跟随 --td-body-font-family；新增 --td-motion-duration-fast （100 ms）、--td-motion-duration（150 ms）、--td-motion-duration-slow（250 ms）， shell 的每个过渡都引用它们，prefers-reduced-motion: reduce 把它们置零。

排版：UI 与正文使用 Inter（可变字重，Latin/Latin-ext/西里尔/希腊/越南语子集按 unicode-range 提供；CJK 与 emoji 回落到平台字体栈）、无边框行内代码、安静的代码 卡片加悬停显示的复制控件、Mintlify 风格字段行、页末两个文本链接的翻页器、卡片式 栏目索引上方的分隔线。Open Sans（18 个 woff2 子集、652 KB，为一个仅打印用的字体 发布到每个站点）已删除；想在纸面上换字体的站点自己在样式表里设 --td-print-font-family。system 预设依旧不请求任何品牌字体。

shell 图标改为由 shell/icon.html 分发的 Font Awesome class 对 （<i class="td-shell-icon td-shell-icon--<name> fa-solid fa-…">）而不是内联 SVG；--td-shell-icon-size 设置尺寸盒。

发布的资源

• 三个 JavaScript bundle 取代按特性组合生成的单个 bundle：js/actions.js 与 js/core.js 在每一页字节相同、可以缓存；只有一个小的 js/page-<hash>.js 随页面变化。ECharts 单独一个 <script>。print 输出加载 7.9 KB 而不是 100 KB。
• static/css/giscus-oink-{light,dark}.css 没有了。调色板以 assets/css/giscus-{light,dark}.css 随主题提供，只在渲染评论的页面发布， 并且是 comments.giscus.lightTheme / darkTheme 的默认值；指向旧路径的站点 删掉那两行即可（或写 giscus 内置主题名 / 自己的样式表 URL）。
• 删除：static/js/prism.js、static/css/prism.css、static/webfonts/open-sans/、 assets/js/click-to-copy.js。VENDOR.json 与 vendor 目录哈希已重新生成。

i18n

• 提示块文案改为带命名空间的键：callout_note、callout_tip、callout_important、 callout_warning、callout_caution、callout_success、callout_danger、 callout_question、callout_example、callout_quote、callout_details。 主题不再占用 note、example、quote 这类裸顶层键；在自己 i18n/ 里覆盖过 这些键的站点需要改名。
• 删除：community_join、community_introduce、community_learn、 community_using、community_develop、community_contribute、 community_how_to、community_guideline。
• 新增：ui_heading_self_link 与 ui_field_self_link（各语言英文兜底；中文变体已审校）。
• 32 个语言文件保持键完全一致（174 个键）。

数据文件

• data/home/<lang>.yaml（或 data/home.yaml）必须列出 sections；隐式的 hero → metrics → capabilities → principles → cta 顺序没有了，缺失会构建失败。
• 胖页脚只读 data/footer/<lang>.yaml（或 data/footer.yaml）。data/home 里的 footer 键会构建失败并指出新位置。
• data/landing/<key>/<lang>.yaml、data/docs_nav.json、data/download/<key>.yaml、 data/brand.yaml 不变。

行为与输出变化

• 标题带悬停显示的自链接；print 与 RSS 输出剥掉锚点，Markdown 输出 （RenderShortcodes）不受影响。
• print 聚合每次构建对每页内容只渲染一次。0.4 里"本身是 section 的章节"会被自己的 print 输出和父级的 print 输出并发渲染两次，两次渲染在页面 store 上竞态——可见 症状是 _print/ 里偶发重复的 td-code-… id。
• <main> 不再带 role="main"；侧栏 <aside> 不再重复内层 <nav> 的 “Section navigation” 标签。
• ui.dark_mode: true 同时开启暗色调色板与 System / Light / Dark 菜单； 单独的 show_menu: true 隐含 enable。
• ui.code_copy: false 只设默认值（见代码围栏）。
• 首页渲染导航栏；提示块标题满足对比度；Gallery 条目与其它图片同等享有缩放； 标签页运行时保住运行边界、唯一同伴 id 与 print 标题；FileTree 与整个 shell 遵守 prefers-reduced-motion。
• 表格渲染钩子也在 print 与 RSS 输出里运行，表格在交互式 HTML 之外也保留图注、 编号与滚动容器；两种形态的 fields 产出同一渲染，每个条目都有 #field-<name> 锚点。
• llms.txt 读取 params.ui.docs_section，并带描述列出文档页面。
• 图片解析器的错误按调用方标注（Markdown 图片是 image:，fig 是 shortcode 名）， 配置里的图片来源与内容遵循同一 URL 策略。

发布候选加固

最终评审发现了一个系统性迁移缺口：模板已经输出新的 data-td-* 契约，若干运行时与 测试 mock 却仍读取旧 dataset 名称；动作清单还位于同步动作注册 bundle 之后，注册表 可能以空状态初始化。这两项现已修复，并新增结构检查阻止回归。页面动作、命令面板搜索、 代码复制与折叠、反馈页面标识、折叠控件文案、Giscus 主题、图片缩放标签与 Asciinema 计时标签，现在会在测试与真实渲染 DOM 中使用同一组属性。

同一轮加固还完成了以下修正：

• report、migrate 与 check 遇到不存在、空、不可读或非 UTF-8 的目标时直接失败， 不再给出误导性的“无残留”结果；JSON front matter 改用 JSON 解码器解析；
• Markdown、RSS 与聚合打印输出都会执行旧 front matter 检查，页面评论等覆盖项严格 校验布尔值与 map 形态；
• 数据围栏与提示块会保留允许的 data-* / aria-* 属性，同时图表布尔参数保持严格；
• 每个 Swagger 与 ReDoc 嵌入都有唯一实例，不再覆盖 window.onload 或发布 window.ui；
• shell Logo、Wordmark 与配置型 Featured Image 统一使用共享 URL 策略；
• 新增 scripts/check-site-markup.py，从消费站解析后的配置中检查原生形态必需的三项 Goldmark 设置。

迁移指南

顺序很重要：先内容（工具默认 dry-run 且幂等），再让构建错误驱动配置与布局的修改。

改写内容前，先确认消费站能够渲染原生形态：

python3 path/to/oink/scripts/check-site-markup.py --site ~/pgsty/example.com

1. 盘点

python3 scripts/migrations/oink06.py report --sites ~/pgsty/example.com --md report.md --json report.json

报告逐站列出工具会改写的每一个 0.4 结构、不会碰的（带 file:line 与原因）， 以及改写之后仍会被标记的残留。

2. 内容与 front matter

python3 scripts/migrations/oink06.py migrate --site ~/pgsty/example.com          # dry run：diff + 计数
python3 scripts/migrations/oink06.py migrate --site ~/pgsty/example.com --write  # 原子改写
python3 scripts/migrations/oink06.py migrate --site ~/pgsty/example.com --write  # 第二次：changed 0
python3 scripts/migrations/oink06.py check   --site ~/pgsty/example.com          # 残留旧语法 → exit 1

变换按应用顺序：frontmatter（页面键，含 cascade:）、callout、 param_placeholders、tabs、filetree、gallery、datafence、cards、 fieldsdelim、image、include、fencetitle、badge、eg、reportonly。 --only <key> 选子集。围栏内的文本永远不改写；TOML/JSON front matter 只报告不改写。 在 11 个自有站点上，front matter 变换触及 628 个文件、零 finding。

报告会列出需要人工处理的项：swaggerui → swagger、pageinfo → 提示块、 _param 占位符、iframe/conditional-text/blocks/*、不带 kind 的 xref， 以及必须改成 window.OinkEchartsFunctions 条目的 echarts js 子围栏。

3. 配置

构建站点。每个旧键都会带着替代写法失败：

ERROR params.offlineSearch was renamed: use params.offline_search
ERROR params.ui.typography.preset was flattened: use params.ui.typography: technical | system
ERROR params.ui.showLightDarkModeMenu was renamed: use params.ui.dark_mode.show_menu
ERROR params.print.disable_toc was renamed: use params.print.toc (inverted)
ERROR params.rss_sections was removed: the key was never read; delete it

一份典型的 0.4 hugo.yaml 变成：

params:
  offline_search: true
  offline_search_on_serve: true
  offline_search_index: summary
  offline_search_summary_length: 70
  offline_search_max_results: 10
  reading_width: normal            # 原 content_width: norm
  markmap: true                    # 原 markmap: { enable: true }
  print:
    toc: true                      # 原 disable_toc: false
  comments:
    enable: true
    type: giscus
    giscus:
      repo: …                      # lightTheme / darkTheme 两行删除
  ui:
    typography: technical          # 原 typography: { preset: technical }
    dark_mode: true                # 原 showLightDarkModeMenu: true
    sidebar_expand_levels: 2       # 原 ul_show: 2
    scroll_spy: false              # 原 scrollSpy: { disable: true }
    reading_time: false            # 原 readingtime: { enable: false }
    image_zoom: true               # 原 image_zoom: { enable: true }
    keyboard_nav: true             # 原 keyboard_nav: { enable: true }
    annotation: true               # 原 annotation: { enable: true }
    pager_types: [docs, book, blog] # 原 pager: { types: [...] }
    docs_sidebar_root: section     # 原 docs_root
    breadcrumb: true               # 原 breadcrumb_disable: false
    sidebar_enabled: true          # 原 no_left_sidebar: false
    code_copy: true                # 原 disable_click2copy_chroma: false（顶层）

删除 params.links、prism_syntax_highlighting、rss_sections、github_url （改用 github_repo）、algolia_docsearch，以及 giscus 的 lightTheme / darkTheme URL。

4. cascade 与栏目索引

设置过 params.ui.* 的 cascade 改为裸键——_index.md 里的由变换处理， hugo.yaml 里手写的 cascade 要自己检查：

cascade:
  type: blog
  params:
    sidebar_menu_compact: false    # 原 params.ui.sidebar_menu_compact
    sidebar_expand_levels: 3       # 原 params.ui.ul_show

5. Sass、布局与站点脚本

• assets/scss/_styles_project.scss：删掉 @import 'td/color-adjustments-dark'、 'td/code-dark'、'td/extra'、'td/extra/bs-defaults'、'td/gcs-search-dark'； 去掉针对 .td-navbar-cover、.td-navbar-transparent、.td-box*、-bg-*、 oink-*、--oink-* 的规则。
• assets/scss/_variables_project.scss：去掉 $td-print-font-name、 $td-enable-webfonts、$td-box-colors。
• layouts/：partial "home-data.html" / "home/section.html" 换成 landing/…； partial "outputformat.html" 换成 .Store.Get "tdOutputFormat"；删掉调用 td/render-heading.html 的 _markup/render-heading.html；taxonomy_terms_* 调用改名；其它复制过的 partial 或钩子在保留前先与 0.5.0 对比。
• 站点 JS 与测试：oink-* id 与 data-oink-* 属性改为 td-* / data-td-*； 动作清单是 #td-action-manifest；每页 bundle 是 js/page-<hash>.js，旁边是 js/actions.js 与 js/core.js。
• 站点 i18n/ 覆盖：note、tip… 改名为 callout_note、callout_tip…。

6. 数据

把 footer: map 从 data/home/<lang>.yaml 移到 data/footer/<lang>.yaml； 确认 data/home/<lang>.yaml 列出了 sections。

7. 校验

hugo --printPathWarnings --panicOnWarning
python3 scripts/check-output-security.py --public public --base-url https://example.com/

然后检查变化最大的几个面：一个有代码标签页与提示块的文档页、一个有图片的页面 （缩放开与关）、一个 Book 章节及其 _print/ 聚合、index.md Markdown 输出、 一个 RSS feed、首页 landing、暗色调色板。v0.5.0 标签推送后再固定它：

hugo mod get github.com/pgsty/oink@v0.5.0
hugo mod tidy

兼容性

• Hugo Extended 0.160.1 仍是最低版本；CI 跑 0.160.1 与 0.164.0，并新增以 Hugo Module 模式构建消费站点。
• 模块路径仍是 github.com/pgsty/oink；消费站点仍不需要 Node.js、CDN 或构建期下载。
• 对 0.4 没有兼容层：改名的键、形态、shortcode、partial、class 要么构建失败要么 直接消失，这是有意的。旧键报错就是迁移指南；其中源自 Docsy 的条目同样服务 从 Docsy 迁来的站点。
• 合理的 Docsy 键保持不变（见配置下的清单）；sidebar_* 一族名字未动。
• 交互特性仍然默认关闭：offline_search、ui.image_zoom、comments、 ui.feedback、ui.dark_mode、page_context_menu.assistant_links 需要站点主动开启。

验证

主题 CI：34 个检查脚本（i18n 键一致、分类法、字体令牌、导航 / 组件 / 内容原语 / Book 契约、运行时隔离、侧栏图标、搜索、动作、命令面板、阅读、发布资产、下载、 landing、Book 迁移、共享场景、键盘、shell、命名空间、参数、vendor 清单、输出结构 与安全、30 个面的四态 goldens、代码块、内容与媒体原语、图片缩放、Gallery、组件）、 浏览器运行时单测、迁移工具测试（85）、在 Hugo 0.160.1 与 0.164.0 上无警告构建的 fixture 站点、system 排版预设、遗留 Sass 覆盖、非法预设构建失败，以及新增的 Module 模式消费站点构建。scripts/check-params.py 为每个退役键各构建一个站点 （32 个站点键、14 个页面键），断言每个都失败并指名替代。

本站按上述迁移后在 0.5.0 上无警告构建。最终门禁在 Hugo 0.160.1 与 0.164.0 上各跑 一遍完整矩阵；媒体断言允许各支持版本使用不同的不透明派生缓存哈希，同时仍严格检查 渲染 URL 结构、尺寸、alt 语义与 Zoom 排除。源码校验、本地附注标签、远端标签发布、 消费站固定版本与部署仍是可独立审计的门禁。

完整变更集

完整源码差异见 v0.4.2 到 v0.5.0 与主题的 CHANGELOG.md。

3 - Oink 0.4.0 — 面向完整发布流程的场景组件体系

Oink 0.4.0 完整交付场景组件体系。原始设计将 Reading & Release、Landing 与 Book 分别放在 0.4、0.5、0.6 三个里程碑中；公开版本将三条轨道合并到一个已签名的 v0.4.0 标签，让消费站接入一套连贯契约，而不是一串彼此依赖的预览版本。

本版本继续保持本地优先：消费站仍然只需 Hugo Extended 与 Go，不需要 Node.js、浏览器端 API 或 CDN。所有交互都采用渐进增强；HTML、打印、Markdown 与 RSS 输出会保留理解对应界面所需的完整内容。

版本亮点

阅读与发布

文档、Book 与博客页面现在拥有连续阅读 Pager，其顺序来自读者在侧栏看到的同一棵扁平导航树。上一页和下一页也会作为同源 rel 元数据写入文档头。显式导航数据、纯链接条目、侧栏分组和博客时间顺序仍保留各自语义，不会意外变成阅读目的地。

数学公式可以通过 Goldmark passthrough 使用主题内置的本地 KaTeX 渲染器。暂时无法启用 passthrough 的站点，可以使用严格、无参数的 eq 逃生舱渲染块公式；只有显式提供 num 时，同一短代码才进入 Book 的编号公式模式。

发布页面可以从本地 front matter 渲染发布事实、发布卡片、校验和与资产清单，无需浏览器查询 GitHub。经过验证的 data/download/<key>.yaml 模型同时供 download 短代码与 Landing 下载分区使用，区分滚动渠道、固定版本渠道与明确的待发布状态。

完整契约见顺序阅读与数学公式和版本发布与下载。

Landing 页面

数据驱动的首页渲染器现在也是普通页面可用的 layout: landing 外壳。页面可以使用内联数据，或从 data/landing/<key>/ 读取带语言回退的记录，再组合 21 种内置分区，包括价格、对比表、命令框、步骤、时间线、代码面板、案例、下载与条形图。

所有事实都在构建时留在本地。揭示、数字递增、复制、主题图片和紧凑菜单等可选行为只在 Landing 页面需要时加载。关闭 JavaScript 后内容仍然完整；跑马灯可以因焦点或用户选择暂停，遵守 reduced motion，并向辅助技术隐藏重复轨道。

数据解析、全部 21 种分区、本地事实规则与输出矩阵见 Landing 页面。

Book 出版

长篇手册可以在既有文档外壳上声明 Book 元数据。章节获得草稿标签、当前页侧栏标题，以及语义化的 fig、tbl、编号 eq 与按当前语言解析的 xref 目标。整书图表目录与目录树复用同一套注册表。

可选的整书打印文档会把跨章节组件链接改写为文档内引用，并为重复标题 ID 加命名空间。配套迁移工具默认 dry-run、可重复执行，提供可复现的 TPME、DDIA 与 pg-internal 配方、机器可读报告、歧义跳过项，以及第二次运行零变更检查。

创作与迁移契约见 Book 出版。

键盘与站点外壳

站点外壳现在支持单键阅读导航：w、s 在侧栏移动，a、d 折叠或展开分组， j、k 在页面大纲间移动，q、e 沿连续 Pager 翻页。h 切换会话级阅读模式； l、t、f、c 分别切换语言、主题、搜索与命令界面。所有按键都会让位于编辑控件、输入法组合、按住的修饰键与已打开的对话框。

导航栏现在覆盖文档、博客、taxonomy 与 Swagger 布局，并以一个紧凑状态取代第二套移动菜单。页面操作移到面包屑行，成为以「复制 Markdown」为主操作的分裂按钮。页脚支持经过验证的 fat、slim、none 三种样式，读者还可以折叠胖页脚的链接网格并保留该偏好。

参见键盘导航与导航与菜单。

兼容性与行为变化

• 最低支持版本仍为 Hugo Extended 0.160.1。
• 模块路径仍为 github.com/pgsty/oink；消费站仍不需要前端工具链。
• Pager 默认作用于 docs、book 与 blog 内容类型；需要退出的站点可配置明确的类型列表，或在页面设置 pager: false。
• / 现在打开完整搜索，\ 打开纯命令模式；命令面板内部的 > 前缀保持不变。
• params.footer_icp 与 params.footer_icp_url 被一个行内 Markdown 值 params.footer_center_info 取代；显式空字符串会隐藏中间区域。
• params.ui.navbar_enabled 默认为 true，可以在全站、section cascade 或单页覆盖。
• 旧首页数据与 Docsy block 短代码继续兼容；新的 Landing 页面应使用标准分区注册表。

升级到 0.4.0

1. 固定已签名标签并整理模块图。
2. 使用过 ICP 页脚参数的站点改用 footer_center_info。
3. 检查 Pager 默认值、/ 与 \ 快捷键，以及站点自己的导航栏与页脚覆盖。
4. 只有对比清楚本地差异后，才删除复制出来的主题 partial。
5. 构建有代表性的文档、博客、Landing、Book、打印、Markdown、移动端与明暗模式界面。

hugo mod get github.com/pgsty/oink@v0.4.0
hugo mod tidy
hugo --gc --minify

消费站检查清单见本站的 0.4.0 升级指南；主题仓库保留冻结的 PRD 5 迁移参考。

验证

已签名标签与发布主题源码指向同一提交。主题 CI 覆盖 Hugo Extended 0.160.1 与 0.164.0、32 个语言包、vendor 资产、运行时单元测试、全部 PRD 4/5/6 契约，以及零警告示例站构建。项目站固定公开标签，并覆盖双语源码、渲染 Markdown、站内链接、替代配置构建、浏览器行为与完整多语言 WCAG AA 矩阵。

有代表性的文档站、门户、Book 与归档站也在关闭 workspace 的情况下，从公开 v0.4.0 模块完成构建。

源码验收、公开标签、消费站固定版本与线上部署是不同的证据门禁。发布这篇注记不能代替站点流水线完成后的线上 URL 冒烟检查。

完整变更集

完整源码差异见 v0.3.0 到 v0.4.0。

4 - Oink 0.3.0 — 写作、导航与更轻的页面

发布门禁：上面的标签必须能够公开解析，项目站必须固定到该精确标签，并且线上检查必须通过。在此之前，请把当前源码页面视为发布候选材料。

Oink 0.3.0 是围绕写作与导航的一个版本。写页面时，代码块有了现代化的呈现，并补齐了一组每天都会用到的小组件；读页面时，多了嵌套导航与命令面板；而所有页面都实实在在变轻了——jQuery 已被移除。

模块路径、最低 Hugo 版本以及 Hugo-only 的消费者构建方式均未改变。有三项改动可能影响既有站点，详见破坏性变更。

版本亮点

代码块与代码分组

普通围栏代码块现在会渲染出完整的代码外壳：可选的文件名、语言标签、由服务端输出而非脚本注入的复制按钮、可选的自动换行，以及长代码的折叠。Hugo 原生的高亮选项——行号、行锚点、hl_lines、制表符宽度——行为完全不变。

复制行为是确定的，而不是靠猜。console、shell-session 这类会话 lexer 默认只复制命令，不含提示符与输出；其余语言默认复制整块。对于无法区分二者的 lexer， copy=command 会直接报错——静默复制错误内容比构建失败更糟。

code-group 短代码把包管理器、语言、平台这类并列选项组织成同步切换的标签页，并带稳定的 URL hash，因此一个链接可以直接打开读者需要的那个变体。既有的 tabpane 内容继续工作，存储键也保持不变。

完整参数契约见代码块。

日常内容组件

在既有的大型组件之外，0.3.0 补上了作者每天真正会用的小组件：badge、kbd、 fields、filetree、gallery，以及可选启用的 image_zoom。它们全部输出语义化 HTML，其中非交互组件不加载任何 JavaScript，并且每个组件在打印和 Markdown 输出下都有明确定义的呈现方式。

独立的公共 icon 短代码仍然有意推迟：在这套 API 被认真设计出来之前，组件只使用私有的、带白名单的图标注册表来做自身装饰。

各组件契约见组件。

导航与命令面板

顶层菜单在桌面端支持一级下拉，在移动端有对应的折叠面板；父级链接与展开控件分别独立操作，因此父级本身始终可以点击跳转。平铺菜单不受影响。

本地搜索升级为命令面板，具备三种模式：空查询提供快捷入口与页面操作，文本查询返回分组的页面结果，> 前缀则只搜索命令。页面可以提供 search_keywords、正值的 search_boost 以及规范化的排除标记；Lunr 路径与 CJK 子串路径应用同样的加权。

页面操作与面板命令现在走同一套注册表，因此复制文本、在 ChatGPT / Claude 中打开、查阅源码、查阅编辑历史、打印、切换主题、语言或版本，无论从哪里触发行为都一致。助手提示词在激活时解析浏览器 URL，保留实际部署域名、查询参数与片段；历史链接则使用“编辑此页面”的同一仓库路径。助手入口默认关闭，站点必须显式设置 params.ui.page_context_menu.assistant_links: true 才会启用。激活后完整 URL 会离开本站，因此不要在 query 或 fragment 中放置秘密信息。

在可编辑控件之外按 /，可以直接以命令模式打开面板。Cmd/Ctrl-K 仍然是通用入口；这个单字符快捷键不会抢占 input、textarea、select 或 contenteditable 区域中的输入。

侧栏新增图标密度策略 all、groups、none。兼容默认值仍是 all，起步示例站选用 groups。

完整配置面见迁移参考。

字体预设

字体选择被收敛到七个语义化的 --td-*-font-family 角色之后，覆盖界面、正文、标题、代码、展示文字、元信息与打印输出。本次提供两个经过校验的预设：technical 保持当前 Oink 外观，system 使用平台字体栈且完全不请求 Oink 品牌字体。既有的 Docsy 与 Bootstrap Sass 字体变量会作为这些角色的初值，因此原有覆盖继续有效。

这只是更大范围设计令牌工作中的字体一层。颜色、表面、圆角、密度与外观预设不在本次发布范围内。

参见字体令牌。

更轻的页面

jQuery 已被移除。此前它以阻塞渲染的方式出现在每个页面的 <head> 里——在任何内容之前先加载 87.5 KB——而主题自身的架构原则是只在用到的页面加载对应运行时。文档壳层没有任何地方需要它，而由它驱动的 offline-search.js 早已被命令面板取代。

另外两项开销是被消除而不是被接受的。当前输出格式改为从 page store 读取，不再在每次构建中重复推导数千次；文档壳层配置按语言缓存。在 576 页的构建上，这让模板耗时从 357 毫秒降到 72 毫秒，且生成结果逐字节一致。CJK 搜索改为在建立索引时一次性折叠字段，不再在每次击键时把整个语料重新小写化——800 篇文档的查询从每次击键 3.44 毫秒降到 0.34 毫秒。

在所测项目站快照上，移除 jQuery 与被替代的搜索运行时后，一个典型文档页的 CSS 与 JavaScript 合计减少约 88 KB。后续候选资源变化会使精确总量有所浮动。

正确性与本地化

本版本还修复了几项不太显眼但会影响正确性的缺口。Markdown 页面只在当前语言确实发布 llms.txt 时才链接它，索引也不再把站外菜单外壳当作内容。内部自定义命令在子路径部署下保持正确前缀，共用内容类型则会解析到正确的产品 root。归档版本横幅与 Giscus 回退文本已经本地化；打印与 Markdown 输出无论属性使用何种引号，都能清理只用于 Image Zoom 交互的属性。旧搜索链接也会对查询文本做百分号编码，不再遇到 & 就截断查询。

主题 CI 现在会真正运行浏览器 runtime 测试，不再把 Hugo 能打包脚本当作唯一信号。终端录屏也会等待配置字体加载后再适配播放器，避免使用 fallback 字体计算错误尺寸。

破坏性变更

不再加载 jQuery。 第三方清单此前把它列为界面基础的一部分，因此消费站自己的脚本可能依赖全局 $。主题的任何功能都不需要它。仍然需要的站点，请通过项目 JavaScript 自行打包：

<!-- layouts/_partials/hooks/head-end.html -->
<script src="{{ (resources.Get "js/jquery.min.js").RelPermalink }}"></script>

移除 static/js/tabpane-persist.js。 assets/js/code-tabs.js 已接管旧的持久化契约，保留了 td-tp-persist 存储键与 data 属性，因此已写好的标签页内容不受影响。只有直接引用该发布路径的站点需要去掉这个引用。

正文与标题字体角色直接作用于内容。 此前只修改原始 body 或标题选择器的站点，应改为使用对应的 --td-*-font-family 角色或既有的 Sass 变量：

// 之前
body {
  font-family: 'My Sans', sans-serif;
}

// Oink 0.3.0
:root {
  --td-body-font-family: 'My Sans', sans-serif;
}

升级到 0.3.0

1. 检查项目 JavaScript 是否依赖全局 $，如果依赖，请自行打包 jQuery。
2. 删除对 static/js/tabpane-persist.js 的直接引用；已写好的 tabpane 内容本身不需要改。
3. 把原始 body 或标题字体覆盖迁移到字体角色。
4. 决定是否显式启用助手入口；如启用，请检查 URL 是否含敏感 query 或 fragment 数据，并披露第三方边界。
5. 更新 Hugo 模块并整理模块图。
6. 构建站点，检查有代表性的文档页、博客页、移动端、打印视图与明暗模式。

hugo mod get github.com/pgsty/oink@v0.3.0
hugo mod tidy
hugo --gc --minify

不需要重写任何 Markdown 内容。既有的围栏代码块、tabpane 内容、平铺菜单、短代码，以及普通的 Docsy 兼容页面都继续照常工作。

兼容性

验证

0.3.0 候选版本通过并列的 Oink 项目站进行验证，因此站点构建针对的是候选主题本身，而不只是它最后固定的发布版本。公开发布前，主题侧必须通过完整契约测试套件、在最低与当前 Hugo 版本上零警告构建示例站、两种字体预设，以及浏览器运行时单元测试。站点侧必须通过格式化、中英文页面配对与稳定标题 ID、渲染后的 Markdown 与站内链接、Hugo 模块 fixture、备用配置构建、Markdown 与 favicon golden、响应式与组件浏览器行为，以及 axe 无障碍检查。标签、公共模块解析、站点版本钉住与线上冒烟仍是批准后的独立门禁。

完整变更集

完整源码差异见 v0.2.1 到 v0.3.0。

5 - Oink 0.2.0：更丰富的内容与更精致的呈现

Oink 0.2.0 聚焦读者与作者最常接触的表面：首页、品牌呈现、博客发现、分区索引与操作指南。Oink 项目站点也同步成为更清晰的双语参考，用于说明主题的当前契约。

模块路径、最低 Hugo 版本以及消费端仅依赖 Hugo 的构建方式均保持不变。唯一可能影响现有站点的配置改名，详见破坏性变更。

发布亮点

首页与品牌

首页现在可以通过有序 sections 列表组合 12 种内置分区。字符串会选择同名数据；映射则可以通过不同的 key 重用呈现方式、在不删除数据的前提下禁用区块，或直接携带短小的一次性内容。没有 sections 的站点保留 0.1.x 首页顺序，因此显式组合是新增能力，而不是必需迁移。

数据驱动的首页现在可以在 Hero 文案旁放置响应式图片。作者可以配置一张通用图片，也可以分别提供浅色与深色图片；如果图片本身包含信息，还可以提供有意义的替代文字。布局会从桌面端的双栏 Hero 自动调整为紧凑的移动端呈现，无需站点覆盖模板。

Oink 还新增 params.wordmark。配置字标后，首页导航、文档页头、抽屉和页脚会统一使用它；只配置 params.logo 的站点继续使用原来的“图标 + 标题”样式。

首页组件面板现在可以成为真正的导航区域。条目支持链接、可选的外部链接行为、紧凑样式，以及一至四列布局。纯装饰面板仍保持不可交互，兼容 0.1.0 的既有契约。

完整数据结构参见首页与页脚。

博客与版本发布

博客列表现在把图片与摘要作为一个整体进行响应式布局。特色图片不再把文字挤出平板宽度的容器，摘要可以安全断开机器生成的长标识符；没有图片的文章则会完整使用文本宽度。署名行中的分区名称现在可以点击，RSS 入口也会进入与其他页面操作一致的侧栏区域。

分类与标签使用和 TOC、页面操作相同的折叠区规则。在宽侧栏与移动抽屉中，条目都显示为易于扫描的行，并附带数量徽章。分区索引更加简洁，描述拥有更多空间；最后修改信息移动到子页面索引之后，不再打断页面导语。

Oink 项目站点现在把上游 Docsy 历史、Oink 工程文章与版本化 Oink 发布注记拆分为三个独立的双语分区。读者可以直接找到版本报告，同时不会把继承的 Docsy 文章误认为 Oink 发布。

内容组件

0.2.0 新增 Markdown 优先的 steps 短代码。直接子标题会成为自动编号的步骤，并由引导线连接；整体移动、新增或删除步骤时，无需手工维护数字。如果某个辅助标题不应占用编号，可以添加 class="no-step-marker"。

Asciinema 录像新增精致的终端边框、标题栏、紧凑控制栏与跟随颜色模式的样式，并把字体契约直接传入播放器。这样既避免播放器回退到不同的终端字体，也能让录像在两种主题下保持响应式与清晰可读。

ECharts 回调代码块继续采用既有的可信作者模型：回调属于可执行内容，必须像内联 HTML 或其他自定义集成一样接受评审。渲染器不再为每个已评审的回调块重复输出警告。

新 steps 契约参见短代码，完整组件模型参见 Oink 组件。

文档与测试

独立项目站点同步完成一轮文档更新：

• 扩充中英文首页与组件示例。
• 记录全部 12 种可组合首页分区，并在项目首页中使用适合的分区。
• 添加真实的 Asciinema 安装录像与独立的 giscus 指南。
• 把示例移入文档树，并删除过时的社区入口与仅供维护者使用的页面。
• 将 Hugo 配置合并到根目录 hugo.yml，移除旧的 Netlify 专用工具。
• 让浏览器测试与 live reload 隔离，并继续把响应式、无障碍、翻译、渲染后 Markdown 与链接检查纳入发布关卡。

这些都是项目站点改动，不会给主题消费端增加新的运行时依赖。

破坏性变更

0.2.0 将继承的特色图片设置从 default_featured_image 改名为 default_featured。请更新页面、分区 cascade 与站点级配置中的旧键：

# Oink 0.1.x
default_featured_image: /images/blog-card.webp

# Oink 0.2.0
default_featured: /images/blog-card.webp

主题内置的隐式占位图也被移除。如果文章没有图片、匹配的页面资源或显式 default_featured，Oink 现在会渲染干净的纯文本列表项。如果整个分区需要统一的视觉标识，请把 default_featured 指向站点自有图片；如果希望明确关闭默认图片，可以将其设为 false。

旧配置键没有兼容别名。这是 0.2.0 唯一必需的配置迁移。

升级到 0.2.0

1. 将所有 default_featured_image 设置替换为 default_featured。
2. 更新 Hugo 模块并整理模块依赖图。
3. 构建站点，并检查具有代表性的首页、博客、文档、移动端与颜色模式页面。

hugo mod get github.com/pgsty/oink@v0.2.0
hugo mod tidy
hugo --gc --minify

本版本不要求重写 Markdown 内容。现有首页分区、仅配置图标的品牌样式、短代码以及与 Docsy 兼容的普通页面均可继续使用。

兼容性

验证范围

0.2.0 候选版本通过同级目录中的 Oink 项目站点接受验证，因此站点构建使用的是候选主题，而不只是上一个固定版本。发布关卡覆盖格式、中英文页面配对与稳定标题 ID、渲染后 Markdown 与内部链接、Hugo 模块 fixture、响应式浏览器行为，以及 axe 无障碍检查。

完整变更

查看从 v0.1.0 到 v0.2.0 的完整源码差异。

6 - Oink 0.1.0：稳定的本地优先基础

Oink 0.1.0 是 Oink 主题的首个稳定版本。它包含 0.0.1 实现预览以及之后的稳定化工作：统一的文档页面外壳、消费端仅依赖 Hugo 的构建、本地优先的浏览器资源、基于 Hugo 原生对象的多语言行为，以及可复用的内容组件。

本版本继续使用模块路径 github.com/pgsty/oink，要求 Hugo Extended 0.160.1 或更高版本。消费站点在构建和提供主题自带功能时，不需要 Node.js、npm、PostCSS、Autoprefixer 或 CDN。

发布亮点

本地优先的主题基础

Oink 随主题提供自有的样式、字体、图标、本地搜索、图表、API 文档运行时与内容组件运行时。可选资源只在页面实际使用时加载；可分发仓库本身是一个根 Hugo 模块，不再内嵌项目站点或前端工作区。

本版本还确立了核心产品契约：

• Hugo 的语言与翻译对象统一驱动语言路由、切换、hreflang、书写方向与 locale 元数据。
• 主题支持单语言、多语言与 RTL 站点，不依赖 PGSTY 专属域名假设。
• Asciinema、ECharts、Infographic、图表、API 参考、标签页、卡片等可复用组件，共享本地且按页面加载的运行时。
• 通过可选的 giscus 集成支持 GitHub Discussions 评论；站点未启用时不会加载任何外部评论脚本。
• 继续支持与 Docsy 兼容的内容组织、菜单、分类法、打印输出与扩展钩子。

响应式页面外壳

文档、博客与 API 参考布局现在共用一套响应式外壳。桌面导航、可调整宽度的侧栏、目录（TOC）、页面操作、分类法、版本选择器和页脚采用一致的视觉与交互规则。

在平板与手机上，Oink 会把 TOC、页面操作、分类与标签移动到导航抽屉中，而不是渲染第二份副本。这样可以保持 ID唯一，并确保滚动跟踪、折叠区与复制操作在视口动态变化时仍能正常工作。语言与颜色模式控件在所有宽度下均可访问；颜色选择器明确提供“自动”“浅色”和“深色”三种偏好。

导航条目使用一致的图标，移动菜单会限制键盘焦点，页脚各列完整利用可用宽度，紧凑的页面操作菜单也不再与右侧栏重复。复制 Markdown、查看 Markdown、编辑、问题反馈和打印操作现在共用一套实现。

发布与内容呈现

语法高亮现在使用基于 class 的 Chroma 输出，并协调浅色与深色调色板。即使 JavaScript 尚未初始化颜色模式，代码仍然清晰可读；站点也可以通过 params.highlight_classes: false 选择退出。

博客列表新增确定性的特色图片解析顺序。在 0.1.0 中，它依次检查 front matter 中的 images、匹配的页面资源、继承的 default_featured_image、站点参数，最后使用主题占位图。现代博客列表与兼容的旧 partial 共用这一解析器。

新的墨迹标志与占位图能够正确处理“系统主题 × 站点所选主题”的四种组合。Oink会同时明确声明浅色与深色页面实际使用的 color-scheme，因此用户在站点中的显式选择会覆盖操作系统偏好。

无障碍与正确性

0.1.0 修复了桌面端、移动端、打印视图与辅助技术评审中发现的问题：

• 修正标题顺序、landmark 名称、任务列表标签与打印列表语义。
• 确保博客列表在平板宽度下不会溢出视口，并允许长 URL 或标识符安全换行。
• 对 GitHub issue 链接中的标题与 URL 进行正确编码。
• 本地化 404 页面，并移除无障碍名称中硬编码的标点。
• 为 iframe 嵌入补充标题与延迟加载，只注册一次尺寸调整逻辑，并安全处理跨域 frame。
• 每页只输出一个 contentinfo landmark，同时保留消费站点可直接使用的主题扩展 partial 与可选 SCSS 入口。

兼容性审计删除了确实不可达的旧页面外壳代码，也恢复了下游站点可以直接导入的文件。可达性判断会检查消费站点的布局与 _styles_project.scss，而不只检查主题自身的入口。

升级到 0.1.0

更新 Hugo 模块并重新构建站点：

hugo mod get github.com/pgsty/oink@v0.1.0
hugo mod tidy
hugo --gc --minify

本版本不要求迁移内容。如果站点直接导入 Oink partial 或 SCSS，请在升级过程中构建该站点，让其自定义表面与主题一起接受检查。

兼容性

验证范围

0.1.0 最终候选版本在主题 fixture 与 Oink 项目站点上接受了七种视口宽度的完整检查。记录结果中没有控制台错误、请求失败、水平溢出或 axe 违规。独立 fixture 还覆盖最低与当前 Hugo 版本、LTR 与 RTL 语言、子路径、打印输出、重复组件实例，以及网络隔离环境中的消费端构建。

完整变更

请参阅 v0.1.0 源码快照。