> 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/xie-zuo-gui-fan/writing-workflow.md).

# 写作与发布流程

## 一篇文章的生命周期

```
notes/ 里的碎片
     ↓  攒够了，能讲清一件完整的事
posts/<分类>/<slug>.md    ← 复制 meta/post-template.md
     ↓  写完，过一遍检查清单
SUMMARY.md 挂上导航       ← 最容易漏的一步
     ↓  git push
GitBook 自动发布
```

## 具体步骤

### 1. 建文件

从模板复制，别从零开始 —— 模板里的 frontmatter 和结构能省掉不少纠结：

```bash
cp meta/post-template.md posts/tech/my-new-post.md
```

**文件名规则**：全小写、英文、连字符分隔，不带日期。

* ✅ `gitbook-blog-setup.md`
* ❌ `2026-07-27-GitBook 搭建.md`

文件名会直接进 URL。中文会被编码成一长串乱码，日期前缀则会在文章更新后显得过时 —— 时间信息交给正文和 Git 历史就够了。

### 2. 写

正文首行放标签和日期，方便站内搜索按主题捞文章：

```markdown
> `Kubernetes` · `排障` · 2026-07-27
```

图片放 `.gitbook/assets/`，用相对路径引用。GitBook 的扩展语法见 [语法速查](/xie-zuo-gui-fan/gitbook-syntax.md)。

### 3. 自检

* [ ] frontmatter 的 `description` 写了，且是完整的一句话（它会出现在搜索结果和卡片里）
* [ ] 一级标题 `#` 有且只有一个
* [ ] 技术类：环境版本、报错原文、可直接复制的命令，齐了
* [ ] 内部链接是**相对路径**，且指向 `.md` 文件（不是渲染后的 URL）
* [ ] 没有"待补充"这类残留占位

### 4. 挂进 SUMMARY.md

{% hint style="danger" %}
**这一步漏了，文章等于没发。**

GitBook 的侧边栏完全由 `SUMMARY.md` 决定。没登记的文件仍然在仓库里，直链也能打开，但读者不会看到任何入口。
{% endhint %}

在对应分类下加一行，注意缩进层级：

{% code title="SUMMARY.md" %}

```markdown
  * [技术](posts/tech/README.md)
    * [用 GitBook + Git 搭建个人博客](posts/tech/gitbook-blog-setup.md)
    * [我的新文章](posts/tech/my-new-post.md)
```

{% endcode %}

顺手在分类页 `posts/tech/README.md` 的文章列表里补一个 `content-ref` 卡片。

### 5. 提交并推送

```bash
git add .
git commit -m "post: 我的新文章"
git push
```

提交信息前缀约定：

| 前缀       | 用途                                               |
| -------- | ------------------------------------------------ |
| `post:`  | 新文章                                              |
| `fix:`   | 修订已发布内容（结论变更时同步更新 [更新日志](/guan-yu/changelog.md)） |
| `notes:` | 笔记本更新                                            |
| `chore:` | 配置、模板、结构调整                                       |

推送后 GitBook 会自动同步，通常一两分钟内上线。

## 修订已发布的文章

直接改正文，**不要**在文末堆一串"更正1、更正2"。让读者读到一篇正确的文章，比读一篇带勘误列表的旧文有用。

如果改动改变了结论 —— 方案失效、原结论是错的、有了更好的做法 —— 在 [更新日志](/guan-yu/changelog.md) 里记一条，说明改了什么、为什么。

## 删文章

尽量不删。真要删，在 `.gitbook.yaml` 里登记一条重定向，把旧路径指到替代内容：

{% code title=".gitbook.yaml" %}

```yaml
redirects:
  posts/tech/old-post: posts/tech/new-post.md
```

{% endcode %}

文章一旦被收藏或转发，删文件就是在制造死链。加一行配置的成本几乎为零。


---

# 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/xie-zuo-gui-fan/writing-workflow.md?ask=<question>&goal=<endgoal>
```

`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.