建站笔记：多站架构、怎么改、怎么编译、怎么在本地看¶

配套阅读：本文是博客引擎的选择 →、Hugo 从零搭建 →、GitHub Pages 分支区别 → 的「实操手册」版。前面几篇讲「为什么选」，这篇讲「怎么动手」。

我目前手上有五个站点，分别用三种引擎搭建，现在都并排在 wild-civil/ 工作区里统一管理。这篇文章把它们的目录结构、改哪里、怎么编译、怎么在本地看一次讲清，免得我自己过段时间也忘了。

想看更直白的「改哪里、敲哪行命令」版本，先看全站架构小白篇 →；想看引擎内部怎么运作，看全站架构进阶篇 →。

一、总览：我手里的五个站¶

站点	引擎	仓库目录	线上地址	部署方式	Pages 源（分支）
civil_wiki	MkDocs Material	`civil_wiki/`	wiki.hanvon.top	GitHub Actions 自动	`gh-pages`（项目页）
civil_digest	MkDocs Material	`civil_digest/`	digest.hanvon.top	GitHub Actions 自动	`gh-pages`（项目页）
civil_nav	Hugo 0.147.7	`civil_nav/`	nav.hanvon.top	GitHub Actions 自动	`gh-pages`（项目页）
civil_works	Hugo 0.147.7	`civil_works/`	works.hanvon.top	GitHub Actions 自动	`gh-pages`（项目页）
Civil_Blog	Hexo 5.4.2	`Civil_Blog/`	blog.hanvon.top	手动 `hexo d`	`main`（用户页）

几个要点先说清楚：

wiki / digest / nav / works 都是「项目页」：仓库名不是 <user>.github.io，所以 GitHub 默认从 gh-pages 分支 serve；每次 git push 触发 Actions 自动构建。
Civil_Blog 是「用户页」：它的线上仓库名就是 wild-civil.github.io，所以成品直接回写到 main 分支，靠 hexo d 手动推送（仓库里没有 Actions 工作流，只有 dependabot.yml）。这正好对应我之前写的「用户页成品就是 main」。
五站现在在同一个 wild-civil/ 工作区并排，引擎不同但一起管；导航站（nav）已经把 Wiki / 博客都链进去了，访问体验上已经「放进来」。

二、civil_nav —— Hugo 导航站¶

2.1 目录结构¶

civil_nav/
├── config.toml            # 站点标题、baseURL、顶栏参数（wiki/github 链接）
├── data/links.yaml        # ★ 内容数据：分区 + 卡片（平时只改这里）
├── layouts/index.html     # 整页模板（Webstack 风格：左侧固定栏 + 右侧卡片网格）
├── static/                # 原样拷到站点根目录
│   ├── CNAME              # 自定义域名文件（nav.hanvon.top）
│   └── assets/            # CSS / JS / 字体 / 图片（xenon 主题资源）
├── content/_index.md      # 首页桩文件（仅 frontmatter，无正文）
├── .github/workflows/ci.yml
└── .gitignore

2.2 怎么改¶

加 / 改链接：只编辑 data/links.yaml，不用碰模板。结构如下（我现在填了 3 个分区：Civil's Nav / 友链 / 常用工具）：

sections:
  - title: Civil's Nav       # 分区标题
    icon: star               # 分区图标（FontAwesome 4.7 名字，不含 fa- 前缀）
    items:
      - name: Wiki 知识库     # 卡片标题
        desc: 我的学习笔记与知识库
        url: https://wiki.hanvon.top
        # icon: https://.../logo.png   # 可选：不填就自动用该域名的 favicon

卡片图标默认按 url 域名用 Google Favicon 服务自动取；想强制用某张图，就填 icon:。

改站名 / 副标题 / 页脚 / 顶栏链接：编辑 config.toml 的 title、params.subtitle、params.footer、params.wiki、params.github。
换图标（favicon / logo）：替换 static/assets/images/favicon.png、logo@2x.png 等，或改 layouts/index.html 里对应的 <img src>。
改样式：编辑 static/assets/css/nav.css（白卡 + hover 上浮）或 xenon 系列 CSS；一般不用动 layouts/index.html。

2.3 本地编译¶

cd civil_nav
D:/tools/hugo/hugo.exe --minify      # 生成 public/

产物在 public/：根目录有 index.html、CNAME、assets/。

2.4 本地预览¶

实时预览（推荐，改文件自动刷新）：

D:/tools/hugo/hugo.exe server --bind 127.0.0.1 --port 1313
# 浏览器打开 http://127.0.0.1:1313/

纯静态看：先 hugo --minify 生成 public/，再起一个静态服务器（不要直接双击 file:// 打开，原因见第八节）：

cd public && python -m http.server 8080
# 浏览器打开 http://127.0.0.1:8080/

2.5 部署¶

git add -A && git commit -m "update nav" && git push

push 后 GitHub Actions（ci.yml）自动 hugo --minify 并推到 gh-pages，GitHub Pages 重新发布。

三、civil_works —— Hugo 作品集¶

套路和 nav 完全一样（都是 Hugo 单页站），这里只列差异。

3.1 目录结构¶

civil_works/
├── config.toml
├── data/projects.yaml      # ★ 内容：分类 + 项目
├── layouts/index.html      # 筛选网格（filterSelection 脚本驱动按钮）
├── static/
│   ├── CNAME
│   ├── favicon.svg         # 站点图标（复用 wiki 的书本 logo）
│   └── assets/index.css, index.js
└── .github/workflows/ci.yml

3.2 怎么改¶

加 / 改作品：编辑 data/projects.yaml。categories 是顶部筛选按钮，items 是卡片：

categories: [MCU, Linux, Sensor, Power]   # 顶部筛选按钮，按需增删

items:
  - name: 项目名
    desc: 一句话简介
    categories: [MCU]        # 可多个，决定被哪些按钮筛出
    website: https://...      # 可选：作品主页
    repo: https://github.com/...   # 可选：源码仓库
    image: /images/xxx.png    # 可选：封面图（放 static/images/ 或外链）

加封面图：把图放进 static/images/，再在 yaml 写 image: /images/xxx.png；也可以直接填外链 image: https://.../xxx.png。
换图标 / 样式：同上，替换 static/favicon.svg 或改 static/assets/index.css。

3.3 本地编译与预览¶

同 nav：hugo --minify 出 public/；hugo server 实时预览。筛选按钮在本地一样可用。

3.4 部署¶

同 nav：git push → Actions → gh-pages。

四、civil_wiki —— MkDocs 知识库（项目页）¶

MkDocs 是内容驱动：你写 Markdown，它按 mkdocs.yml 把文章织成站点。本站最大、最常用的就是它（你现在读的这篇就在它里面）。

4.1 目录结构¶

civil_wiki/
├── mkdocs.yml                 # 全局配置 + 导航(nav) + 主题(material) + 插件
├── requirements.txt           # Python 依赖（mkdocs-material 等）
├── docs/
│   ├── index.md               # 首页
│   ├── 硬件与半导体/          # 按主题分区的笔记（含 显示与屏幕 / 射频与天线 等子章）
│   ├── 阅读与学习/
│   ├── 杂记/                  # 站内随笔（对应导航里的「杂记」分区）
│   └── stylesheets/extra.css  # 自定义样式（换中文字体、给图片加描边等）
├── overrides/main.html        # 主题覆盖（Jinja2，extends base.html）
└── .github/workflows/ci.yml   # 推送 main 时自动 mkdocs gh-deploy --force

4.2 怎么改¶

加一篇笔记：在 docs/ 对应分区文件夹新建 xxx.md，再到 mkdocs.yml 的 nav: 里加一行指向它：

nav:
  - 硬件与半导体:
      - 硬件与半导体/index.md
      - 硬件与半导体/我的新笔记.md   # ← 加这一行

改站点级配置：编辑 mkdocs.yml（nav / theme / plugins / extra_css / markdown_extensions）。
改样式 / 注入元信息：编辑 docs/stylesheets/extra.css，或用 overrides/main.html（Jinja2）改 <head>。
嫌手动维护 nav 麻烦：把整个 nav: 块删掉，MkDocs 会自动按文件名列出所有页面。

⚠️ 大坑：nav 里引用的文件必须真实存在，否则 CI 构建直接报错、gh-deploy 不执行，结果整站不更新（曾经就因为 nav 引用了未提交的文件，导致新章节上线失败）。每次 push 前确认 nav 引用的 .md 都已提交。

4.3 本地编译与预览¶

首次用前先装依赖：

cd civil_wiki
pip install -r requirements.txt   # 装一次即可
mkdocs serve -a 127.0.0.1:8000    # 实时预览，改文件自动重建
# 浏览器打开 http://127.0.0.1:8000/

纯静态看：mkdocs build（默认出 site/），再 cd site && python -m http.server 8000。
MkDocs 站点必须通过 mkdocs serve 或 python -m http.server 看，别直接双击 site/index.html（file:// 下资源路径会错，见第八节）。

4.4 部署¶

git add -A && git commit -m "update wiki" && git push

push 后 GitHub Actions 跑 mkdocs gh-deploy --force，把 site/ 推到 gh-pages 分支，GitHub Pages 据此发布 wiki.hanvon.top。

五、civil_digest —— MkDocs 书摘（项目页）¶

和 wiki 同一套引擎、同一套路，只是结构更轻量（书摘站目前基本只有首页）。

5.1 目录结构¶

civil_digest/
├── mkdocs.yml                 # 全局配置 + 导航(nav) + 主题
├── requirements.txt           # Python 依赖
├── docs/
│   ├── index.md               # 书摘首页（好句都追加在这里）
│   └── stylesheets/extra.css  # 自定义样式
└── .github/workflows/ci.yml   # 自动 mkdocs gh-deploy --force

5.2 怎么改 / 编译 / 预览 / 部署¶

加一条书摘：直接编辑 docs/index.md 在末尾追加；或新建 书名/章节.md，再到 mkdocs.yml 的 nav: 加一行。
本地预览：mkdocs serve（默认 :8000）。
部署：git push → Actions → gh-deploy 到 gh-pages → 发布 digest.hanvon.top。

六、Civil_Blog —— Hexo 博客（用户页）¶

6.1 目录结构¶

Civil_Blog/
├── _config.yml             # 站点配置（title / url / 部署 / permalink）
├── _config.butterfly.yml   # 主题配置（butterfly 主题专属）
├── source/
│   ├── _posts/             # ★ 文章（27 篇 .md，按 001~027 编号）
│   ├── images/             # 文章图片
│   ├── css/ js/            # 自定义样式 / 脚本
│   ├── categories/ tags/ link/   # 分类 / 标签 / 友链页
│   └── CNAME               # blog.hanvon.top
├── themes/
│   ├── butterfly/          # 当前启用的主题（在 _config.yml 里 theme: butterfly）
│   └── landscape/          # 也装了但没启用
├── scaffolds/              # 新建文章模板（post.md / page.md / draft.md）
├── node_modules/           # 依赖已装（含 hexo 可执行）
└── package.json            # 脚本：clean / generate / deploy / server

注意：仓库里没有 .github/workflows/ci.yml，所以不自动部署，靠手动 hexo d。

6.2 怎么改¶

写新文章：

cd Civil_Blog
npx hexo new "文章标题"     # 在 source/_posts/ 生成「文章标题.md」（按 scaffolds/post.md 模板）

或直接新建 source/_posts/xxx.md，front-matter 至少要有 title:、date:、tags:、categories:。我现在那 27 篇文章就是这种 .md。

改站点信息：编辑 _config.yml（title、subtitle、author、url；permalink 用了 abbrlink 算法生成短链）。
改主题外观：编辑 _config.butterfly.yml——这是 butterfly 的专属配置，比改 _config.yml 更常用（配色、首页、菜单、侧栏、友链大多在这里）。
改导航 / 侧栏 / 友链：butterfly 多用 _config.butterfly.yml 的 menu，或 source/_data/*.yml（如 link.yml、widget.yml）。
加图片：丢进 source/images/，文章里用 ![说明](/images/xxx.png) 引用，构建后随站发布。

6.3 本地编译¶

Hexo 的核心命令：

cd Civil_Blog
npx hexo clean        # 清空 public/ 与缓存 db.json（排错第一步）
npx hexo generate     # 生成 public/（等价 hexo g）

hexo clean 在改了主题配置或遇到缓存错乱时很关键；平时只改文章直接 hexo g 就行。

6.4 本地预览¶

实时预览（推荐）：

npx hexo server      # 默认 http://localhost:4000 ，改文件自动刷新
# 想连草稿一起看：hexo s -d

纯静态看：hexo g 出 public/，再起静态服务器：

cd public && python -m http.server 8080
# 浏览器打开 http://127.0.0.1:8080/

6.5 部署（手动）¶

npx hexo deploy        # 等价 hexo d；按 _config.yml 的 deploy 配置推送

_config.yml 里已经配好：

deploy:
  type: git
  repository: https://github.com/wild-civil/wild-civil.github.io.git
  branch: main

所以 hexo d 把 public/ 推到用户页仓库的 main——这就是前面说的「用户页成品就在 main」。source/CNAME（blog.hanvon.top）构建后自动落到 public/ 根，GitHub Pages 据此绑定自定义域名。

想也给它接 CI 自动部署？可以参考我写的从零搭建多站点 MkDocs →，给 Civil_Blog 加一个 hexo g + actions-gh-pages 的工作流。但用户页默认就是 main，直接 hexo d 最简单，所以我目前保留手动部署。

七、命令对照表（MkDocs vs Hugo vs Hexo）¶

目的	MkDocs（wiki / digest）	Hugo（nav / works）	Hexo（Civil_Blog）
内容模型	内容驱动：每篇 `.md` = 一页	数据驱动：`data/*.yaml` + 模板	内容驱动：`source/_posts/*.md` = 文章
清理缓存	（一般无需；必要时删 `site/`）	（一般无需；必要时删 `resources/` 或 `hugo --gc`）	`hexo clean`
生成静态站	`mkdocs build`（出 `site/`）	`hugo` / `hugo --minify`（出 `public/`）	`hexo generate` / `hexo g`（出 `public/`）
本地实时预览	`mkdocs serve`（`:8000`）	`hugo server`（`:1313`）	`hexo server` / `hexo s`（`:4000`）
部署上线	`git push`（Actions 跑 `gh-deploy` → `gh-pages`）	`git push`（Actions → `gh-pages`）	`hexo deploy` / `hexo d`（手动推 `main`）
新建内容	手写 `docs/*.md` + 改 `nav`	手写 `data/*.yaml` 或 `.md`	`hexo new "标题"`

核心区别一句话：MkDocs / Hugo 站是「push 即自动部署」（项目页走 gh-pages）；Hexo 站是「文章驱动 + 手动 hexo d 部署」（用户页机制决定了回写 main）。

八、关于「本地静态显示」的两个坑¶

别直接双击 site/ 或 public/ 里的 index.html 用 file:// 打开。 MkDocs / Hugo / Hexo 生成的资源路径是绝对路径（如 /assets/css/...）。file:// 下浏览器会把 / 当成磁盘根，结果 CSS / JS 全部 404，页面「裸奔」。正确做法是用 mkdocs serve / hugo server / hexo s 或 python -m http.server（从产物目录起服务）。
Hexo 同理。 尤其开了绝对资源路径或 abbrlink 短链后，直接 file:// 也可能缺资源。统一用引擎自带 server 或 python -m http.server 最稳。

一句话：本地看效果，要么用引擎自带的 server，要么用 python -m http.server 起一个真·HTTP 服务；别用 file:// 直接开产物目录。

九、小结¶

civil_wiki / civil_digest（MkDocs）：加 docs/*.md → mkdocs serve 本地看 → git push 上线（Actions gh-deploy → gh-pages 项目页）。
nav / works（Hugo）：改 data/*.yaml → hugo server 本地看 → git push 上线（Actions 编译到 gh-pages 项目页）。
Civil_Blog（Hexo）：写 source/_posts/*.md → hexo s 本地看 → hexo clean && hexo g && hexo d 上线（手动回写用户页 main）。
五站现在都在 wild-civil/ 工作区，三种引擎但并排管理；导航站已经把 Wiki / 博客都链进去了，访问体验上已经「放进来」了。

如果你也想像 nav / works 那样「push 就自动部署」，我可以给 Civil_Blog 补一个 GitHub Actions 工作流——只要说一声。