> 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/gitbook-syntax.md).

# GitBook 语法速查

标准 Markdown 全部可用。下面是 GitBook 额外提供的块语法 —— 每节先给源码，再给渲染效果。

## 页面 frontmatter

写在文件最顶部，三横线包裹：

```markdown
---
description: 一句话摘要，会出现在搜索结果和页面卡片里。
---

# 页面标题
```

{% hint style="warning" %}
`description` 是最值得认真写的字段。自造字段（`tags`、`date`、`author` 等）不会报错，但也不会被渲染 —— 想要标签效果，写在正文里。
{% endhint %}

## 提示框 hint

```markdown
{% hint style="info" %}
补充说明。
{% endhint %}
```

四种 `style`：

{% hint style="info" %}
`info` —— 补充信息、背景知识。
{% endhint %}

{% hint style="success" %}
`success` —— 推荐做法、验证通过的结论。
{% endhint %}

{% hint style="warning" %}
`warning` —— 容易踩的坑、需要注意的前提。
{% endhint %}

{% hint style="danger" %}
`danger` —— 有破坏性后果的操作。
{% endhint %}

## 代码块

普通代码块用标准 Markdown 三反引号即可。需要标题、换行或行号时用 `code` 块包一层：

````markdown
{% code title="deploy.sh" overflow="wrap" lineNumbers="true" %}
```bash
kubectl rollout status deployment/api
```
{% endcode %}
````

效果：

{% code title="deploy.sh" lineNumbers="true" %}

```bash
kubectl rollout status deployment/api --timeout=120s
kubectl get pods -l app=api
```

{% endcode %}

## 标签页 tabs

同一件事的多个变体（不同系统、不同语言、不同包管理器）适合用它，避免正文被平行方案撑长：

```markdown
{% tabs %}
{% tab title="macOS" %}
brew install foo
{% endtab %}

{% tab title="Ubuntu" %}
apt install foo
{% endtab %}
{% endtabs %}
```

效果：

{% tabs %}
{% tab title="macOS" %}

```bash
brew install foo
```

{% endtab %}

{% tab title="Ubuntu" %}

```bash
sudo apt update && sudo apt install -y foo
```

{% endtab %}
{% endtabs %}

## 折叠块

用原生 HTML，适合藏长日志、次要细节：

```markdown
<details>
<summary>完整报错栈</summary>

...

</details>
```

{% hint style="info" %}
`<summary>` 和内容之间要留一个**空行**，否则里面的 Markdown 不会被渲染。
{% endhint %}

效果：

<details>

<summary>点开看完整报错</summary>

```
panic: runtime error: invalid memory address
  goroutine 1 [running]:
  main.main()
```

</details>

## 页面引用卡片

比裸链接显眼，会自动带上目标页面的标题和 `description`：

```markdown
{% content-ref url="post-template.md" %}
[post-template.md](post-template.md)
{% endcontent-ref %}
```

效果：

{% content-ref url="/pages/gscgEOWjkdUD91lddHrs" %}
[文章模板](/xie-zuo-gui-fan/post-template.md)
{% endcontent-ref %}

## 外部嵌入

YouTube、CodePen、Figma 等会渲染成预览卡片，其余降级为链接：

```markdown
{% embed url="https://github.com/git-guides" %}
```

## 图片

图片统一放 `.gitbook/assets/`，**用相对路径**引用：

```markdown
![架构图](../.gitbook/assets/arch.png)
```

需要图注时用 `figure`：

```markdown
<figure>
  <img src="../.gitbook/assets/arch.png" alt="服务调用关系">
  <figcaption>图 1：服务调用关系</figcaption>
</figure>
```

## 卡片式表格

表头加 `data-view="cards"`，把表格渲染成卡片网格（首页导航常用）：

```markdown
<table data-view="cards">
  <thead>
    <tr><th></th><th></th><th data-hidden data-card-target data-type="content-ref"></th></tr>
  </thead>
  <tbody>
    <tr>
      <td><strong>标题</strong></td>
      <td>一句话描述</td>
      <td><a href="../posts/README.md">全部文章</a></td>
    </tr>
  </tbody>
</table>
```

## 常见坑

| 坑                          | 说明                                  |
| -------------------------- | ----------------------------------- |
| 文件没进 `SUMMARY.md`          | 页面不出现在侧边栏，等于没发布                     |
| 内部链接写渲染后的 URL              | 应该指向仓库里的 `.md` 文件相对路径，GitBook 会自动转换 |
| 图片用绝对路径                    | 本地预览正常，同步后碎图 —— 一律用相对路径             |
| 文件名含中文或空格                  | 会被百分号编码进 URL，分享时很难看                 |
| 多个一级标题 `#`                 | 每页只应有一个，其余降为 `##`                   |
| `<details>` 里 Markdown 不渲染 | `<summary>` 之后漏了空行                  |

## 参考

* [GitBook 官方文档](https://gitbook.com/docs) —— 块语法完整清单
* [Git Sync 说明](https://gitbook.com/docs/getting-started/git-sync) —— 仓库同步机制与配置


---

# 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/gitbook-syntax.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.