跳转到主要内容

使用 OINK Starter

一份从克隆到发布的简短连续指南。

使用 OINK Starter

一份从克隆到发布的简短连续指南。

这本小书介绍模板本身。请先从头到尾阅读一次，再用你的项目真正需要的长篇指南替换它。

目录

1 预览站点

用三条命令克隆仓库并打开本地首页。

OINK Starter 是一个 Hugo Module 站点。Git 下载源码，Go 解析锁定版本的主题，Hugo 负责完成全部构建。

前置条件

安装 Git、Go 1.27 或更新版本，以及 Hugo Extended 0.165.0 或更新版本。hugo version 输出中必须包含 extended。

三条命令

git clone https://github.com/pgsty/oink-starter.git
cd oink-starter
hugo server

打开 http://localhost:1313/。中文位于 /zh/，法语位于 /fr/。

第一个证据

修改 data/home/en.yaml 中的一句话，并确认浏览器自动刷新。现在你已经有了一条可以工作的编辑循环。

2 理解目录结构

了解哪些少量文件分别负责配置、内容与部署。

这个模板把每项职责放在一个明显的位置。

地图

hugo.yaml          站点身份、语言与可选集成
data/home/         每种语言一份精简首页数据
content/blog/      文章、设计记录与版本发布
content/docs/      经典四部曲文档树
content/book/      这份连续教程
.github/workflows/ GitHub Pages 与 Cloudflare Pages 部署

导航跟随内容

每个栏目首页 front matter 中的 menus.main 创建顶部导航及其下拉菜单。Docs 与 Book 下面的目录树则创建各自侧栏。

译文放在一起

英文使用 .md，中文与法语对页分别使用 .zh.md 与 .fr.md。把它们并排保存，并使用一致的显式标题 ID。

3 把模板变成你的站点

替换身份与示例内容，无需重新构建主题。

大多数项目只需要修改内容，以及两处配置值。

只修改一次身份

在 hugo.yaml 顶部替换 Project Name 与 https://example.org/。YAML 标题锚点会把名称带入三种语言。

只有在已有正式项目图形时，才替换 assets/icons/logo.svg 与 static/favicon.svg。

替换首页

编辑 data/home/en.yaml、zh.yaml 与 fr.yaml。sections 列表控制顺序，下面的同名数据块提供文案。

替换示例内容

保留目录结构，然后重写或删除示例叶子页面。要修改顶部栏目名称，请编辑对应语言的 _index 文件。

有意识地启用集成

hugo.yaml 中规整地注释了仓库链接、Giscus、Google Analytics、颜色、字体、分享与反馈示例。只有当配置完整且你准备运营它时，才取消注释。

4 发布站点

使用任一内置 workflow，并验证真实部署路由。

生成的 public/ 目录是一份静态站点。仓库内置两条彼此独立的部署路径。

GitHub Pages

在仓库设置中选择 Pages → Source → GitHub Actions。推送到 main 会运行 .github/workflows/github-pages.yaml，workflow 会自动计算正确的仓库子路径。

Cloudflare Pages

创建一个 Direct Upload Pages 项目，然后将 CLOUDFLARE_ACCOUNT_ID 与 CLOUDFLARE_API_TOKEN 添加为仓库密钥。把仓库变量 CLOUDFLARE_PAGES_ENABLED 设为 true 即可自动部署。项目名默认使用仓库名，也可以通过 CLOUDFLARE_PROJECT_NAME 覆盖。

验证生产站点

打开 /、/zh/ 与 /fr/，再分别测试每种语言下的 Blog、Docs 与 Book 路由。确认搜索、语言切换、深色模式以及窄屏移动布局。

重要

本地构建成功、提交已推送、workflow 变绿、公开站点正确，是四道彼此独立的检查。