なぜ .qmd は知識バンドルのソースに強いのか

前回の記事で取り上げた okf-seedling は、「エージェントにも人間にも読める .qmd」を知識バンドルのソースにします。ここでは、Quarto（.qmd）と Open Knowledge Format（OKF）がなぜ相性が良いのかを整理します。

OKF の知識バンドルの要求

OKF バンドル（index.md / log.md / concepts/*.md）に求められるのは、おおよそ次の性質です。

要求	意味
構造化メタデータ	type・対象・作成日などを機械が解釈できる
1 ファイル 1 概念	API / Playbook / Metric などを単位で管理
人間可読性	人が読んで理解できること
機械可読性	エージェントやツールが処理できること
更新の追跡	差分を sha 等で検知できること

親和性①：frontmatter がそのままメタデータ辞書

.qmd の先頭にある YAML frontmatter は、そのまま「機械用の辞書」になります。

---
type: metric
name: revenue
fiscal_year: 2026
created: 2026-08-11
---

# Revenue

Quarto は標準で frontmatter をパースし、ページのタイトル・日付・メタ情報として解釈
生成ツール（stamp-okf.mjs 等）は frontmatter をそのまま抽出・保持できる
_metadata.yml を使えば、ディレクトリ単位で共通メタデータを継承できる

つまり 「Quarto の解釈に使うメタデータ」と「バンドルのメタデータ」を別々に持たずに済みます。

親和性②：単一ソースから複数系統を出力

Quarto の強みは「1 つの .qmd から複数の出力」を作れることです。

concepts/api-overview.qmd（source of truth）
 ├─ HTML   （人間用サイト）
 ├─ PDF / Word（必要なら）
 └─ .md    （機械用 OKF バンドル）

okf-seedling は post-render に node tools/stamp-okf.mjs を挟み、レンダリング後に okf/ バンドルを自動生成しています。コンテンツを二重管理せずに、人間用と機械用を同時更新できるのがポイントです。

親和性③：パイプライン化しやすい

コマンドライン操作とテンプレート機構が揃っているため、CI に組み込みやすい構成です。

quarto render … 1 コマンドで全出力
post-render … レンダリング後の後処理フック（バンドル生成・検証の差し込み先）
quarto use template … バンドル雛形の生成を 1 コマンド化
quarto check … 環境診断

「雛形生成 → 執筆 → render → 検証 → 公開」までの流れを、GitHub Actions や Cloudflare Pages のビルドステップにそのまま乗せられます。

親和性④：コード実行が「検証可能な知」に直結

Quarto は Python（Jupyter / marimo）や R のコードを .qmd 内で実行できます。

Attested Computation（検証可能な計算定義）は、ソースに実行可能コードを持てる
Metric の値が古くならないかは、計算を再実行して sha の変化で検知できる
実行結果の数値や表を、人向け記事と機械向け定義で共有できる

「定義と計算が同じファイルにある」ことは、エージェントが知識の裏付けを辿るのに有利です。

まとめ

性質	OKF の要求	Quarto（.qmd）
メタデータ	構造化されている	YAML frontmatter
1 ファイル 1 概念	概念単位	ファイル = 概念
人間可読	必要	Markdown そのもの
機械可読	必要	`.md` 出力 + frontmatter
更新追跡	必要	`log.md` + sha（生成物）
再現性	望ましい	コード実行 + 実行結果埋め込み

「人が読む記事」と「機械が読む知識」を同じソースから保ち続けるという点で、Quarto の .qmd は OKF のソースとして自然な選択肢です。単なるドキュメントツールとしてではなく、知識の入り口として Quarto を置くという発想が、この CMS と okf-seedling に共通しています。