用 Oink 搭个人站：从零到发布的笔记整理

2026-08-29 发布于博客

不太懂前端时，如何用 Hugo + Oink 搭文档站——内容结构、博客写法、hugo.yml 与本地预览命令。

Oink 官方教程写得很完整，但对不太了解前端的人来说，第一次把「文件夹、配置、命令」串起来仍会有点晕。这篇把我最近搭 YHY Study Website 时的笔记整理成一条线：先搞清 Oink 是什么，再理解 content/ 怎么组织，最后走一遍写博客和发布的流程。

Oink 建站示意 — Markdown → Hugo → Oink 主题 → 可发布的静态站点

Oink 和 Hugo 各管什么

Hugo 是静态站点生成器：读 Markdown + 配置，输出 HTML。
Oink 是 Hugo 主题：决定侧栏、卡片、提示块、代码块等「长什么样」。

内容和外观分开维护：

站点仓库（my-project-docs）：Markdown 文章、hugo.yml 配置
主题仓库 github.com/pgsty/oink：模板与样式

站点在 hugo.yml 里声明「用 Oink 主题」，go.mod 固定版本（当前 v0.6.0）。运行 hugo server 时：

从站点仓库读文章和配置
从主题模块（按 go.mod 下载）读模板和样式
把内容套进主题，生成网页

日常够用的一条命令

只写文档、不改主题时，记住 hugo server 即可；不必一开始就碰 make dev。

本地预览：先让站跑起来

进入项目目录后启动：

cd D:\MyData\yhy\6data\repository\my-project-docs
hugo server

浏览器打开 http://localhost:1313/。改 content/ 下的 .md 保存后会自动刷新。

若希望每次改动都做更完整的重渲染（排查样式问题时有用）：

hugo server -DFE --disableFastRender

-DFE：草稿、未来日期页面也显示，方便写作
--disableFastRender：关掉快速渲染，避免增量更新带来的偏差

content/ 怎么分层

Oink 不单独维护导航库：磁盘上的文件夹结构 = 侧栏结构 = URL 路径。

三个常用概念：

概念	含义
Section（分区）	有 `_index.md` 的文件夹，这一层本身也有入口页
Page（页面）	文件夹里的 `.md`，或子文件夹里的 `index.md`
Sibling（同级）	同一目录下多篇 `.md`，用 `weight: 10/20/30…` 排序

本站根目录示意：

content/
├── _index.md           → 首页
├── search.md           → 搜索页（特殊，一般不改）
├── links.md            → 友链
├── experience/         → 经历（文档型，type: docs）
├── learn/              → 学习
└── blog/               → 博客（按 date 排序）

一篇文章两种放法：

方式	路径示例	适合
单文件	`content/blog/my-post.md`	纯文字、图放 `static/`
页面包	`content/blog/my-post/index.md` + 同目录图片	一篇多图，图与文放一起

hugo.yml 里先认这几个键

不用一次读完整个配置文件，先知道这几项即可：

键	作用
`title`	站名，出现在浏览器标签、顶栏等
`params.productionURL` + `baseURL`	正式上线后的完整网址；影响 sitemap、RSS、绝对链接
`params.github_repo`	「编辑此页」等按钮指向的内容仓库
`params.copyright`	页脚版权信息
`languages.zh.menus.main`	顶栏菜单（经历 / 学习 / 博客 / 友链）

baseURL 常和 productionURL 用 YAML 锚点绑在一起：

productionURL: &productionURL https://ryanyhy.github.io/YHY-Website/
baseURL: *productionURL

&productionURL 定义名字，*productionURL 引用，改一处全站生效。

写一篇博客：五步

起文件名 — 在 content/blog/ 新建 .md，文件名会变成 URL 的一部分，建议用英文 slug（如 oink-site-setup-notes.md → /blog/oink-site-setup-notes/）。
写 front matter — 文件最上方元数据，至少含 title、date、description；linkTitle 是列表/卡片上的短标题。
写正文 — 从 Obsidian 复制后改语法（见下节）；可加提示块、步骤列表、锚点、图片。
本地预览 — hugo server，打开 /blog/ 看卡片和文章页。
发布 — git add → git commit → git push，GitHub Actions 构建并更新 GitHub Pages。

front matter 模板：

---
title: 文章完整标题
linkTitle: 列表短标题
description: 一句话摘要，搜索和卡片会用。
date: 2026-08-29
tags: [Oink, Hugo]
---

Obsidian 迁到 Oink：语法对照

Obsidian	Oink / Markdown	处理
`==高亮==`	`加粗`	全部替换
`[[双链]]`	`[文字](/path/)` 或外链	改成真实链接
图片 `![[x.png]]`	`![说明](路径)`	见下文

Oink 常用组件（详见组件文档）：

提示块

> [!NOTE] 阅读提示
> 正文写在这里。

步骤列表 — 每行用 1.，末尾加 {.steps}（见上文「五步」）。

标题锚点 — ## 小节 {#id}，{#id} 不显示，用于 [文字](#id) 文内跳转。

图片与图注 — {caption="..."} 必须写在图片下一行（不能和 ![...](...) 挤同一行）：

![示意](/images/blog/example.png)
{caption="图注显示在图片正下方"}

全局图：放 static/images/...，文中用 /images/...
页面包：与 index.md 同目录，用相对路径

make 四条命令：改主题才需要

Makefile 里的四条是别名。Windows 上往往没有 make，且 make dev / make check 需要上级目录有 ../oink 主题源码。

命令	主题来源	适合
`make dev`	本地 `../oink`	改主题时快速预览
`make check`	本地 `../oink`	改主题后跑 `npm test`
`make build`	`go.mod` 固定版	正式构建，与线上一致
`make serve`	`go.mod` 固定版	生产配置本地预览

只写内容、不改主题时，用 PowerShell 等价即可：

目的	PowerShell
日常预览	`hugo server`
正式构建	`hugo --cleanDestinationDir --minify`
接近线上效果	`hugo server --environment production --minify`

dev 与 check 的分工

dev 偏快、给人看效果；check 偏慢、跑自动化测试。改主题时：先 dev 满意，再 check 过关。

发布：git 三步

确认本地预览无误后：

git add content/blog/oink-site-setup-notes.md
git commit -m "blog: add Oink site setup notes"
git push origin main

git add：选中本次要提交的文件（只提交博客就写具体路径；全部提交可用 git add -A）
git commit：在本地打快照
git push：推到 GitHub，触发 Actions 部署

顺序：add → commit → push。

小结

搭 Oink 站可以记一条主线：Hugo 生成页面，Oink 管样式，content/ 文件夹就是导航树。写博客 = front matter + Markdown 正文 + 本地 hugo server + push。图注记得换行写 {caption=...}；Obsidian 的 == 和 [[链接]] 发布前要改成标准 Markdown。

更系统的阅读顺序仍推荐 Oink 教程书第 1–3 章；本站 RAICOM 文档可作为写法范例对照。