> For the complete documentation index, see [llms.txt](https://book.funcd.org/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://book.funcd.org/wen-zhang/posts/tech/gitbook-blog-setup.md).
# 用 GitBook + Git 搭建个人博客
> `GitBook` · `工具` · 2026-07-27
## 为什么是 GitBook
我要的博客只有三个硬需求：**源文件是纯 Markdown**、**版本由 Git 管**、**不想维护构建流水线**。
静态生成器（Hugo / VitePress 之类）满足前两条，但主题、构建、部署三件事都得自己养着。GitBook 的 Git Sync 正好补上第三条：仓库推上去就发布，托管、搜索、全文索引、暗色模式都是现成的。代价是渲染层不归我控制 —— 对一个个人博客来说，这笔交易划算。
## 仓库长什么样
```
.
├── .gitbook.yaml # 站点配置：根目录、README、SUMMARY 的位置
├── README.md # 站点首页
├── SUMMARY.md # 侧边栏导航（GitBook 唯一认的目录文件）
├── posts/
│ ├── README.md
│ ├── tech/ # 技术文章
│ └── life/ # 随笔
├── notes/ # 未成文的碎片
├── about/ # 关于我、更新日志
└── meta/ # 写作规范、模板、语法速查
```
按主题分目录而不是按年份。翻旧文的时候，"我写过 K8s 的什么"比"2025 年我写过啥"更常见。
## 两个关键文件
### SUMMARY.md 决定导航
GitBook 完全按 `SUMMARY.md` 渲染左侧目录 —— 层级靠缩进，分组靠 `##` 标题：
{% code title="SUMMARY.md" %}
```markdown
# Table of contents
* [欢迎](README.md)
## 文章
* [全部文章](posts/README.md)
* [技术](posts/tech/README.md)
* [用 GitBook + Git 搭建个人博客](posts/tech/gitbook-blog-setup.md)
```
{% endcode %}
{% hint style="warning" %}
**没写进 SUMMARY 的 Markdown 文件不会出现在侧边栏。**
文件仍然在仓库里、链接也能直接访问，但读者找不到入口。新增文章时改 SUMMARY 是最容易漏的一步 —— 我的做法是把它写进 [发布流程](/xie-zuo-gui-fan/writing-workflow.md) 的检查清单，而不是指望自己记得。
{% endhint %}
### .gitbook.yaml 定位置
{% code title=".gitbook.yaml" %}
```yaml
root: ./
structure:
readme: README.md
summary: SUMMARY.md
# 文章改名后登记旧路径，避免外链 404
# redirects:
# posts/hello: posts/tech/gitbook-blog-setup.md
```
{% endcode %}
`root` 指向文档根。如果博客只是某个大仓库里的一个子目录，把它改成 `./docs/` 之类即可，其余路径都相对于它。
`redirects` 值得从第一天就用起来：文章一旦被人收藏或转发，改文件名就等于制造死链，登记一条重定向的成本几乎为零。
## 接上 Git Sync
在 GitBook 的 Space 设置里找到 **Git Sync**，授权 GitHub / GitLab，选好仓库和分支，然后 —— 这一步要看清楚 —— 选择**首次同步的方向**。
{% hint style="danger" %}
方向选反会**覆盖**目标端的内容。
* 仓库里已经有 Markdown（比如现在这种情况）→ 选 **Git → GitBook**
* 内容在 GitBook 里已经写好、仓库是空的 → 选 **GitBook → Git**
拿不准就先把仓库推到一个临时分支上试同步，确认无误再切主分支。
{% endhint %}
接通之后是双向的：本地 `git push` 会触发站点更新，在 GitBook 网页编辑器里的改动则会以 commit 的形式回推到仓库。我基本只用前一个方向 —— 编辑器适合改错别字，成篇的东西还是在本地写着顺手。
## 用得上的扩展语法
GitBook 在标准 Markdown 之上加了一层块语法，日常够用的就这几个：
{% tabs %}
{% tab title="提示框" %}
四种样式：`info` / `success` / `warning` / `danger`。
```markdown
{% hint style="warning" %}
生产环境执行前先在 staging 验证。
{% endhint %}
```
{% endtab %}
{% tab title="折叠块" %}
直接用 HTML，适合藏冗长的日志：
```markdown
完整报错栈
...一大段日志...
```
{% endtab %}
{% tab title="页面引用" %}
渲染成带标题和摘要的卡片，比裸链接显眼：
```markdown
{% content-ref url="../life/why-i-write.md" %}
[why-i-write.md](../life/why-i-write.md)
{% endcontent-ref %}
```
{% endtab %}
{% endtabs %}
完整清单整理在 [GitBook 语法速查](/xie-zuo-gui-fan/gitbook-syntax.md)。
## 三个踩过的坑
图片路径必须是相对路径
图片放 `.gitbook/assets/`，正文里用相对路径引用：
```markdown
```
用绝对路径 `/assets/arch.png` 在本地编辑器里看着正常，同步到 GitBook 之后是碎图。
文件名不要用中文和空格
文件名会直接进 URL。中文名会被百分号编码成一长串，分享出去很难看，个别客户端还会截断。
正文标题随便用中文，**文件名一律小写英文加连字符**。
frontmatter 只认 GitBook 支持的字段
`description` 会被用作页面摘要和搜索结果里的说明文字，值得认真写。自造的字段（`tags`、`date` 之类）不会报错，但也不会渲染 —— 想要标签效果，写在正文里比塞 frontmatter 有用。
## 小结
整套东西的核心其实只有两个文件：`SUMMARY.md` 管导航，`.gitbook.yaml` 管位置。剩下的就是好好写 Markdown，然后 `git push`。
写作和发布的完整流程见下一篇：
{% content-ref url="/pages/9TimnsUZwm2B7LJNX0KD" %}
[写作与发布流程](/xie-zuo-gui-fan/writing-workflow.md)
{% endcontent-ref %}
---
# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.
## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.
Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:
```
GET https://book.funcd.org/wen-zhang/posts/tech/gitbook-blog-setup.md?ask=&goal=
```
`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.
Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.