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

发布日期：2026-08-10 · 主题标签： v0.2.0 · 代码仓库： pgsty/oink

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/[email protected]
hugo mod tidy
hugo --gc --minify

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

兼容性

验证范围

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

完整变更

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