多语言支持

Mon, 01 Jan 0001 00:00:00 +0000

OINK 使用 Hugo 的多语言页面模型，不依赖某个站点专属的域名或模板假设。随仓库提供的站点将英文设为首要语言，将简体中文（zh）设为第二语言。

配置语言

在 hugo.yaml 中定义默认语言与所有启用的语言：

defaultContentLanguage: en

languages:
 en:
 label: English
 locale: en-US
 weight: 1
 title: Product Documentation
 params:
 description: Product guides and reference
 zh:
 label: 简体中文
 locale: zh-CN
 weight: 2
 title: 产品文档
 params:
 description: 产品指南与参考资料
 time_format_default: 2006年1月2日
 time_format_blog: 2006年1月2日

weight 同时决定语言排序和选择器顺序。label 使用该语言自己的文字显示。locale 为 HTML、备用链接和 Open Graph 元数据提供符合标准的语言标签。

贡献指南

Mon, 01 Jan 0001 00:00:00 +0000

OINK 是从 Docsy 派生的独立主题。贡献必须保留 Apache-2.0 历史和适用的第三方 NOTICE，同时改进唯一的标准实现。

提交变更之前

在 OINK 仓库中搜索已有 issue 和拉取请求。
报告缺陷时，请记录 Hugo 版本、安装方式、语言、路由、生产命令和最小可复现输入。
提议功能时，请说明它为什么属于可复用主题，而不是消费站点的业务层。
不要引入 oink.enabled 开关、oink.* 配置树或平行视觉外壳。OINK 的标准布局就是产品本身。

小型修复可以直接实现。较大的行为变更应在编写代码前说明兼容性、离线、无障碍、安全与迁移影响。

开发环境

消费站点只需要 Hugo Extended、Go 与 Git。主题仓库是直接的 Hugo Module；项目站点仓库使用固定的 Node.js 与 npm 版本运行格式、链接、翻译与回归检查。

请在仓库根目录按照 lockfile 安装维护依赖。不要在无关变更中顺带更新依赖。

项目拆分为：

github.com/pgsty/oink：发布主题源码与 VENDOR.json；
github.com/pgsty/oink.pgsty.com：文档、示例与测试。

构建消费端合同

必须从消费站点验证用户真正运行的路径：

hugo --gc --minify

该构建必须在消费站点不安装 npm 软件包的情况下成功，也不能为了主题自有浏览器资源发起网络请求。

测试本地主题候选版本时，把两个仓库克隆为同级目录，并启用被忽略的 Hugo workspace：

go work init .
go work edit -replace=github.com/pgsty/oink=../oink
HUGO_MODULE_WORKSPACE=go.work npm run build

运行聚焦测试

先选择最小的相关测试集：