三者の分業
このツールキットで組むドキュメント/wiki サイトは三つの部品から組み上がり、それぞれがちょうど一つの層を持ちます。部品の間の境界線は好みで引かれたものではありません——どれも、踏み越えたときに牙を剥く制約に裏打ちされています。
§1三つの層、三人の持ち主
- astro-inkbrush(エンジン):最小限の CMS——ブラウザ内でのその場ブロック編集、ブロック単位の履歴と巻き戻し、コメント、AI への質問・書き換え・翻訳、インボックス取り込み。そしてもう一つ、CMS には属さなそうに見えるものを持ちます:Markdown 方言とコンテンツガードです。理由は固いものです。エディタが受理する文法とページが描画する文法は同一でなければならず、そうでなければ「エディタでは保存できたのに、ページでは崩れて描画される」のは時間の問題だからです。だからパーサ規則はエンジンの中に一度だけ書かれ、三つの場所——サイトの描画、CMS の保存時検証、CI のチェック——で消費されます。
- astro-inkstone(紙面——このパッケージ):共有の外観・パイプライン層——二つの文脈にまたがる二層のデザイントークン、本文スタイルシート
base.cssとブラウズの書架browse.css、コンポーネントライブラリ、siteMarkdownパイプラインプリセット、この庭が回っている分類・バックリンクのヘルパー、Maple Mono CN のコードフォントサブセット、そしてレンダリング層のプローブ。サイトのアイデンティティには手を出しません:ブランドカラー、レイアウトのクローム、ルーティングとデプロイは、このパッケージの管轄外です。 - サイト(いま読んでいるこの庭のような):第一層トークンを上書きして自分のアイデンティティカラーを出し、Sidebar とナビのクロームを自前で持ち(このサイトの実装が模範解答です)、コンテンツの編成、ルートの形、デプロイ先を決めます。
覚える一行はひとつ:編集はエンジン、見た目は紙、サイトはあなた。
§2境界線がここにある理由
どの切れ目も、現実の制約に裏打ちされています:
方言はエンジンのもの。プラグイン構成がサイトと食い違うチェッカーは、チェッカーが無いより悪いからです——数式プラグインを欠いたチェッカーは数式の波括弧を JSX 式と読み違え、GFM を欠いたものはテーブルのパイプを素通しします。文法は一度だけ書かれ、三つの場所で消費される——だから漂流のしようがありません。
スタイルは紙のもの。複数のサイトがそれぞれ自前の本文スタイルシートを抱えると、コントラストの修正一つをサイトの数だけ適用することになるからです——一つ取りこぼせば、そのサイトの小さいテキストが AA を割ります。共有レイヤーなら、修正一つが全サイトに届きます。
アイデンティティはサイトのもの。共有レイヤーがどこか一つのサイトのブランドカラーを呑み込んだ瞬間、他のすべてのサイトが上書きでそれと戦う羽目になるからです。二層トークンはそのためにあります:サイトは第一層の生パレット(--p-*)を上書きし、意味層とコンポーネント層は手つかずのままついてきます——二層パレットを参照。
§3ブラウズの仕組みの置き場所
いままさに辿っているこのナビゲーションにも、同じ規律が働いています。パッケージが同梱するのはメカニクス——createTaxonomy(種類/分野/タグの解決、ハブ継承、ロケールミラー)、createBacklinks(バックリンクの索引)、そしてランディングページのノートカードや分類の行のような表示コンポーネントです。サイトが持つのは語彙とルート:この庭の種類と分野はサイト自身のレジストリファイルにあり、/kind/…、/domain/…、/tag/… のページは、消費するサイトがコピーして作り替える普通の Astro ページです。同じ分業が一段上でも:メカニクスはパッケージに、意味はサイトに。
§4サイトが得るもの
サイトの視点では、このパッケージとエンジンを合わせて導入すると、こうなります:
astro-inkstone/styles/tokens.css+base.css+browse.css:トークン、読書カラム、書架の順——@import三行で外観の全部。siteMarkdown(...):Markdown パイプライン全体が一行。スイッチの説明は はじめに。astro-inkstone/components/以下のコンポーネント。必要な分だけパスで import。astro-inkstone/lib/の分類ファクトリとバックリンクビルダー。サイト自身のレジストリに結びつけて使う。- WIKI モードでは、エンジンのフル CMS(このサイトなら
npm run wikiで試せます)。 - 五つのチェック:
check-content、check-wikilinks、check-dist(エンジン同梱)と、ui_probe、contrast_probe(当パッケージ同梱)——各種チェックを参照。
この庭のすべてのページの、すべての描画効果が、この分業の産物です——ノートがそのままマニュアル、マニュアルがそのままデモ。