建站笔记-全站架构小白篇

这篇是「小白版」：只告诉你改哪里、敲哪行命令、在浏览器输什么地址。想看引擎内部是怎么运作的（目录解剖、模板、CI/CD、自定义主题），去看进阶版 → 全站架构进阶篇 →。如果只关心其中某几个站的操作，也先看这篇，再看多站架构与本地预览 →。

一、我的"站点家族"一览¶

我把不同性质的内容拆成了五个独立的站，分别用三种静态站点生成器（下面叫"引擎"）来做：

站点仓库	是干嘛的	用的引擎	线上地址	仓库类型
`civil_wiki`	我的知识库（文档/笔记）	MkDocs Material	`wiki.hanvon.top`	项目页
`civil_digest`	我的书摘（读书好句）	MkDocs Material	`digest.hanvon.top`	项目页
`civil_nav`	我的导航（友链/工具入口）	Hugo	`nav.hanvon.top`	项目页
`civil_works`	我的作品集（硬件项目）	Hugo	`works.hanvon.top`	项目页
`Civil_Blog`	我的博客（时间线文章）	Hexo	`blog.hanvon.top`	用户页

为什么拆这么多？因为没有一种引擎适合所有内容：写文档用 MkDocs 最舒服，做导航/作品集用 Hugo 最灵活，写博客用 Hexo 最顺手。拆开后每个站都"趁手"。引擎之间的区别可看 → 博客引擎的选择 →。

二、三个引擎一句话说清（大白话）¶

把"引擎"想成厨师，把"Markdown / 数据文件"想成食材，把"构建"想成做菜，把"部署"想成上桌：

MkDocs（Material 主题）：你写一篇篇 Markdown 文章，它帮你排好版、生成目录和搜索。适合文档、笔记、书摘这类"一篇篇"的内容。civil_wiki 和 civil_digest 都是它。
Hugo：你写一个数据文件（YAML）+ 一个页面模板，它把数据"填"进模板生成网页。适合导航页、作品集这种"结构固定、内容是一条条数据"的页面。civil_nav 和 civil_works 都是它。
Hexo：专门给博客用的。你在 source/_posts/ 里写带日期的文章，它按时间排好、生成归档和标签页。Civil_Blog 就是它。

记住一句话就够：文档 → MkDocs；导航/作品集 → Hugo；博客 → Hexo。

三、最常见的改动（照葫芦画瓢）¶

下面每一步都是"改完 → 提交 → 推送"三连。初学者先学会改文件，推送命令在第五节统一给。

1）加一条书摘（`civil_digest`）¶

书摘站很轻量，目前导航只有首页。两种方式：

偷懒：直接打开 civil_digest/docs/index.md，在末尾追加：
```
> "你想记的一句话。"
> —— 《书名》/ 作者
```
分篇：在 civil_digest/docs/ 下新建 书名/章节.md，写同样格式，然后到 mkdocs.yml 的 nav: 里加一行：
```
nav:
  - 我的书摘: index.md
  - 某本书: 书名/章节.md
```

2）加一篇知识库笔记（`civil_wiki`）¶

知识库是按文件夹分区的（如 硬件与半导体/、技术与编程/）。加一篇新笔记：

在 civil_wiki/docs/ 对应的分类文件夹里，新建一个 xxx.md；

打开仓库根目录的 mkdocs.yml，在 nav: 对应分区下加一行指向它：

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

文章顶部加 front-matter（至少要有标题）：

---
title: 我的新笔记
---

正文写这里……

嫌手动维护 nav 麻烦？把整个 nav: 块删掉，MkDocs 会自动按文件名列出所有页面。

3）在导航站加一个链接（`civil_nav`）¶

导航站完全由数据驱动，你不用碰 HTML。改 civil_nav/data/links.yaml：

sections:
  - title: 友链            # 分区标题
    icon: link             # 分区图标（FontAwesome 4.7 名字，不带 fa- 前缀）
    items:
      - name: 某某博客      # 卡片标题
        desc: 一句话简介    # 卡片描述
        url: https://xxx.com
        # icon: https://xxx.com/logo.png   # 可选：不写就自动用该域名的 favicon

照着已有的条目复制一份、改改文字即可。

4）在作品集加一个项目（`civil_works`）¶

同样只改数据文件 civil_works/data/projects.yaml：

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

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

5）写一篇博客（`Civil_Blog`）¶

博客文章放在 Civil_Blog/source/_posts/：

在那里新建 2026-07-20-我的文章.md；

顶部写 front-matter：

---
title: 我的文章
date: 2026-07-20 12:00:00
tags: [随笔]
---

正文用 Markdown 写。

四、怎么在本地"看效果"（serve）¶

改完别急着推送，先在本地预览确认没问题。每个引擎一条命令，跑起来后打开对应的浏览器地址即可。

站点	在哪运行命令	命令	浏览器打开
`civil_wiki` / `civil_digest`	仓库根目录	`mkdocs serve`	`http://127.0.0.1:8000`
`civil_nav` / `civil_works`	仓库根目录	`hugo server`	`http://localhost:1313`
`Civil_Blog`	仓库根目录	`hexo clean && hexo g && hexo s`	`http://localhost:4000`

首次用 MkDocs 前，先 pip install -r requirements.txt 装依赖；首次用 Hexo 前，先 npm install 装依赖（装一次即可）。 hugo server / mkdocs serve / hexo s 都是带热更新的：你改文件保存，浏览器会自动刷新。

预览完按 Ctrl+C 停止本地服务。

五、怎么发布上线（一句话）¶

站点	发布命令	说明
`civil_wiki` / `civil_digest` / `civil_nav` / `civil_works`	`git add -A && git commit -m "改了啥" && git push`	推送后 GitHub Actions 自动构建并上线，约 1–2 分钟
`Civil_Blog`	`hexo clean && hexo g && hexo d`	`hexo d` 直接把成品推到 `wild-civil.github.io` 的 `main` 分支

关于"为什么有的是 gh-pages、有的是 main"：项目页（前四个）成品默认走 gh-pages；用户页博客（Civil_Blog）成品直接走 main。详细区别看 → GitHub Pages 分支区别 →。

六、两个千万别踩的坑¶

别用 file:// 直接双击打开 public/ 或 site/ 里的 index.html。构建出的网页引用资源用的是绝对路径（如 /assets/xxx.css），直接双击会因为路径不对而样式全崩。一定要用第四节的"本地服务"命令（或 python -m http.server）来看。
改完要 git push（博客要 hexo d）才会上线。本地预览只是你电脑上看，不推送别人看不到。

七、下一步看什么¶

想知道每个引擎内部怎么运作、目录里每个文件是干嘛的、怎么自定义样式/模板、CI 到底干了啥 → 全站架构进阶篇 →
想知道某几个站更聚焦的操作 → 多站架构与本地预览 →
想知道我为什么选这三个引擎 → 博客引擎的选择 →