跳转到主要内容

快速上手

从官方 OINK Starter 建立可运行的本地基线,再依次定制内容、语言、品牌、集成与部署。

新建站点推荐从公开的 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 站点 版本升级 保留内容,迁移受支持的语法,并审查站点覆盖

五分钟建立基线

  1. 安装工具

    安装 Git、Go 1.27.3 或更新版本,以及 Hugo Extended 0.168.0 或更新版本。Hugo 输出必须包含 extended:

    $ go version
    go version go1.27.3 darwin/arm64
    $ hugo version
    hugo v0.168.0+extended+withdeploy darwin/arm64
    

    macOS 可以执行 brew install git go hugo。Linux 与 Windows 请按官方 Hugo 安装指南和 Go 下载页安装,并确认选择 Hugo Extended。

  2. 创建或克隆站点

    准备长期维护时,请打开 Starter 仓库并点击 Use this template,然后克隆 GitHub 为你创建的新仓库。只想在本机评估原始模板时执行:

    git clone https://github.com/pgsty/oink-starter.git my-docs
    cd my-docs
    hugo server
  3. 打开基线

    打开 http://localhost:1313/。默认 Starter 还在 /zh/ 发布中文,在 /fr/ 发布法语。开始修改前,先确认 Docs、Blog、Book、本地搜索、语言切换与深浅色 模式都能工作。

  4. 完成一个可见修改

    修改 hugo.yaml 顶部的站名与规范 URL,再修改 data/home/en.yaml 中的一句话。 浏览器刷新后能同时看到两处变化,才算证明配置、内容与固定版本的主题已经正确连通。

由浅入深地定制

  • 使用 OINK Starter — 先选语言,再依次处理身份、首页、 内容、导航、品牌、集成与部署。
  • Starter 仓库导览 — 每个文件负责什么,哪些要替换, 哪些可以删除。
  • 编写页面 — front matter、标题、链接、图片、草稿与页尾控件。
  • 组件总览 — 内容树稳定后,再增加表达能力。
  • 品牌外观 — Logo、强调色、字体、页宽与 CSS 扩展点。
  • 发布上线 — 使用内置 GitHub Pages 或 Cloudflare Pages workflow,再验证真实公开路由。

先跑通基础构建与内容树,再逐层修改语言、导航、CSS、统计与托管配置,遇到问题时更容易排查。

发布门禁

首次推送前,先在本地执行与 Starter workflow 一致的生产构建:

hugo --cleanDestinationDir --gc --minify --environment production \
  --printPathWarnings

确认命令正常退出并输出 Total in …,且 public/ 下已生成各语言根目录以及代表性的 Docs、Blog、Book 页面。构建时请保持告警可见以便审阅,请勿启用 --panicOnWarning 或 HUGO_PANICONWARNING(Hugo 内置 LibSass 的弃用提示属预期现象)。推送后,再进一步核对 CI workflow 状态与线上公开地址的渲染结果。

用 AI agent 建站

OINK 发布了一个 agent 技能 Oink 建站(oink-site):一个 Markdown 文件,汇集了建站流程、OINK 自家站点的审阅标准,以及案例库中的经验。语法以本文档为准,并要求 agent 在浏览器中验证自己的工作。

保存为技能后,开启一个新的 agent 会话:

Claude Code
mkdir -p ~/.claude/skills/oink-site
curl -fsSL https://oink.pgsty.com/skill.zh.md -o ~/.claude/skills/oink-site/SKILL.md
Codex
mkdir -p ~/.codex/skills/oink-site
curl -fsSL https://oink.pgsty.com/skill.zh.md -o ~/.codex/skills/oink-site/SKILL.md

然后描述你想要的站点,例如“用 oink-site 技能为这个项目搭建一个中英双语文档站”。没有技能目录的 agent,把地址交给它即可直接按文件执行。想要英文版,把地址换成 skill.md。重新下载即可更新;文件中写明了它对应的 OINK 版本。

下一步

继续阅读完整 Starter 教程。如果模板有你不需要的结构, 按仓库导览安全删减。只有在给既有站点接入 OINK,或者 明确想亲手组装每个文件时,才走从零建站路径。