語法結構
Markdown+ 文件由
一份 H1 標題 + 一段引言 + 多個 bullet-list block
組成。每個 block 的開頭固定格式:
- **#<kebab-case-id>** `type:<value>` `<key>:<value>` ...
<block body, 縮排 2 spaces, 任意合法 Markdown>
- **#<child-id>** `type:<value>` ...
<子 block, 縮排 4 spaces>
組成元素
| 元件 | 規則 | 純 Markdown 渲染 | Markdown+ viewer 渲染 |
|---|
| Bullet | - | 圓點 | section 邊界 |
| Block ID | **#kebab-id** | 粗體 hashtag | anchor + id="" |
| Metadata | inline code `key:value` | monospace badge | 解析為 attribute |
| 父子 | nested bullet list 縮排 | 自然縮排 | <section> 巢狀 |
受控 metadata 字彙表
type: (block 主類型,closed list)
需要擴充必須用 x- 前綴。
| type | 用途 |
|---|
state | 描述當前事實 / 現況 |
history | 已不適用的歷史(預設摺疊) |
decision | 決策紀錄 |
record | 事件紀錄 (會議、incident) |
issue | 待解問題 / blocker |
note | 補充說明 |
spec | 規格 / 技術說明 |
task | 待辦 / action item |
reference | 外部連結彙整 |
figure / table / chart / diagram | 視覺資料 |
kpi / gauge / targets / dashboard / card | 儀表板元件 |
dialogue / turn | 對話容器與輪次 |
step | 教學 / runbook 步驟 |
status: (closed list)
draft
active
proposed
accepted
rejected
superseded
deprecated
archive
healthy
degraded
down
on-track
behind
exceeded
done
blocked
open
closed
其他常用 metadata
updated:YYYY-MM-DD — ISO 日期visibility:collapsed — viewer 預設摺疊priority:high|normal|low|criticaltags:[domain:auth,team:platform] — 用 namespacesuperseded-by:<id> — 指向替代者related:[id1,id2]variant-group:install + variant:mac — 同 group 的 sibling 會被 viewer 聚合成 tab- KPI:
value: target: delta: unit:
- Gauge:
value: min: max: target: zones:[99:red,99.9:amber,99.95:green]
必須遵守的約束關係
status:deprecated ⇒ 必有 superseded-by:<id>type:history ⇒ visibility:collapsedtype:kpi ⇒ value:,且與 prose 段數字一致type:gauge ⇒ value: min: max: target: zones: 全要- 同層共用
variant-group: 的 sibling 必須各有不同 variant:
- 每個
figure / chart / table / kpi / gauge / video / audio 必須有 prose companion 段
- 表格 > 30 列必須用
data-source:./data/<name>.csv
禁止清單 (lint error)
| 禁止項 | 替代 |
|---|
:::block fenced div | bullet list block |
Raw HTML 容器 (div / span / section ...) | 由 viewer 從 metadata 生成 |
<script> / <style> | 留給 viewer |
class="" / style="" | 留給 viewer |
Inline data:image/...;base64,... | 外部相對路徑 |
Inline <svg> |  |
| 巨型 inline chart spec (>80 行) | 拆到 ./charts/*.json |
| 巨型 inline 表格 (>30 列) | 拆到 ./data/*.csv |
寫死 caption 編號 (Figure 1:) | *Figure: ...*,viewer 自動編號 |
自由 type: 值 | 受控字彙表或 x- 前綴 |
設計理念對照
| 面向 | 傳統 Markdown | HTML | Markdown+ |
|---|
| 對 AI | 友善但難結構化 | tag 噪音、token 暴漲 | block-addressable + 受控 metadata |
| 對人類 | 陽春 | 漂亮但 source 不可讀 | viewer 渲染漂亮 + source 仍可讀 |
| 新 dialect | 無 | (N/A) | 無 — 仍是合法 CommonMark |
| 圖片 | 路徑或 base64 | 常用 base64 inline | 強制路徑,禁 base64 |
| 互動 UI | 無 | 需手寫 JS + CSS | 由 viewer 從 metadata 自動推導 |