@DocREADME
@Doc — AIネイティブ・セマンティック文書記法
⚠️ この文書は AI による翻訳です。誤りが含まれる可能性があります。 正確な内容を確認したい場合は、繁體中文版 または English 版 をご参照ください。
どの時代の文書フォーマットも、その時代の最も本質的な課題を解決してきた。
| フォーマット | 解決した課題 |
|---|---|
| Word | 文書編集 |
| HTML | 文書表示 |
| Markdown | 人間にとって書きやすいこと |
| JSON | データ交換 |
| JSX | コンポーネント合成 |
| @Doc | AI と人間が共同で執筆するためのセマンティック文書表現 |
しかし、AI が生成するコンテンツのために設計されたフォーマットは一つもなかった。
@Doc は 3 種類の読者のために設計されている：
- コンテンツを執筆する人間
- コンテンツを生成する AI
- それをレンダリングするコンパイラ
@Doc は「次の Markdown」ではない。 それは、LLM が生成するコンテンツとレンダラーの間に欠けていた notation（記法）レイヤーである。
既存の主流フォーマットは通常、このうち一つか二つしか最適化できておらず、三つすべてを第一級の設計目標として同時に扱っているものは少ない：
| 特性 | Markdown | HTML | MDX | @Doc |
|---|---|---|---|---|
| AI 生成の安定性 | ❌ | ⚠️ | ❌ | ✅ |
| トークン効率 | ✅ | ❌ | ❌ | ✅ |
| セマンティックな検索可能性 | ❌ | ⚠️ | ⚠️ | ✅ |
| マルチターゲット・コンパイル | ❌ | ❌ | ⚠️ | ✅ |
既存の選択肢が抱える根本的な問題
Markdown — 人間の執筆のために設計され、機械生成のためではない
LLM が Markdown を読むこと自体は問題ない。問題はその逆だ。LLM に Markdown を生成させ、それを下流のプログラムに解析させようとすると、出力される構造の信頼性はほとんど保証できない——インデントの曖昧さ、ネストしたリストのずれ、テーブルの崩壊、パーサーごとの方言の違い。
Markdown には意味的な意図がない。「このボタンは primary variant である」や「このテーブルには縞模様が必要」といったことを表現できない。
HTML — 構造と表現が一体化してしまっている
HTML はどんなものでも表現できるが、その代償として表現ロジックが構造にハードコードされてしまう。同じコンテンツを別のプラットフォームでレンダリングしたい？書き直しが必要だ。AI に安定した HTML を生成させたい？幻覚タグや閉じられていない要素のリスクに直面する。HTML はレンダーターゲットであって、notation（記法）ではない。
MDX — 人間の開発者のために設計され、その代償を AI が払う
MDX は文書とコードを融合させ、人間の開発者に非常に高い表現力を与える。しかし、この自由度は生成モデルにとって別の意味を持つ——より高い構文の不安定性と、より脆い構造的予測可能性である。
| 比較軸 | MDX | @Doc |
|---|---|---|
| 本質的な位置づけ | 文書をプログラムにする（Code-driven） | 文書をセマンティックデータにする（Data-driven） |
| AI 生成の安定性 | 任意の JS ロジックを許すため LLM は構文を崩しやすい | 決定的な文法であり LLM の出力は予測可能 |
| 括弧の意味論 | {} [] <> の意味が多重に混同する | [] のグローバルな意味は常に Content（内容） ただ一つ |
| トークンコスト | 冗長なタグの閉じ処理と JS のボイラープレート | 文法が極度に圧縮されている（w-[300px] ではなく w-300px、計画中——下記「コア構文」節の但し書きを参照） |
| エラー処理 | レンダー時にクラッシュし、1 文字の誤りで画面が真っ白になる | パース時に捕捉され、AI は数秒で自己修正できる |
@Doc とは何か
同じ @Doc ソースコードは、一文字も変更することなく、Tailwind JIT HTML、Inline Style HTML、あるいは将来のどんなレンダーターゲットにもクリーンにコンパイルできる。
構造と表現は徹底的に分離されている。意味論はフォーマット自体が担い、レンダラーが決めるものではない。
コア構文
すべてのノードの長期的な目標形は、同じ 4 スロット構造である：
@node(modifier){styles}[content]<action>| スロット | 役割 | 例 |
|---|---|---|
@node | ノード種別 | @heading（別名 @h）・@paragraph（別名 @p）・@card |
(modifier) | バリアントまたは属性 | (primary)・(ja) |
{styles} | スタイルまたはメタデータ | {w-300px bg-fff} |
[content] | コンテンツスロット ── グローバルに唯一 | [Submit] |
<action> | 末尾のアクション | <submit>・<install> |
[] は @Doc において常にただ一つの意味を持つ：内容（コンテンツ）。例外はなく、エスケープ地獄もない。
構文例
@meta[
title = @Doc 2026 Spec
description = AI-native semantic document runtime
]
@heading(1)[@Doc プロジェクト仕様]
@paragraph[これは通常の段落で、インライン・セマンティックノードを含んでいる。]
@card(featured)[
@heading[AI ネイティブな言語]
@paragraph[決定的な文法を持つ構造化マークアップ言語。双方向 AST のために設計されている]
]
@table[
@cols[id,name,price]
@data[
[1,朝食,60]
[2,昼食,80]
[3,晩餐,90]
]
]デュアルルート・コンパイル
同じ AST から 2 種類の出力を生成できる。ソースコードは一文字も変更しない：
Route A — Tailwind JIT
<h1 class="text-lg w-[120px]">@Doc プロジェクト仕様</h1>Route B — Universal Inline Style
<h1 class="text-lg" style="width: 120px;">@Doc プロジェクト仕様</h1>動的な値は AST の中で構造化データ（{ prop: "w", value: "120px" }）として保持され、生の文字列としては保持されない。実際にどうレンダリングするかはバックエンドのアダプターが決定する。
ノードの分類
Core Nodes — 構造プリミティブ
文書の骨格であり、これ以上分割できない原子である。
@heading（別名 @h） @paragraph（別名 @p） @quote @code @list @img @table
Semantic Nodes — セマンティックコンテナ
2 つの振る舞いモードを持つ：
- Inline Semantic — タグ付きのインライン要素としてレンダリングされる：
@mark[重要]、@link(example.com)[リンク] - Block Metadata — ホストの設定に注入されるだけで、HTML はまったくレンダリングされない：
@meta[key = value]
AI 開発者へ
LLM に直接 HTML を生成させるのは脆い。@Doc はモデルに制約された決定的な文法を提供する——エラーはレンダー時ではなく、パース時に露見する。
[] だけが内容の意味を持つ唯一の括弧であるため、モデルは括弧の衝突を推論する必要がない。
トークンコストも低い：Tailwind の任意値構文 w-[300px] の代わりに w-300px を使う——括弧はコンパイラが補うものであり、モデルが生成する必要はない（計画中。現時点で {styles} がサポートするのは色トークンのみ。上記「コア構文」節の但し書きを参照）。
Web 開発者へ
import { tokenize } from './Lexer';
import { DocParser } from './Parser';
import { DocTranspiler } from './Adapters';
const tokens = tokenize(source);
const ast = new DocParser(tokens).parse();
const html = ast.map(node => DocTranspiler.toTailwindHTML(node)).join('\n');@Doc のソースコードを入力すると、構造化された AST が出力される。あとは自分の技術スタックに合ったアダプターでレンダリングすればよい。Parser と Adapters はそのままパイプラインに組み込め、余計な依存関係もない。
設計上の境界線
@Doc は意図的にプログラミング言語ではない。これは制約ではなく、武器である。
- 変数がない
- 条件分岐がない
- ループがない
- マクロシステムがない
ロジックはホストアプリケーションの責務である。@Doc が担うのは構造だけであり、振る舞いは担わない。この境界線があるからこそ、AI が生成する出力は常に予測可能であり続ける。この境界線は意図的に引かれたものであり、動かされることはない。
現状
コアの Parser、Lexer、およびデュアルルートのアダプターは基本的な動作が可能な段階にある。Web ネイティブ版の Lexer と Parser は集中的な開発の真っ最中である。インタラクティブな Playground と CLI ツールは近い将来の開発ロードマップに載っている。
@Doc は、LLM の出力とレンダーターゲットの間にある設計空間を探るために存在している。コア機能はすでに動作しており、残りの部分は公開の場で継続的に構築されている。
目標：2027 年 1 月 1 日に 1.0 Production 版を正式リリース。
このリポジトリに含まれるもの
src/ Lexer、Parser、registry（ノードの単一の情報源）、Adapters（HTML レンダリングの2つのルート）
src/editor/ Monaco系エディタ向けのMonarch tokenizer
tests/ Lexer/ParserのStrict Modeテストケース群、および各ノードのレンダリング検証
configs/ editor/tooling用のノード設定
*-Specification.md この言語の権威ある文法定義（EBNF + セマンティックルール）Block-Syntax-Specification.md と Inline-Syntax-Specification.md が文法の権威ある情報源である。コードコメントの中では、Structural-Blocks.md や Container-Blocks.md のようなノード単位の補足説明ドキュメントが時折参照されているが、これらは v0.1 のリリース範囲には含まれていない——対応する内容はすべて上記 2 つの仕様書の中に含まれている。
License
MIT — see LICENSE.