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

> Oink 的首个稳定版本将实现预览完善为可直接使用的 Hugo 模块，提供响应式页面外壳、多语言基础设施、本地优先组件与更扎实的无障碍基线。

---

LLMS index: [llms.txt](/zh/llms.txt)

---

**发布日期**：2026-08-10 · **主题标签**：
[v0.1.0](https://github.com/pgsty/oink/tree/v0.1.0) · **代码仓库**：
[pgsty/oink](https://github.com/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。

## 发布亮点 {#release-highlights}

### 本地优先的主题基础 {#local-first-foundation}

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

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

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

### 响应式页面外壳 {#responsive-shell}

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

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

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

### 发布与内容呈现 {#publishing-and-content}

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

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

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

### 无障碍与正确性 {#accessibility-and-correctness}

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

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

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

## 升级到 0.1.0 {#upgrade}

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

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

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

## 兼容性 {#compatibility}

| 契约             | Oink 0.1.0                               |
| ---------------- | ---------------------------------------- |
| Hugo             | Extended 0.160.1 或更高版本              |
| 模块路径         | `github.com/pgsty/oink`                  |
| 消费端前端工具链 | 无                                       |
| 默认浏览器依赖   | 本地优先                                 |
| 主要内容模型     | 与 Docsy 兼容的 Markdown 与 front matter |

## 验证范围 {#verification}

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

## 完整变更 {#full-change-set}

请参阅 [v0.1.0 源码快照](https://github.com/pgsty/oink/tree/v0.1.0)。