快速上手
新建站点推荐从公开的 GitHub 模板
pgsty/oink-starter 开始。该模板固定了已发布的 OINK 版本,开箱即可构建,仅包含干净的示例内容与部署 workflow,不夹带本站的回归测试套件。
OINK 站点使用 Git、Go 1.27.3 或更高版本,以及 Hugo Extended 0.168.0 或更高版本构建(使用 Hugo 内置 Sass 编译器,无需安装 Node.js、npm 或外部 Sass)。
选择起点
| 当前情况 | 推荐路径 | 得到什么 |
|---|---|---|
| 新建文档站或项目站 | OINK Starter | 一套精简的三语 Docs、Blog、Book 站点与两条部署 workflow |
| 已有 Hugo 站点 | 从零安装 | 不替换内容,只补 OINK 模块与 Goldmark 前置配置 |
| 已有 Docsy 或旧版 OINK 站点 | 版本升级 | 保留内容,迁移受支持的语法,并审查站点覆盖 |
五分钟建立基线
-
安装工具
安装 Git、Go 1.27.3 或更新版本,以及 Hugo Extended 0.168.0 或更新版本。Hugo 输出必须包含
extended:macOS 可以执行
brew install git go hugo。Linux 与 Windows 请按官方 Hugo 安装指南和 Go 下载页安装,并确认选择 Hugo Extended。 -
创建或克隆站点
准备长期维护时,请打开 Starter 仓库并点击 Use this template,然后克隆 GitHub 为你创建的新仓库。只想在本机评估原始模板时执行:
-
打开基线
打开 http://localhost:1313/。默认 Starter 还在
/zh/发布中文,在/fr/发布法语。开始修改前,先确认 Docs、Blog、Book、本地搜索、语言切换与深浅色 模式都能工作。 -
完成一个可见修改
修改
hugo.yaml顶部的站名与规范 URL,再修改data/home/en.yaml中的一句话。 浏览器刷新后能同时看到两处变化,才算证明配置、内容与固定版本的主题已经正确连通。
由浅入深地定制
- 使用 OINK Starter — 先选语言,再依次处理身份、首页、 内容、导航、品牌、集成与部署。
- Starter 仓库导览 — 每个文件负责什么,哪些要替换, 哪些可以删除。
- 编写页面 — front matter、标题、链接、图片、草稿与页尾控件。
- 组件总览 — 内容树稳定后,再增加表达能力。
- 品牌外观 — Logo、强调色、字体、页宽与 CSS 扩展点。
- 发布上线 — 使用内置 GitHub Pages 或 Cloudflare Pages workflow,再验证真实公开路由。
先跑通基础构建与内容树,再逐层修改语言、导航、CSS、统计与托管配置,遇到问题时更容易排查。
发布门禁
首次推送前,先在本地执行与 Starter workflow 一致的生产构建:
确认命令正常退出并输出 Total in …,且 public/ 下已生成各语言根目录以及代表性的 Docs、Blog、Book 页面。构建时请保持告警可见以便审阅,请勿启用 --panicOnWarning 或 HUGO_PANICONWARNING(Hugo 内置 LibSass 的弃用提示属预期现象)。推送后,再进一步核对 CI workflow 状态与线上公开地址的渲染结果。
用 AI agent 建站
OINK 发布了一个 agent 技能 Oink 建站(oink-site):一个 Markdown 文件,汇集了建站流程、OINK 自家站点的审阅标准,以及案例库中的经验。语法以本文档为准,并要求 agent 在浏览器中验证自己的工作。
保存为技能后,开启一个新的 agent 会话:
然后描述你想要的站点,例如“用 oink-site 技能为这个项目搭建一个中英双语文档站”。没有技能目录的 agent,把地址交给它即可直接按文件执行。想要英文版,把地址换成 skill.md。重新下载即可更新;文件中写明了它对应的 OINK 版本。
下一步
继续阅读完整 Starter 教程。如果模板有你不需要的结构, 按仓库导览安全删减。只有在给既有站点接入 OINK,或者 明确想亲手组装每个文件时,才走从零建站路径。