这是本节的多页打印视图。 .
快速上手
- 1: 使用 OINK Starter
- 2: Starter 仓库导览
- 3: 从零建站与其它安装方式
新建站点推荐从公开的 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,或者 明确想亲手组装每个文件时,才走从零建站路径。
1 - 使用 OINK Starter
pgsty/oink-starter 是新建 OINK
站点的官方模板。它保持精简干净,不夹带 oink.pgsty.com 的主题文档、统计账号、评论仓库、浏览器回归套件或 PGSTY 品牌资产。
你只需准备 Git、Go 1.27.3+ 以及 Hugo Extended 0.168.0+(内置 Sass 编译器,无需安装 Node.js 或外部 Sass)。
模板包含什么
| 内容区 | 内置基线 | 第一个决定 |
|---|---|---|
| 语言 | 英语、简体中文、法语 | 保留三语,或选择内置单语 / 双语 profile |
| 内容 | Docs、Blog 与一本简短 Book 教程 | 重写示例;确认整个内容区不需要时才整棵删除 |
| 首页 | 每种语言一份精简 data/home/<lang>.yaml |
替换项目承诺与入口 |
| 品牌 | 中性 Logo 与 favicon | 有正式项目图形之前先保留 |
| 集成 | 仓库、Giscus、分析、分享、反馈示例均被注释 | 只启用你准备长期运营的完整配置 |
| 部署 | GitHub Pages 与 Cloudflare Pages Direct Upload workflow | 选择一条生产路径并验证真实 URL |
Starter 自己的 /book/ 是一份从预览到部署的四章短教程。本页是维护者级版本:
说明修改顺序、各层边界,以及每层之后应执行的检查。
创建自己的仓库
推荐使用 GitHub 模板
打开 Starter 仓库,点击 Use this template → Create a new repository,再克隆 GitHub 在你的账号或组织下 创建的仓库:
这样站点从一开始就有自己的 Git 历史,原始 Starter 只是上游参考,不会成为一个 可能误推送的 remote。
克隆原始仓库进行评估
只做一次性本地评估时执行:
真实项目不要从删除这个 clone 的 .git 目录开始。GitHub 模板操作已经创建了清晰的
项目边界,并保留可审计的初始提交。
修改前先预览
依次打开:
/、/zh/、/fr/:三个首页;/docs/、/blog/、/book/:三种内容区;- 任意一组译文,再操作语言切换器;
- 本地搜索、深浅色切换,以及一个窄屏视口。
同时记录实际解析的模块:
先检查所用 Starter 快照在 go.mod 中固定的版本。要使用当前发布版本,请在定制内容前更新到 github.com/pgsty/[email protected]:
分层定制
第一层:语言配置
根配置默认启用英语、中文和法语。如果这不是目标语言组合,请在其它配置修改之前 选择内置 profile。以下两条命令二选一:
这两份是完整的最小配置,不是可以叠加的片段;复制会覆盖根文件里那些被注释的集成
示例。因此应在最开始做;hugo.yaml 已有项目修改时,只合并 languages 与
disableLanguages,不要整文件覆盖。
如果已按快速上手修改站名与 URL,不必复制整份 profile。默认三语改为英中双语时,
只需在现有 hugo.yaml 顶层加入 disableLanguages: [fr];仅英文则使用 [zh, fr]。
这样可以保留已完成的身份与集成配置。
未启用语言仍保留声明,让 Hugo 能识别 .zh.md 与 .fr.md 是译文并安全忽略。
要永久移除一种语言,先确认所选 profile 能构建,再删除对应内容与首页数据。
第二层:站点身份
修改 hugo.yaml 顶部标有 CHANGE ME 的两个值:
标题的 YAML 锚点会把站名带进所有已启用语言。接着修改版权人,并在新仓库已存在后 取消仓库链接的注释:
重新运行 hugo server,检查浏览器标题、页脚、编辑 / 历史链接与 canonical URL。
项目图形尚未定稿时先不要改 Logo;文字身份更容易先完成评审。
第三层:首页
首页内容保存在 data/home/ 下的数据文件中:
先修改一种语言。每个文件中的 sections 决定区块顺序,hero、cards、cta 提供具体内容。保留原有结构,替换标语、目标 URL 与示例卡片文案;待第一种语言定稿后,再同步翻译到其他已启用语言。
需要更多区块类型时,请参考首页与落地页中的完整区块列表;主题直接读取数据文件渲染首页,无需覆盖模板。
第四层:内容与导航
重写或删除 content/ 下的示例叶子页面。确定整个内容区不属于你的项目之前,先保留
栏目根:
内容树就是侧栏。顶部导航写在各语言 _index 根页的 menus.main 里,因此给 Docs、
Blog 或 Book 改名时,修改发生在它所描述的内容旁边,而不是另一棵全局菜单树。译文
并排放置,对应标题使用相同的显式 ID:
新增自定义导航数据之前,先读组织内容;大多数站点使用生成树 已经足够。
第五层:品牌与阅读功能
正式图形准备好后,替换 assets/icons/logo.svg 与 static/favicon.svg。随后一次只启用
一组最小而有用的配置:
自定义本地字体时,用 params.ui.fonts 写字体族,或者在站点 CSS 中声明字体文件。
布局、侧栏、搜索与组件配置应查询配置总览,不要复制
oink.pgsty.com 那份大得多的站点配置。
第六层:外部集成
Starter 默认关闭或注释了仓库操作、Giscus、Google Analytics、反馈与分享。只有 必需事实全部明确时才启用:
- 仓库链接需要真实 owner、repository 与 branch;
- Giscus 需要仓库 / 分类名称和不可变 ID;
- Google Analytics 需要项目自己的 measurement ID;
- 反馈只有在分析存在时才记录结构化
gtag事件; - 助手链接会把当前 URL 发送给第三方,因此必须做显式策略选择。
不完整的可选块应继续保持注释。各集成的运营边界见启用评论、 分析与 SEO和仓库与页面信息。
构建与部署
本地生产构建
启用托管 workflow 前执行:
构建时请保持告警可见以便审阅,请勿启用 --panicOnWarning 或 HUGO_PANICONWARNING(上游 LibSass 弃用提示属预期现象)。提交 hugo.yaml、go.mod 与 go.sum;不要提交生成的 public/、resources/、模块
缓存或本地模块替换。
GitHub Pages
Starter 已包含 .github/workflows/github-pages.yaml。在
Settings → Pages 中选择 GitHub Actions 作为 Source。推送到 main 后,
workflow 使用固定工具链构建,向 GitHub 查询正确的项目子路径,再通过 Pages 部署
API 发布 public/。
Cloudflare Pages
内置 .github/workflows/cloudflare-pages.yaml 使用 Direct Upload。创建 Pages
Direct Upload 项目,添加 CLOUDFLARE_ACCOUNT_ID 与 CLOUDFLARE_API_TOKEN,再手动
运行一次 workflow。设置仓库变量 CLOUDFLARE_PAGES_ENABLED=true 后才会自动部署;
规范地址不是默认 pages.dev 域名时,再设置 CLOUDFLARE_SITE_URL。
同一个项目只选 Direct Upload 或 Cloudflare Git integration 其中一种。完整托管对比
与 baseURL 规则见发布上线。
验证并删除示例
宣布站点完成前:
- 搜索
Project Name、example.org、OWNER、PROJECT等占位符,逐项确认剩余位置 是否有意保留。 - 在桌面与移动端打开每种已启用语言的根,以及代表性的 Docs、Blog、Book 页面。
- 确认语言切换落到对页,而不是首页。
- 验证搜索、深色模式、一个组件、Markdown 输出、打印、404、canonical URL 与仓库操作。
- 把部署 workflow 和公开 URL 与本地构建分开检查。
删除示例 Book 或 Blog 之前,要同时移除对应顶部菜单根,以及首页上指向它的卡片。每整棵 删除一个内容区就严格重建一次,才能让失败归因到单一改动。
下一步
用 Starter 仓库导览查询文件职责,再继续阅读 编写页面与配置总览。已有站点不应 继承 Starter 内容模型时,改走从零建站路径。
2 - Starter 仓库导览
本页梳理从 pgsty/oink-starter
初始化后的仓库目录结构。go.mod 以 Hugo Module 方式固定 OINK 主题版本,Hugo 会将解析后的主题源码保存在 Go 模块缓存中,不会复制进站点仓库。
顶层地图
oink-starter/
- oink-starter/
- hugo.yaml身份、语言、输出、参数与模块导入
- go.mod站点模块与精确 OINK 版本
- go.sum模块校验和
- examples/
- hugo.single.yaml仅英文的完整 profile
- hugo.bilingual.yaml英文 + 中文的完整 profile
- data/
- home/
- en.yaml每种语言一份精简落地页
- zh.yaml
- fr.yaml
- home/
- content/
- _index.md各语言首页根
- _index.zh.md
- _index.fr.md
- docs/简介、快速上手、教程、参考
- blog/文章、设计记录、发布说明
- book/介绍 Starter 的连续教程
- assets/
- icons/logo.svg经 Hugo 处理的项目 Logo
- static/
- favicon.svg原样复制到站点根
- i18n/
- fr.yamlStarter 自有法语界面覆盖
- .github/workflows/
- github-pages.yaml生产构建与 GitHub Pages 部署
- cloudflare-pages.yaml生产构建与 Cloudflare Direct Upload
- README.md面向仓库维护者的操作摘要
- LICENSE模板源码许可证
生成的 public/、resources/、.hugo_build.lock 与模块缓存是被忽略的构建状态,
不是源码。
最先修改什么
| 路径 | 职责 | 第一次操作 |
|---|---|---|
hugo.yaml |
身份、规范 URL、语言、输出、主题功能、可选集成 | 修改两个标记值;其它修改前先选择语言 profile |
data/home/ |
首页承诺、卡片与行动入口 | 一种语言确认后,再重写所有已启用语言 |
content/ |
全部读者可见内容 | 替换示例叶子;确认整个内容区不要时才删除栏目根 |
assets/icons/logo.svg |
经处理的 Logo | 有正式图形后再替换 |
static/favicon.svg |
浏览器图标 | 与 Logo 一起评审后替换 |
hugo.yaml 中的 params.github_* |
编辑、历史、新建页面与 issue 链接 | 目标仓库已存在后才取消注释 |
哪些必须保留
go.mod与go.sum:两者共同固定并校验模板选定的 OINK 版本,都要提交;这条基线与后续升级分开记录。hugo.yaml中三项 Goldmark 设置:原生 Steps、Cards、Fields、图片属性与 Book 目标都依赖它们。outputs:删除markdown、LLMS或print,会有意删除对应的 Markdown、 Agent 索引或打印内容区。- workflow 中的
fetch-depth: 0:保留enableGitInfo时,最后修改与贡献者事实需要 完整 Git 历史。 - CI 中的
GOWORK: off与HUGO_MODULE_WORKSPACE: off:开发者本地 workspace 不得 替换 CI 正在验证的公开版本。
可选内容区
Docs、Blog 与 Book 是彼此独立的顶层内容区。安全删除其中一个的顺序是:
- 删除对应的
content/<surface>/内容树; - 删除首页指向它的卡片或链接;
- 确认其它页面不再链接它;
- 生产构建,并检查剩余顶部导航。
不要只删除某种语言的栏目根:那会形成难以区分「有意不对称」与「漏译」的语言专属导航 和回退行为。要么在所有已启用语言中删除整个内容区,要么明确记录这种不对称。
完成语言选择后,examples/ 下两个配置 profile 可以删除,也可以作为参考保留;真正
生效的站点配置只有根目录 hugo.yaml。
内容与导航
Docs 与 Book 下的目录结构和 weight 共同形成侧栏与翻页顺序。顶部导航来自栏目根的
menus.main。译文根重复相同的 identifier、parent 与 weight,只翻译可见标签。
Starter 刻意演示 Documentation System 内容模型:
- 简介回答是什么、为什么;
- 快速上手帮助新用户得到结果;
- 教程带领读者完成端到端任务;
- 参考记录精确的受支持行为。
可以按项目需要改名或重组,但应保留不同学习路径之间的分工,不要把所有答案混进一棵树。
语言模型
英文源码以 .md 结尾,中文和法语对页分别以 .zh.md、.fr.md 结尾。首页数据按
data/home/ 下的语言键分文件。根 profile 声明语言、locale、顺序与站点描述。
单语与双语 profile 仍声明被禁用的语言,这是有意设计:Hugo 会把未使用后缀识别为 译文,而不会把多个文件渲染到同一个英文 URL。只在项目配置开始前复制 profile;之后 应手工合并。
OINK 在哪里
两个文件建立模块边界:
此示例固定当前发布版本 v1.5.1。请检查所用 Starter 快照的固定版本;若版本较早,按
升级指南更新。
hugo mod graph 显示实际解析的版本。生产构建使用 go.mod 中固定的标签;联调主题时可通过环境变量 HUGO_MODULE_REPLACEMENTS 临时指向本地目录,切勿将该覆盖配置提交进 Git。
部署文件
GitHub Pages workflow 在推送 main 后自动运行;仓库设置必须选择 GitHub Actions
作为 Pages Source。Cloudflare workflow 默认手动运行,只有仓库变量
CLOUDFLARE_PAGES_ENABLED=true 存在时才自动执行;所需账号 ID 与 API token 始终
保存在仓库 secrets 中。
只保留实际运营的部署路径。Cloudflare Direct Upload 与 Cloudflare Git integration 是同一个项目的两种所有权模型,不是应当同时运行的两道关卡。
安全的定制顺序
- 证明未修改的预览可用。
- 先选择语言,再修改身份。
- 替换一种首页,再补齐译文。
- 替换内容并验证导航。
- 品牌与阅读功能一次只改一组。
- 启用完整的外部集成。
- 执行生产构建。
- 部署,再独立验证生产环境。
仓库已经属于自己后,每层之间做一次提交。小边界能让后续回归与回滚明确归因到一个决定。
验证
模块图应显示固定发布,构建成功并完成告警审阅,上游 LibSass 弃用告警允许出现。
Git 状态只包含源码修改而没有 public/ 或缓存。之后打开所有已启用语言的根,以及代表性的 Docs、Blog、Book 路由,再进入部署。
相关
- 使用 OINK Starter — 完整分层流程
- 从零建站 — 不采用这套内容模型,只接入 OINK
- 组织内容 — 侧栏、翻页与菜单权威
- 配置总览 — 当前全部站点参数
- 发布上线 — 托管商配置与生产检查
3 - 从零建站与其它安装方式
这是推荐路径 OINK Starter 的手工替代方案。本页从空目录
搭建一个最小 OINK 站点:一份精简 hugo.yml 加一条 hugo mod get,得到一个可预览
的单语站点。代价是首页、示例内容、部署 workflow 与每种组件用法都要自己组装。
已有 Hugo 站点时,按下方接入现有站点操作;已有 Docsy 站点见版本升级。
后半部分对比四种安装方式:Hugo Module、Git submodule、离线归档、固定版本源码副本。 当前开发与构建统一使用 Go 1.27.3 与 Hugo Extended 0.168.0(内置 Sass 编译器,无需外部 Sass)。
接入现有站点
在保留现有配置与内容的分支中操作。跳过 hugo new site,继续使用原配置文件名。
- 只有站点没有
go.mod时,才用自己的仓库模块路径执行hugo mod init;已有模块声明保持不变。 - 执行
hugo mod get github.com/pgsty/[email protected]。 - 用下方的 OINK
module.imports替换旧主题引用,保留无关导入与配置。合并示例中的三项markup.goldmark设置与markup.highlight.noClasses: false,不要整份覆盖原配置。 - 检查站点自有
layouts/、资源、旧主题短代码,以及页面的type/layout:这些覆盖和约定可能仍然选择旧主题行为。保留内容,只做必要适配。 - 执行
hugo,再用hugo server打开一篇已有的代表性页面。先核对导航、图片与代码块,再启用可选 OINK 功能。最后按验证完成检查。
从空目录到第一页
-
建骨架并获取主题
hugo mod init后面跟的是你自己站点的模块路径,通常就是仓库地址。hugo mod get会写出go.mod与go.sum,两个都要提交。构建前创建
.gitignore,避免把生成文件加入 Git。完成首个提交前,保持enableGitInfo关闭:.gitignore最新版本号可在 GitHub Releases 查看;本页显示的
v1.5.1是本站当前固定的版本。生产站点应在go.mod中固定明确的发布标签,避免直接跟踪main分支。 -
写
hugo.yml仅对这个新站:把生成的
hugo.yaml改名为hugo.yml(Hugo 两者都接受),再用下面内容替换。已有站点应合并所需配置,不要整份覆盖:hugo.yml五段分别管什么:
段 管什么 少了会怎样 顶层 + languages站名、域名、语言与顶栏菜单 baseURL不对,线上所有绝对链接指错markup.goldmark三项组件前置 属性行变成正文里的一行 {.steps}params搜索、仓库链接、外壳开关 交互功能默认关闭,主题不替站点决定 outputs每页的 .md、llms.txt、打印页页面菜单里没有「复制 Markdown」,也没有打印视图 module引用主题、声明 Hugo 下限 构建时找不到主题 -
写第一页
content/下的每个一级目录是一个分区,目录结构就是侧栏结构。文档分区至少要有一个_index.md:content/docs/_index.mdcontent/docs/install.md标题写显式
{#id}:后续加译文时两种语言的锚点才能对应。页面写法见编写页面。 -
预览
打开 http://localhost:1313/docs/,Docs 分区中应列出 Install。添加首页内容之前,根地址的首页仍为空。修改 Install 页面,确认预览随之更新。
其它安装方式
上面用的是 Hugo Module。另外三种方式面向特定约束:网络隔离、平台要求构建输入包含完整主题树、组织内部需要评审主题副本。除 hugo mod vendor 之外,它们都不建立 Go 模块,站点用 theme: oink 而不是 module.imports 引用主题;共同的代价是版本解析与完整性校验由你自己负责。
Hugo Module(推荐)
唯一能让 Hugo 自己解析版本、校验 checksum、并在 go.sum 里留下审计记录的方式。hugo mod graph 看实际解析结果,hugo mod get -u 升级。需要本机有 Go。
Git submodule
在站点仓库里记录准确的主题 commit:
CI 必须在运行 Hugo 之前初始化 submodule,否则 themes/oink 是空目录:
离线归档
网络隔离环境使用。两条路径,都先在联网机器上准备,再整体搬入。
用 hugo mod vendor:把已解析的主题源码固化进站点目录,之后构建既不联网也不需要 Go。
_vendor/ 存在时 Hugo 优先使用它(hugo mod graph 输出 +vendor),hugo.yml 里的 module.imports 保持不变。这一步需要 Go,之后的构建不需要。升级主题要回到联网环境重新执行 hugo mod get 与 hugo mod vendor。
_vendor/ 只收主题挂载出来的目录(assets data i18n layouts static)以及 hugo.yaml 与 theme.toml,不含 LICENSE、NOTICE 与 VENDOR.json。要对外分发这份归档,把这三个文件从主题仓库一并取来。
用 tag 源码归档:不建 Go 模块,直接把某个版本的主题解压到 themes/oink/。
主题仓库的根目录就是模块根目录,解压出来直接是 layouts/、assets/、i18n/、static/ 这一层,不需要再进入下一级。重新分发时必须保留 LICENSE、NOTICE 与 VENDOR.json。最后一个记录了每个第三方运行时的版本、来源、许可证路径与 SHA-256,是离线审计的依据。
跨机器传输时,在联网侧从不可变标签生成归档与校验值:
把归档与 .sha256 一起传入隔离环境,先校验再解压:
离线构建前,请确认以下 11 项顶层文件与目录完整无缺:
themes/oink/
- oink/
- go.mod模块路径声明,Hugo Module 方式解析用
- hugo.yaml主题默认参数与 Hugo 版本下限
- theme.toml主题元数据,theme: oink 方式需要
- LICENSEApache-2.0
- NOTICE上游署名,再分发时必须保留
- VENDOR.json第三方运行时清单:版本、来源、许可证路径、SHA-256
- assets/SCSS、JS 与随主题分发的第三方运行时
- layouts/模板、partial、shortcode、render hook
- static/字体文件,原样发布
- i18n/32 份界面语言文件
- data/页尾出处行用的 SPDX 许可证表
固定版本源码副本
托管平台要求站点仓库包含主题文件时,按上方tag 归档步骤准备并解压到
themes/oink/。配置 theme: oink,把解压后的文件连同已验证的标签与校验值记录一起提交。
直接 git clone ... themes/oink 会保留嵌套 .git 目录,加入父仓库时记录的是 Git 引用,
而非主题文件,因此不能得到这里所需的完整源码副本。希望用 Git 引用跟踪主题时,应使用 submodule。
四种方式对比
| 方式 | 需要 Go | 版本可审计 | 主题源码进你的仓库 | 适用 |
|---|---|---|---|---|
| Hugo Module | 是 | go.sum 自动校验 |
否 | 默认推荐 |
| Git submodule | 否 | 仓库记录 commit | 以引用形式 | 需要主题源码在库内 |
| 离线归档 | 否 | 手工核对 checksum | 是 | 网络隔离 |
| 固定版本源码副本 | 否 | 记录标签与校验值 | 是 | 平台要求完整树 |
Bootstrap、Font Awesome、字体、搜索与图表运行时全部随主题分发。站点不需要 node_modules、PostCSS、RTLCSS,也不需要 CDN。为 Docsy 站点安装 npm 依赖的教程属于上游 Docsy 的流程,不适用于 OINK。
用本地主题 checkout 开发
同时修改主题与站点时才需要这一节。把两个仓库克隆为同级目录:
用环境变量 HUGO_MODULE_REPLACEMENTS 把模块临时替换为本地 checkout,go.mod 不变:
文档站仓库的 Makefile 就是这几条命令的别名,make dev 与 make check 要求主题 checkout 在同级目录 ../oink:
Go workspace(go work init + HUGO_MODULE_WORKSPACE=go.work)是等价的另一种做法。两种做法都只作用于本机:CI 与生产构建用的是 go.mod 里的版本,go.work 不要提交。
验证
构建以 Total in … 结束且无意外 WARN / ERROR 即通过(上游 LibSass 弃用提示属预期现象;请保持告警可见并审阅,请勿启用 --panicOnWarning 或 HUGO_PANICONWARNING)。再确认:
/docs/打得开,侧栏里有你写的页面- 顶栏有搜索框,搜得到刚写的标题
- 深浅色切换按钮在,切换后代码块配色跟着变(说明
markup.highlight.noClasses: false生效) git status --short只列出源码修改,生成产物已被忽略。Module 方式提交go.mod与go.sum;其它安装方式保留各自的主题源码或 submodule 记录。
相关
- 快速上手 — 在 Starter、既有 Hugo 站点与迁移之间选择
- OINK Starter — 推荐的新站点路径
- Starter 仓库导览 — 模板各目录的职责
- 配置总览 —
hugo.yml每个键的含义与默认值 - 编写页面 — 第一页之后怎么继续写
- 版本升级 — 升级主题模块、从 Docsy 迁移