sorane は OKF（Open Knowledge Format）ネイティブの静的サイトジェネレータです。Markdown を書くだけで、人間向け HTML と（必要なら）エージェント向けの機械可読出力を同じビルドから得られます。

プリセット（軽量 vs フル OKF）#

preset: blog        # 軽量 SSG（既定に近い）
preset: okf-site    # ssg.sorane.dev 相当のフル出力
preset: gov         # 行政向け + 厳格 validate
出力blog / 既定okf-site
HTML + feed / sitemap / robotsonon
各ページ .md / catalog.jsonld / llms.txt / okf/bundleoffon
図表・ブログ archive/tagoffon

詳細は 設定（YAML）。

OKF と機械可読出力#

preset: okf-site（または build.outputs）で有効になる主な成果物:

出力用途
HTML + .md 代替人間の閲覧とエージェントのテキスト取得
catalog.jsonldサイト全体の構造化カタログ（schema.org）
llms.txtLLM / エージェント向けサイト要約とリンク
okf/bundle.tar.gzOKF プロファイル準拠のコンテンツバンドル
sitemap.xml / robots.txt / feed.xml検索エンジン・購読

OKF プロファイルで article / index に加え dataset・reference・glossary・glossary-term・faq などを検証・出力できます（OKF プロファイル）。

エージェントと Git ワークフロー#

  • 管理画面なし — content/ と sorane.yaml を Git で編集
  • sorane validate --json — 構造化レポート（OKF エラー + 品質 warning）
  • template/site/ に AGENTS.md と CI テンプレート付属

AI アシスタント向けの手順は AI 向け解説。

公的サイト・発見性（Findability）#

組織サイトや政府系サイト向けに、検索・エージェント・構造化データをまとめて強化できます。

  • 発行主体 — site.organization / contact → JSON-LD・llms.txt
  • パンくず・サイト内検索 — BreadcrumbList、SearchAction（search.html?q=）
  • 記事メタ — identifier / subject / audience / coverage / updated
  • 多言語 — site.i18n、ロケール別 content/、hreflang / og:locale:alternate
  • 運用 — 全ページ緊急バナー（site.emergency）、記事の改訂履歴（revisions）
  • 品質ゲート — 画像 alt、リンク文言、表ヘッダー、日付、改訂履歴の validate warning

設定の詳細は 設定（YAML）。

検索#

  • FTS（標準） — SQLite ベースのキーワード検索。モデル不要

  • ハイブリッド（experimental） — 埋め込み + FTS。大規模サイトは ONNX を CDN 配信可能

  • ヘッダー検索 — sorane index 後、全ページにコンパクトな検索ボックス

  • 専用ページ — content/search.md（view: search）で種別 facet・説明文・SearchAction 用 URL

小さなサイトは専用ページを省略可能。open-data / 行政向けでは残すのが一般的です（設定）。

index / search コマンドは @sorane/search を別途インストールします（CLI）。

図表#

既定は off（preset: okf-site で on）。Mermaid client 利用時は mermaid パッケージが必要です。

ソースは常に Markdown のコードフェンスに残り、HTML はプレゼンテーション層です。

  • Mermaid — クライアント描画（既定）またはビルド時 SVG（mmdc）
  • D2 — ビルド時 SVG（d2 CLI）
  • Graphviz — ビルド時 SVG（dot）

図表 を参照。

AI コンテンツ開示#

profile: sorane-okf/0.2 または 0.3 で、EU 系の開示要件に沿ったメタデータを扱えます。

  • 記事 frontmatter → HTML バッジ + digitalSourceType（JSON-LD / 検索 / カタログ）
  • 静的画像 — IPTC XMP 埋め込み、C2PA 署名（opt-in）
  • associatedMedia でインライン画像と開示情報を JSON-LD に連携

AI 開示。

フォント・表示#

  • ページ単位の WOFF2 サブセット埋め込み（@sorane/font）
  • スキップリンク、セマンティック HTML、カスタム 404.md
  • ブログ一覧・アーカイブ・タグ（任意）

ホスティング連携#

Cloudflare Pages 向けに、HTML にトラッキングを埋め込まず運用メタを出力できます。

  • dist/ops/cloudflare.json — Pages プロジェクト・ゾーン・解析の目印
  • 任意で Logpush → R2（監査用アクセスログ）

デプロイ。

次のステップ#