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

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

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

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

兼容性

验证范围

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

完整变更

请参阅 v0.1.0 源码快照。