Block Syntax Specification
@Doc Block Syntax Specification v1.5
⚠️ この文書は AI による翻訳です。誤りが含まれる可能性があります。 正確な内容を確認したい場合は、繁體中文版 または English 版 をご参照ください。
0. 目次
- 1. 設計思想
- 2. ドキュメント AST 構造
- 3. EBNF
- 4. 共有コンポーネント
- 5. 構造ブロック
- 6. コンテナブロック
- 7. コールアウトブロック
- 8. ウィジェットブロック
- 9. メタデータ
- 10. コア原則
- 11. 簡易構文エイリアス
1. 設計思想
@Doc Block Syntax が採用しているのは:
Semantic First, Layout Later
ブロックノードが記述するのは:
文書の意味(What)
であり、次のものではない:
表現方法(How)
そのため @Doc は次のものを提供しない:
@div@span(汎用レイアウトラッパーとして)@flex@grid@row@col@class@style
Renderer はプラットフォームに応じて自由に決定できる:
- HTML
- React
- DOCX
- Discord
- Terminal
- Notion
- AI UI
2. ドキュメント AST 構造
Document AST
│
├── Metadata
│ └── @meta
│
├── Block Nodes
│ │
│ ├── Structural Blocks
│ │ ├── @heading (alias: @h)
│ │ ├── @paragraph (alias: @p)
│ │ ├── @quote
│ │ ├── @list
│ │ ├── @code
│ │ ├── @img
│ │ ├── @table
│ │ ├── @hr
│ │ └── @svg
│ │
│ ├── Container Blocks
│ │ ├── @details
│ │ └── @card
│ │
│ ├── Callout Blocks
│ │ ├── @note
│ │ ├── @tip
│ │ ├── @important
│ │ ├── @warning
│ │ └── @caution
│ │
│ └── Widget Blocks
│ ├── @tabs
│ ├── @tab
│ └── @mermaid
│
└── Inline Nodes
│
├── Text Formatting
│ ├── @mark
│ ├── @color
│ ├── @bordered
│ ├── @bold (alias: @b)
│ ├── @italic (alias: @i)
│ ├── @underline (alias: @u)
│ ├── @del
│ └── @raw
│
├── Semantic Inline
│ ├── @sup
│ ├── @sub
│ ├── @kbd
│ ├── @link
│ ├── @spoiler
│ └── @hex
│
├── Footnotes
│ ├── @fn
│ └── @defn
│
└── Special Nodes
├── @n
└── @@3. EBNF
document =
[ metadata ],
{ block-node } ;
block-node =
heading
| paragraph
| quote
| list
| code
| image
| table
| hr
| svg
| details
| card
| note
| tip
| important
| warning
| caution
| tabs
| mermaid ;
(* Note:
`tab` は block-node に属さない。
これは @tabs 専用の子ノード構文であり、tabs-content の中にしか出現できない。
詳細は下記 "Widget-Specific Grammar: @tabs" を参照。
*)
metadata =
"@meta" , meta-content ;
(* meta-content は block-content と同じ方法でレキシングされる —— "[" / "]" のペアは
通常どおりトークン化されるため、未登録の "@word" は §6 Unknown Command
Fallback の規則に従って通常のテキストにフォールバックする —— しかし
Parser.ts はここで、他のどの block ノードよりも意味論的に厳格になる:
構造系のノードに限らず、@n や @raw すら含め、@meta 内部に現れる登録済み
ノードをすべて拒否する。その後 Parser は得られたテキストを改行で分割し、
各行の最初の "=" でキーと値に分割して、その構造化を後段のパスに任せる
のではなく、直接 AST ノード(MetaNode.meta)に格納する。完全な挙動と
具体例は Metadata.md §3/§6 を参照。 *)
meta-content =
"[" ,
{ text } ,
"]" ;
heading =
( "@heading" | "@h" ) ,
[ "(" , level , ")" ] ,
block-content ;
paragraph =
( "@paragraph" | "@p" ) , block-content ;
quote =
"@quote" , block-content ;
list =
"@list" ,
[ "(" , "ordered" , ")" ] ,
block-content ;
code =
"@code" ,
[ language ] ,
raw-block-content ;
image =
"@img" ,
"(" ,
image-option-list ,
")" ,
[ styles ] ,
block-content ;
hr =
"@hr" ;
svg =
"@svg" ,
raw-block-content ;
details =
"@details" ,
[ title ] ,
[ styles ] ,
block-content ;
card =
"@card" ,
[ title ] ,
[ styles ] ,
block-content ;
note =
"@note" ,
[ title ] ,
[ styles ] ,
block-content ;
tip =
"@tip" ,
[ title ] ,
[ styles ] ,
block-content ;
important =
"@important" ,
[ title ] ,
[ styles ] ,
block-content ;
warning =
"@warning" ,
[ title ] ,
[ styles ] ,
block-content ;
caution =
"@caution" ,
[ title ] ,
[ styles ] ,
block-content ;
mermaid =
"@mermaid" ,
raw-block-content ;
(* ==========================================================================
Structural-Specific Grammar: @img
@img の括弧の中身は単一の裸テキストではなく、カンマ区切りの
key=value オプションリスト(image-option-list)であり、拡張可能である。
最初のオプションで key が省略された場合、デフォルトで src とみなされる。
`image` 生成規則(上記参照)には ")" の後にもう一つ、独立した選択可能な
[styles] がある —— Image Style v1 であり、構文レベルでは image-option-list
とは完全に無関係(括弧の中には書けない)。意味論レベルの詳細は下記
「Image Style v1」小節を参照。
========================================================================== *)
image-option-list =
image-option ,
{ "," , image-option } ;
image-option =
src-option
| width-option
| height-option
| align-option
| bare-align-option
| radius-option
| border-option ;
src-option =
[ "src=" ] , url ;
width-option =
"width=" , integer ;
height-option =
"height=" , integer ;
align-option =
"align=" , align-value ;
align-value =
"left"
| "center"
| "right"
| "float-left"
| "float-right" ;
(* Because align-value is a closed set, a bare item that is exactly one of
its five values is also accepted as an align-option with no "align="
key (e.g. @img(src=a.png,float-left)[...]). This is checked BEFORE the
"first bare item is src" rule, so @img(float-left)[...] reads as align,
never as a URL that happens to spell "float-left". *)
bare-align-option =
align-value ;
radius-option =
"radius=" , text ;
border-option =
"border=" , text ;
url =
{ text-char - "," - ")" } ;
(* ==========================================================================
Widget-Specific Grammar: @table
@table は汎用の block-content を使わず、
専用の構造化構文(Columns + Rows)を持つ。
========================================================================== *)
table =
"@table" , table-content ;
table-content =
"[" ,
cols ,
data ,
"]" ;
cols =
"@cols" ,
"[" ,
column-list ,
"]" ;
(* Cell delimiter (v0.1.2): "|" if the row uses "|" anywhere at its own
top level, otherwise the legacy ",". Decided independently for @cols and
for each @data row. See §5 Table. *)
cell-delimiter =
"|" | "," ;
column-list =
[ "|" ] , cell , { cell-delimiter , cell } , [ "|" ] ;
data =
"@data" ,
"[" ,
{ row } ,
"]" ;
row =
"[" ,
[ "|" ] , row-cell , { cell-delimiter , row-cell } , [ "|" ] ,
"]" ;
(* A cell that is exactly one span-cell counts as n toward the row's width
instead of 1. A leading and/or trailing "|" is decoration and is
stripped, each edge independently. *)
row-cell =
span-cell
| cell ;
span-cell =
"@span" , "(" , integer , ")" , "[" , cell , "]" ;
(* cell は単純なプレーンテキストだけではない —— 厳選された inline-node の
サブセット(cell-inline-node)も許可されており、これは @cols のカラムと
@data のセルが共有する形と同じである。権威あるホワイトリストは、この
文法ではなく registry.ts の isCellAllowedNode() にある —— その集合に
含まれないノード(例:@card、@table、@details)は、Strict Mode
(Inline Syntax Specification §11)に従い、黙って捨てられるのではなく
MUST throw(必ず例外を投げる)でなければならない。 *)
cell =
{ cell-inline-node | any-unicode-char - cell-delimiter - "]" } ;
(* ==========================================================================
Widget-Specific Grammar: @tabs / @tab
@tab は @tabs の tabs-content の中にしか出現できない。
汎用の block-node 集合には属さないため、
document のトップレベルや他の block-content の中に
単独で出現することはできない。
========================================================================== *)
tabs =
"@tabs" , tabs-content ;
tabs-content =
"[" ,
{ tab } ,
"]" ;
tab =
"@tab" ,
"(" ,
text ,
")" ,
block-content ;4. 共有コンポーネント
block-content =
"[" ,
{ block-element } ,
"]" ;
block-element =
block-node
| inline-stream
| text ;
raw-block-content =
"[" ,
{ any-unicode-char } ,
"]" ;
title =
"(" ,
text ,
")" ;
language =
"(" ,
text ,
")" ;
level =
"1"
| "2"
| "3"
| "4"
| "5"
| "6" ;
text =
{ any-unicode-char } ;
integer、text-char等終結符定義沿用 Inline Spec 第 4 節 (完全な EBNF 文法定義)中のinteger與text-char産生式を そのまま踏襲しており、両文書は同じ文字集合の定義を共有しているため、 ここでは重複して掲載しない。
stylesも同様に Inline Spec 第 4 節のstyles生成規則 ("{" , { text-char - "}" } , "}")をそのまま踏襲しており、構文レベルでは 依然として「波括弧で囲まれた任意の文字列」としか定義していない。 Container Blocks(@details、@card)、Callout Blocks(@note、@tip、@important、@warning、@caution)と@imgは、いまではそれぞれの 生成規則の中に正式に組み込まれており(上記第 5〜7 節を参照)、もはや EBNF に明記されていない Parser 側の付随的な振る舞いではなくなっている。トークンの意味論は各ノード自身の規則であり、単一の共有テーブルではない。
@note/@tip/@important/@warning/@caution/@detailsは、 Inline Spec 第 7 節@mark スタイル意味論にある既存の color token 規則 (named token 対照表 + hex サポート)をそのまま踏襲する。一方@cardと@imgはそれぞれ独立した閉じた token 集合を持つ —— それぞれCard Style v1(下記第 6 節「Card Style v1」小節を参照)とImage Style v1(下記第 5 節「Image Style v1」小節を参照)であり、 同じ#RRGGBB/radius-Nという token の形は共有しつつも、意味論は それぞれ独立している(@cardの hex は背景色、@imgの hex は外枠の色)。 どちらも Inline Spec 第 7 節の named color 対照表は踏襲しない。 Container/Callout/@imgのstylesを実際に視覚スタイルへどう マッピングするか(あるいはするかどうか)は、各 Renderer が自由に決定する。認識できない token は指摘される(v0.1.2)。 そのノード自身の語彙に含まれない token——たとえば
@card{blue}(@cardは#RRGGBB/radius-Nのみを受け付け、名前付きカラーは受け付けない)や@mark{bluee}——は、これまで黙って捨てられ、ノードはスタイルなしのまま、どこにも通知がなかった。 Parser は現在、該当する token に対して diagnostic を報告する(Inline Spec 第 11 節 Diagnostics を参照)。 文書は従来どおりパース・レンダリングされ、その token は引き続き無視される。
5. 構造ブロック
見出し(Heading)
正典の構文は @heading であり、@h はそれと同等の簡略化されたエイリアス(Simplified Alias)である。両者は同じ AST ノードとしてパースされ、Renderer は作者が実際にどちらの書き方を入力したかを区別しない。
@heading(1)[
Introduction
]
@h(1)[
Introduction
]HTML(どちらの書き方でも出力は同じ):
<h1>Introduction</h1>段落(Paragraph)
正典の構文は @paragraph であり、@p はそれと同等の簡略化されたエイリアスである。
@paragraph[
Hello World
]
@p[
Hello World
]HTML(どちらの書き方でも出力は同じ):
<p>Hello World</p>引用(Quote)
@quote[
言葉は安い。
コードを見せろ。
]HTML:
<blockquote>
言葉は安い。
コードを見せろ。
</blockquote>リスト(List)
空でない行はすべて 1 つの項目である。行頭の - は任意の後方互換用の書き方であり、Parser が自動的に取り除く:
@list[
Apple
Banana
Orange
]これは以下と同等である:
@list[
- Apple
- Banana
- Orange
]各項目は AST の中で独立した list-item ノード(node.items)であり、その内容にはインラインノード(例えば @bold)を含めることができ、単なるプレーンテキストにとどまらない:
@list[
@bold[Apple] (本日特価)
Banana
]AST:
List
└── items
├── ListItem [ Bold("Apple"), " (本日特価)" ]
└── ListItem [ "Banana" ]順序付きリスト
@list(ordered)[...] はデフォルトの <ul> ではなく <ol> としてレンダリングされる。通常の @list と同様、行頭の - は任意であり必須ではない——プレーンテキストの行もそれだけで 1 項目とみなされる。追加で N. /N) と書けば番号を明示的に指定したことになり、Parser はその数値を該当 ListItem の marker フィールドに保存する。Renderer は ordered が真のときにのみ marker を <li value="N"> に変換し、「番号が飛んだ後に自動的に連番を続ける」処理はブラウザ標準の <ol> カウンターに任せる:
@list(ordered)[
- Apple
- Banana
3. Cherry
- Date
]レンダリング結果は 1. Apple、2. Banana、3. Cherry(明示的に指定)、4. Date(自動的に連番)となる。
ネストしたリスト
新しい構文の追加はない——@list の内容はもともと block-content であり、ネストした @list[...] はすでに正当な子ノードである。1 行を単独で占めるネストした @list[...](前後に空白しかない場合)は、Parser によって直前の item の内容に統合され、新しい item として別に作られることはない:
@list[
- Fruits
@list[
- Apple
- Banana
]
- Vegetables
]AST 上では、内側の @list ノードは Fruits という ListItem の content 配列の中に現れる。Renderer 側で追加のロジックは一切不要で、content を再帰的にレンダリングすれば自然にネストした <ul>/<ol> が生成される。
旧バージョンのドキュメントでは、
(modifier)の配列(例えば@list(bullet,number)[...])で階層ごとにリストの種類を宣言する案が触れられていたことがあるが、上記の@list(ordered)とネストした子リストがそれぞれ自分の種類を宣言するという設計が、実際に採用された、その案よりもシンプルな方式である。
コード(Code)
@code(ts)[
const x = 1;
]HTML:
<pre><code class="language-ts">
const x = 1;
</code></pre>画像(Image)
@img の括弧の中身はカンマ区切りの key=value オプションリスト(image-option-list)であり、拡張可能である。最初のオプションで key= が省略された場合、デフォルトで src とみなされる:
@img(
https://example.com/logo.png
)[
WEDC Logo
]これは以下と同等である:
@img(src=https://example.com/logo.png)[
WEDC Logo
]他のオプションと組み合わせて使う:
@img(
https://example.com/logo.png,width=200,align=center
)[
WEDC Logo
]現在サポートされているオプション:
| オプション | 説明 | 例 |
|---|---|---|
src(省略可) | 画像の取得元 URL | src=https://... |
width | 表示幅(単位は Renderer が決定) | width=200 |
height | 表示高さ(単位は Renderer が決定) | height=150 |
align | 配置方法 | align=left/center/right/float-left/float-right |
radius | 角丸(Renderer にそのまま渡す CSS 値) | radius=8px |
border | 外枠(Renderer にそのまま渡す CSS 値) | border=1px solid #ccc |
Image の align 値(v0.1.2)
align の値の集合は閉じている:
| 値 | 効果 |
|---|---|
left | 画像を左寄せ。後続の内容は画像の下に続く |
center | 画像を中央寄せ(従来の動作) |
right | 画像を右寄せ。後続の内容は画像の下に続く |
float-left | 画像を左寄せ。後続のテキストが右側に回り込む |
float-right | 画像を右寄せ。後続のテキストが左側に回り込む |
@img(./a.png,align=float-left)[代替テキスト]- キー省略形。 値の集合が閉じているため、カンマ区切りの項目がこの 5 つの値のどれか 1 つと完全に一致する場合は、
align=というキーがなくてもalignとして認識される:@img(./a.png,float-left)[...]は@img(./a.png,align=float-left)[...]と等価である。この判定は「最初のキーなし項目はsrc」という規則より前に行われるため、@img(float-left)[...](srcが一切ない)は、たまたま "float-left" と綴られた URL ではなく配置として読まれる。 - 組み合わせではなく単一のオプション値。
align=left,float=trueのような組み合わせは意図的に設けていない——無効な状態はそもそも書けず、作者(またはモデル)は 2 回ではなく 1 回の選択で済む。 center+ 回り込みはない。 中央寄せの画像の左右両側にテキストを回り込ませることは CSS のfloatでは表現できず、ほとんどの renderer も実装できない。残しておくと、各 renderer が黙ってそれぞれ異なる動作にフォールバックするだけになる。- 回り込みの終了位置。 回り込みは renderer レベルの慣例であり、AST には記録されない:次の見出し、次の
@hr、または囲んでいるコンテナの終端で終了すべき(SHOULD)である。 - 狭い画面や、フロー配置できない出力先(スマートフォン、terminal、一部の PDF):renderer は配置と回り込みを無視し、中央寄せまたは全幅で表示してもよい(MAY)。配置は位置の意味論であり、ピクセル単位のレイアウトを約束するものではない。
- 認識できない値(例:
align=middle、タイプミス):renderer はその値を無視してデフォルト(配置なし)を使う。Parser は加えて warning の diagnostic を報告する——文書は引き続きレンダリングされるので error ではないが、もう黙って無視されることはない。
Image Style v1
@img(...) の後ろには、任意で {styles}(構文定義は第 4 節を参照)を 続けて書くことができ、@card と同じ Card Style v1 の token の形 (#RRGGBB / radius-N)を共有する。ただし意味論は独立しており、 それ自体が閉じた token 集合を構成する——Inline Spec 第 7 節の named color 対照表は踏襲せず、image-option-list の一部でもない ((...) 括弧の中には書けない):
| Token の形 | 意味 | 例 |
|---|---|---|
#RRGGBB(16 進数 hex) | 外枠の色。1px の実線の外枠として適用される | @img(src=...){#3366ff}[...] → border: 1px solid #3366ff |
radius-N(N は非負整数) | 角丸。N はピクセル値 | @img(src=...){radius-12}[...] → border-radius: 12px |
@img(src=https://example.com/photo.jpg){#3366ff,radius-12}[
WEDC Photo
]{styles} を省略した場合は、純粋な裸の <img> となり、デフォルトの角丸や 外枠は一切付与されない——これは @card に通常 Renderer 独自の静的な デフォルト値があり、それを上書きできるのとは異なる。@img にとって {styles} は純粋な「任意」のオン・オフスイッチであり、「デフォルトの 上書き」ではない。
テーブル(Table)
@table の内部構造は @cols + @data という 2 つの専用子ノードで固定されており、順序は固定で、両方とも必須である:
@table[
@cols[id,name,price]
@data[
[1,朝食,60]
[2,昼食,80]
[3,晩餐,90]
]
]@cols[...]:区切り文字で区切られた列見出しのリストであり、列の順序と数を定義する。各列は@dataのセルと同じくcell(下記参照)であり、プレーンテキストの識別子に限定されない。@data[...]:各行は[...]の中に包まれ、その行の幅は@colsで定義された列数と等しくなければならない(MUST)(@span(n)のセルはn、それ以外のセルはそれぞれ 1 と数える)。幅が異なる行は diagnostic として報告される——下記「行の幅」を参照。
セルの区切り文字:| または ,(v0.1.2)
@cols と各 @data 行はもともと , のみでセルを区切っていたため、それ自体にカンマを含むセル($1,500、Web, iOS, Android、DECIMAL(10,2))を書く方法がなく、黙って余分な列が生まれていた。v0.1.2 からは、区切り文字は行ごとに、次の機械的な規則で決まる:
ある行の最外層に "|" が現れれば、その行は "|" で区切る。
そうでなければ、従来どおり "," で区切る。@table[
@cols[時間|講演|登壇者]
@data[
[09:00 - 10:30|開会講演|王小明]
[10:30 - 11:00|@span(2)[休憩]]
[11:00 - 12:00||データエンジニアリング分科会]
[13:30 - 15:00|テーブル構文の設計|陳大文, 林美華]
]
]|モードでは,は普通のテキスト——エスケープも制限も不要(上の最後の行の登壇者セルを参照)。,モードは変更なし。|を含まない行は従来とまったく同じようにパースされるため、既存の文書に移行作業は不要。カンマ形式は旧式とみなされ、Editor Mode の実装は非推奨として表示してもよい(MAY)。- 最外層の区切り文字だけが区切る。 ネストされたノード自身の角括弧内の
|や,(@bold[a,b]、@raw[a|b])はリテラルのまま——セルの分割は角括弧の深さに従い、registry は参照しない。セルにリテラルの|が必要な場合は@raw[...]で包む。|が必要になる内容はたいていコードであり、意味的にもそれが正しいノードである。 - 空のセルは書き出さなければならない。
[11:00 - 12:00||データエンジニアリング分科会]の中央のセルは意図的に空である。 - 先頭や末尾の余分な
|は装飾とみなされ除去される。両端は独立に判定される。[|a|b|c|](Markdown テーブルの習慣)、[|a|b|c]、[a|b|c|]、[a|b|c]はすべて同一にパースされる。代償として、端の|では「本当に空の最初/最後のセル」を表せなくなる——プレースホルダーを入れるか、列を組み替えること。行の途中の空セルは影響を受けない。 - セルを
<...>で包むのは避けること——その形は<action>スロット用に予約されている。
列をまたぐセル:@span(n)[...](v0.1.2)
[10:30 - 11:00|@span(2)[休憩]]内容がちょうど 1 つの @span(n)[...] ノード(n は正の整数)であるセルは n 列にまたがり、行の幅を数えるときに 1 ではなく n と数えられるため、「すべての行の幅が列数と等しい」という規則に例外はない。上の例のその行は実際のセルが 2 つで、幅は 1 + 2 = 3 となり、@cols の 3 列と一致する。Renderer はこれを自身の colspan の概念に対応させる(HTML:<td colspan="n">)。
@spanは@dataのセルの唯一の内容としてのみ有効である。@colsの中、テーブルの外、あるいはセル内の他の内容と混在している場合は、位置を誤ったノードとして、@tabsの外の@tabと同じ方法で指摘される。nは単純な正の整数でなければならない(MUST)。@span(two)、@span(0)、@span(2.5)はそれぞれ独自の diagnostic として報告される。行の幅の検査ではそのようなセルは幅 1 として数えられるため、同じ根本原因が二重に報告されることはない。@hexと@spanはセルの許可リストに入っている(色見本の表は@hexの最も一般的な用途であり、@spanはここでしか意味を持たない)。@spoilerは意図的にリストに含まれない——クリックして開示するスパンをテーブルのセルに置くのは不適切だからである。@span自体にはスタイルやレイアウト上の意味はない——第 1 節の注記を参照。
行の幅
行の幅(@span を含む)が @cols の列数と等しくない場合は、その行がどの区切り文字を使っているかにかかわらず diagnostic として報告される。Parser は自動的な補完や切り詰めを決して行わない:黙って不一致のままにすると、列が見出しとずれたテーブルが描画されてしまう。この diagnostic は Strict Mode では error、Editor Mode では報告されるがブロックしない diagnostic であり、問題のある行を指す。
各 cell は単純なプレーンテキストではない——テキスト本体に加えて、厳選された行内書式ノード(@bold、@italic、@underline、@del、@mark、@color、@sup、@sub、@link、@fn、@hex、@span、そして改行に変換される @n)が許可されている。これらのノードはテキストの見た目だけを変え、テーブル本来の「列とデータ行を揃える」という構造には影響しないためである。この一覧は Renderer 側(registry.ts の isCellAllowedNode)で管理されており、構文レベル自体はその内容を制限しないため、将来的に拡張可能である。一覧に無いノード(例えば @card、@table、@details のような、自分自身のレイアウト構造を持ち込むブロックノード)は、黙って捨てられるのではなく、MUST throw(必ず構文エラーを投げる)でなければならない——これは Strict Mode(Inline Syntax Specification 第 11 節)の「エラーを投げることを厭わず、誤った内容を飲み込まない」という精神と一致する。
@table[
@cols[id,name,note]
@data[
[1,@bold[Alice],See @link(https://example.com)[profile]@n more info]
]
]AST:
Table
├── Columns
│ ├── id
│ ├── name
│ └── price
└── Rows
├── Row [1, 朝食, 60]
├── Row [2, 昼食, 80]
└── Row [3, 晩餐, 90]あるいはインライン書式付きのセルの場合:
Table
├── Columns
│ ├── id
│ ├── name
│ └── note
└── Rows
└── Row [
"1",
[ Bold("Alice") ],
[ "See ", Link("https://example.com", "profile"), "\n", " more info" ]
]水平線(Horizontal Rule)
@hrHTML:
<hr>SVG
@svg は @code/@mermaid と同じく raw-block-content に属する——内容はそのまま保持され、Parser は解析も escape もしない:
@svg[
<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 10 10">
<circle cx="5" cy="5" r="4" />
</svg>
]6. コンテナブロック
@details/@card は現在、任意の {styles}(構文定義は第 4 節を参照)も 受け付けるようになっており、(title) の後、block-content の前に置かれる:
@card(API Key){#3366ff,radius-12}[
ここに説明の内容を書く。
]省略した場合は純粋な内容だけの形式のままとなり、どちらも正当である。 Renderer は認識できない token を無視してもよい(MAY)(Inline Spec §6 Unknown Command Fallback の精神と一致する)。@card の {styles} の token 意味論は、それ自体が独自の閉じた規則(Card Style v1)であり、 Inline Spec 第 7 節の named color token 対照表とは無関係である——下記 「Card Style v1」小節を参照。
詳細(Details)
@details(詳細情報を見る)[
内容
]HTML:
<details>
<summary>詳細情報を見る</summary>
内容
</details>カード(Card)
@card(API Key)[
ここに説明の内容を書く。
]Card Style v1
@card の {styles} が許すのは、少数の、クロスプラットフォームかつ価値の 高いスタイルだけであり、汎用的な CSS の逃げ道にはあえてしていない——現在 認識されるのは以下 2 種類の token の形のみで、それぞれ単独で使う、両方を 併用する(カンマ区切り、順序は問わない)、あるいは全体を省略する、のいずれ も可能である:
| Token の形 | 意味 | 例 |
|---|---|---|
#RRGGBB(16 進数 hex) | 背景色。その色値をそのまま採用する | @card{#3366ff}[...] → background-color: #3366ff |
radius-N(N は非負整数) | 角丸。N はピクセル値 | @card{radius-12}[...] → border-radius: 12px |
@card{#3366ff,radius-12}[
背景色と角丸を同時に設定する。
]上表に無い token(例えば named color の語、Inline Spec 第 7 節の color token)は一律に認識不能とみなされ、Renderer はエラーを投げるのではなく 無視しなければならない(MUST)(Inline Spec §6 Unknown Command Fallback の精神と一致する)。そのうえで Renderer 自身のデフォルトの見た目を維持 する。radius-N の N が純粋な数字でない場合(例えば radius-lg)も 同様に認識不能とみなされる。
7. コールアウトブロック
@note、@tip、@important、@warning、@caution はいずれも任意の (title)(定義は第 4 節を参照)と組み合わせることができ、本文とは独立した 見出しフィールドを内容に付加できる。また任意の {styles}(第 4 節、 および第 6 節 Container Blocks の同じ説明を参照)を (title) の後に置いて 組み合わせることもできる。両方を省略した場合は純粋な内容だけの形式のまま となり、いずれも正当である:
ノート(Note)
@note[
これは一般的な情報です。
]ヒント(Tip)
@tip[
これはベストプラクティスの提案です。
]重要(Important)
@important[
この内容を優先して読んでください。
]警告(Warning)
@warning[
削除すると元に戻せません。
]タイトルと組み合わせる:
@warning(データ保持ポリシー)[
削除すると元に戻せません。
]注意(Caution)
@caution[
この操作はデータ損失を引き起こす可能性があります。
]8. ウィジェットブロック
タブ(Tabs)
@tabs の内部には1 つ以上の @tab 子ノードしか含めることができず、他の block-node や裸のテキストは受け付けない:
@tabs[
@tab(JavaScript)[
...
]
@tab(Python)[
...
]
@tab(Rust)[
...
]
]@tab(タイトル)[内容]:タイトルはタブの表示名であり、内容は完全なblock-content(任意の block-node と inline-stream を含められる)である。- もし
@tabs[...]の中に@tab以外のノード(例えば裸のテキストや他の block-node)が現れた場合、Parser は MUST でこれを構文エラーとみなす(Strict Mode)か、Editor Mode によって自動的に無視 / 修正を提案する。 - 一意な id(v0.1.2)。 タブウィジェット用に DOM の id を出力する renderer は、それらを文書全体で一意にしなければならない(MUST)。各
@tabsブロックの中で panel に 0 から番号を振ると、1 つの文書内の 2 つの@tabsがどちらもtab-panel-0、tab-panel-1、…… を出力してしまい、トリガーのaria-controlsがただ 1 つの panel に解決されなくなる。参照実装は、文書ごとの widget カウンターを付与する(tab-panel-<widget>-<index>)。 - 初期状態。 参照実装は最初のタブを選択済みとして印を付ける(トリガーに
aria-selected="true"、panel にdata-active="true")。これにより、スクリプトが実行される前からウィジェットが正しい初期状態を持つ。
Mermaid
@mermaid[
graph TD
A --> B
]9. メタデータ
@meta[
title = @Doc
author = WEDC
description = AI Native Document Format
keywords = parser,ast,dsl
]Renderer は以下にマッピングできる:
- HTML Meta Tags
- OpenGraph
- PDF Metadata
- DOCX Properties
- Search Index
- RAG Metadata
10. コア原則
@Doc Block Syntax の目標は、新しい HTML を作ることではない。
そうではなく、次のような文書 AST を作ることである:
Human Editable Machine Deterministic AI Friendly Cross Platform
HTML は Renderer である。
Markdown は Renderer である。
React は Renderer である。
そして @Doc は:
Source of Truth.
11. 簡易構文エイリアス
一部の高頻度で使われる命令には、簡略化されたエイリアス(Simplified Alias)が追加で用意されている——これは純粋に入力時の省略表記であり、Parser はそれを正典の名前に正規化してから AST ノードを作成する(node.type は常に正典の名前になる)。Renderer は作者が実際にどちらの書き方を入力したかを区別する必要がなく、実際に区別することもない。
Block Syntax がカバーするエイリアス:
| Canonical | Alias |
|---|---|
@heading | @h |
@paragraph | @p |
(Inline Syntax の @bold/@italic/@underline のエイリアス @b/@i/@u は Inline Syntax Specification で定義されている。)
@Doc