Markdown+ 不是新格式。它是純 Markdown 加上三個習慣與一份受控 metadata 字彙表, 讓同一份文件既能被 AI 穩定查詢與修改,又能被 viewer 渲染成有導覽、卡片、儀表板的人類閱讀介面。
- **#current-state** 目前 Auth v2 在 production 運作。 - **#sla-kpi** SLA 99.92%, 距目標 0.03%。 - **#auth-v1** deprecated # 預設摺疊
AI 與人類對「好文件」期待相反。傳統做法走極端,兩邊都做不好。
Source 是給 AI 的純 Markdown + 受控 metadata。 View 由 viewer 把 source 渲染成漂亮 HTML。
Source 不負責長得漂亮,Viewer 不負責保存語義。兩邊各做自己擅長的事。
把這三件事做到位,AI 與人類同時受惠。
Source 必須是合法 CommonMark。GitHub、Obsidian、VS Code 看仍是清楚的 bullet list,絕無亂碼。
Source 承載語義 (metadata + prose);viewer 加上 nav、status pill、card、gauge、callout。視覺不寫進 source。
image / video / svg 一律外部相對路徑。base64 是 LLM context 殺手,一張圖可吃幾萬 tokens 還毫無語義。
設計哲學
Mermaid 在 GitHub render 成圖,在純文字 editor 看是合法 code fence。 Markdown+ 在 GitHub 看是有結構的 bullet list,在 viewer 看是有互動的文件。 Source 從頭到尾是合法 CommonMark,不需要任何 dialect 支援。
同一份 source,左邊是純 markdown viewer 看到的,右邊是 Markdown+ viewer 渲染。
- **#current-state** `type:state` `status:active`
目前 Auth v2 在 production 運作。
- **#sla-kpi** `type:kpi` `metric:API_SLA`
`value:99.92` `target:99.95`
API SLA 99.92%,目標 99.95%。
- **#auth-v1** `type:history`
`status:deprecated`
`visibility:collapsed`
Auth v1 把 token 直接放 cookie。AI 不再要按行掃整檔。可以 list_blocks() → read_block(id) 精準讀取。
歷史內容預設摺疊,AI 不會誤把已棄用內容當現況,人類也看得清楚。
metadata 約 10 tokens vs HTML card 200+ tokens。差距在大文件上會放大幾個數量級。
GitHub diff、grep、IDE preview 都正常 — 因為 source 仍是合法 CommonMark。
nav、卡片、gauge、callout 全由 metadata 自動推導,作者不寫 CSS 與 HTML。
type: / status: 為 closed list,viewer 才能穩定渲染、AI 才好 routing。