アーキテクチャ#

Copy as MarkdownView Markdown

Ox Content は、Rust 製のドキュメントシステムと Markdown ツールキットです。 コアエンジンは小さく、Markdown を arena 割り当てされた AST にパースし、それから描画または 直列化します。リポジトリの残りは、そのエンジンを Vite、Node.js、 WebAssembly、生成 API ドキュメント、検索、OG 画像、i18n、エディタツール向けにパッケージしています。

このページは地図です。大きな境界が見えるよう、API リファレンスの詳細と 性能結果は意図的に避けています。

いまの形#

Ox Content には 3 つの層があります。

1. コア Markdown エンジン: 割り当て、AST ノード、パース、描画向けの Rust crate。
2. プロダクト機能: SSG、検索、生成 API ドキュメント、埋め込み、OG 画像、i18n チェック、 エディタプレビュー向けの Rust と TypeScript モジュール。
3. 配布面: npm パッケージ、N-API バインディング、WebAssembly、Vite プラグイン、フレームワーク連携、エディタアダプター。

大事な区別は、パーサーがプロダクト全体ではないことです。パーサーは、docs サイト、 パッケージ API、執筆ツール、チェックが使ういちばん下の層です。

入口#

ほとんどのドキュメントプロジェクトでは、Vite プラグインから始めてください。必要なネイティブパッケージは すでに依存しているので、@ox-content/napi を直接入れるのは、独自の Node.js ツールを作るときだけが普通です。

Markdown エンジン#

コアの Markdown 経路は意図して狭いです。

主な性質:

• 各パース操作は Allocator を所有し、通常は入力長からサイズを決めます。
• AST ノードはソーステキストと arena から借用するので、パースは速く、 不要な文字列コピーを避けます。
• 描画は、Node.js、WebAssembly、ブラウザへ渡る前に、HTML、JSON データ、JavaScript モジュール コードのような所有出力を作ります。
• パーサーオプションは GFM、脚注、表、タスクリスト、取り消し線、 自動リンク、入れ子上限を制御します。
• レンダラーオプションは、.md リンク変換、ベース URL、行注釈、 コードブロックメタデータ、TOC の深さといったドキュメントサイトの振る舞いを足します。

Vite と SSG パイプライン#

Vite プラグインが主なプロダクト面です。開発中は Markdown 風ファイルを import 可能なモジュールにし、 ビルド中は静的 HTML にします。

開発中、Markdown の import はモジュールへ変換され、変更ファイル向けに HMR が ox-content:update イベントを送ります。ビルド中、SSG ステップは Markdown ファイルを集め、ルートを解決し、ナビを組み立て、HTML ページを生成し、 検索インデックスを書き、任意でページごとの OG 画像を生成します。

docs ジェネレーターは同じビルドグラフの一部です。TypeScript/JSDoc メタデータを抽出し、サイトビルドが消費する前に、設定した docs 出力ディレクトリへ Markdown ファイルを書きます。

Rust crate#

crate はひとつの Cargo ワークスペースから公開されます。内部依存は ワークスペースバージョンとローカルパスを使うので、個別 crate を公開しつつ、 リポジトリをひとつのシステムとして開発できます。

JavaScript パッケージ#

フレームワークパッケージはベースプラグインを置き換えず、包みます。そのため Markdown パース、SSG、検索、生成ドキュメント、テーマの振る舞いは @ox-content/vite-plugin に集中したままです。

執筆ツール#

エディタ連携は、統合言語サーバーを中心に組み立てています。

LSP はサイトパイプラインと同じパーサーとレンダラーの概念を共有しますが、 出力は執筆向けに最適化されています。診断、スニペット、補完、 定義ジャンプ、ホバー、インレイヒント、プレビュー HTML です。 対応するチェッカー / LSP 機能と既知のギャップは チェッカーと言語サーバー にあります。

境界と不変条件#

• パースの正しさは Rust が所有します。 JavaScript のオーケストレーションは、 Markdown の振る舞いを再実装せず、N-API または WASM を呼ぶべきです。
• 連携の形は TypeScript が所有します。 Vite プラグイン、仮想モジュール、 フレームワークアダプター、dev サーバーの振る舞いは npm パッケージにあります。
• 生成サイト機能はビルド時が先です。 検索、GitHub カード、Open Graph カード、ソースドキュメント、OG 画像は、可能なところでは静的に生成します。
• エディタ機能は同じドメインモデルを再利用します。 診断とプレビューは パーサー、レンダラー、frontmatter、MDC、i18n crate と揃ったままであるべきです。
• ランタイムをまたぐデータは所有されます。 借用された AST データは Rust 内に留まります。 JSON、HTML、またはモジュールコードがランタイム境界を越えます。

次に読む#

• はじめる は適切な入口を選びます。
• @ox-content/vite-plugin は サイトと transform API を文書化しています。
• パフォーマンス にはベンチマーク結果と再現 コマンドがあります。
• @ox-content/napi は Node.js API を文書化しています。
• @ox-content/wasm はブラウザと WebAssembly の使い方を扱います。
• 開発環境のセットアップ はローカルビルド、 コントリビューター向けコマンド、テストワークフローを説明します。
• Panic 防止 は入力起因 panic の #774 証拠台帳です。