從零開始寫第一份 Markdown+

跟著下面六步,你就能寫出一份合法、可被 viewer 渲染、可被 AI 查詢的 Markdown+ 文件。 每一步都附「為什麼」與「常見錯誤」。

1

開頭:H1 + 引言

# Q2 2026 Auth Service Review

涵蓋現況、決策、KPI 與未解問題。

規則:整份文件只能有一個 # H1。H1 之後可接 0–1 段純散文,然後就是 bullet block。

常見錯誤:H1 之後直接接 ## 章節 heading。Markdown+ 不用 H2 切章節,章節由 bullet block 承擔。

2

第一個 block

Source
- **#current-state** `type:state` `status:active` `updated:2026-05-13`
  目前 Auth v2 在 production 運作,
  refresh token 由 gateway 統一處理。
Viewer 渲染
Current State Active2026-05-13
目前 Auth v2 在 production 運作,refresh token 由 gateway 統一處理。

三件事必填:ID **#kebab-case**(文件內唯一)、type:(從受控字彙表選)、body 縮排 2 spaces。

常見錯誤:ID 取成 block-1 或 section-a。語義鎖死的 ID 才能讓未來的 cross-link 不腐爛。

3

子 block(縮排 + variant-group)

- **#install** `type:spec`
  Client SDK 安裝方式。

  - **#install-py** `type:step` `variant-group:install` `variant:python`
    ```bash
    pip install auth-sdk
    ```
    Python 3.10+ 透過 pip 安裝。

  - **#install-js** `type:step` `variant-group:install` `variant:javascript`
    ```bash
    npm install @company/auth-sdk
    ```
    支援 Node 18+。

父子靠縮排:子 block 比父多縮 2 spaces。

聚合成 tab:同層 siblings 共用 variant-group: 時,viewer 自動聚合成 tab UI。純 markdown viewer 看仍是三個並排 sibling。

4

視覺資料 (figure / table / chart / KPI)

Source
- **#sla-gauge** `type:gauge` `metric:API_SLA`
  `value:99.92` `unit:%` `min:99.0` `max:100`
  `target:99.95`
  `zones:[99.0:red,99.9:amber,99.95:green]`

  *Gauge: API SLA(目標 99.95%)*

  目前落在 amber 區間。距 green
  區間還差 0.03 個百分點。
Viewer 渲染
API SLA
99.92% target 99.95%
目前落在 amber 區間。距 green 區間還差 0.03 個百分點。

三層必填:metadata 提供精準語義、上方 italic caption(viewer 自動編號)、最後 prose companion(必須) — 讓 AI 不用渲染圖也能利用這個 block。

禁忌:不寫死 *Gauge 1: ...*、不 inline base64、不 inline svg。

5

歷史 / 棄用內容

- **#auth-v1** `type:history` `status:deprecated` `superseded-by:current-state` `visibility:collapsed`
  Auth v1 把 access token 直接放在 cookie。2026-02 棄用,
  所有流量遷移至 Auth v2。

規則:

  • type:history ⇒ 必有 visibility:collapsed
  • status:deprecated ⇒ 必有 superseded-by: 指向替代者的 block id

為什麼:歷史內容預設摺疊,viewer 才不會讓 reader 把已棄用內容誤當現況,AI 也不會搞混。

6

Cross-link 與 callout

> [!IMPORTANT]
> 5/3 那次 outage 與 token service memory leak 有關,
> 詳見 `#inc-2026-05-03`,hotfix PR 已 merge。

- **#related-docs** `type:reference` `related:[decision-canary,inc-2026-05-03]`
  - Spec: `./specs/token-service-v2.md`
  - Incident report: `./incidents/2026-05-03.md`

用 GFM alert > [!NOTE] / [!WARNING] / [!IMPORTANT] / [!TIP] / [!CAUTION] 寫 callout,viewer 渲染成 colored box,純 markdown viewer 就是 blockquote。

related: 接 block id 清單,viewer 渲染成可點擊跳轉。

完成前檢核

  • 每個 block 都有 **#id** + type:
  • ID 是 kebab-case 且文件內唯一
  • 沒有 ::: fence
  • 沒有 raw HTML wrapper
  • 沒有 base64 / inline SVG
  • 所有 figure / table / chart / KPI / gauge 都有 prose 段
  • 表格 >30 列 → 拆 CSV
  • Caption 沒寫死編號
  • status:deprecated 都有 superseded-by:
  • type:history 都有 visibility:collapsed
  • type:kpi 的 value: 與 prose 數字一致
前往 Playground 試試 →