quarto-plus — 統合（多形式をひとつに）

.md / .qmd / .adoc で書かれたドキュメントを単一の静的サイトへ統合・正規化する Quarto ベースのパイプラインツールの解説

概要

quarto-plus は、.md / .qmd / .adoc で書かれたドキュメントを 単一の静的サイト へ統合し、検証済みの HTML として公開する Quarto ベースのパイプラインツールです。「＋（プラス）」の由来は、書き手には得意なフォーマットを、読み手にはひとつのサイトを、つまりバラバラに書かれた文書を「＋」して同じルールのひとつの場所に合流させることです。

  • リポジトリ: https://github.com/watanabe3tipapa/quarto-plus
  • 公開サイト: https://watanabe3tipapa.github.io/quarto-plus/
  • ライセンス: MIT（v0.3.0・調整中）
Note

注意: quarto-plus は現在「調整中」の開発途上プロジェクトです。インターフェースや出力が将来変更される可能性があります。

役割

「Quarto を自由に書いて、ひとつの場所にまとめる」ことを担当します。フォーマットを競合させず、書き手の選択を尊重したまま、公開後の構造を統一します。

営み quarto-plus の対応物
好きなフォーマットで書く .md / .qmd / .adoc のいずれでも執筆
バラバラの見出しを揃える harmonize が pagePrefix-<slug> の一意な ID に正規化（日本語はかな→ローマ字）
ページに目次を持たせる h2..h6 から入れ子構造の #toc を自動生成
画像をまとめる asset-sync が assets/<sha>-<basename> に集約し、参照を自動書換
リンク切れを防ぐ validate が同一ページ・クロスページのアンカーとファイルを検証
最初の一歩を早める 34 種の実用雛形（.qmd 15 / .md 14 / .adoc 5）を同梱
公開する GitHub Actions による GitHub Pages への自動デプロイ

特徴

  • 多形式統合: quarto render + asciidoctor を merge → harmonize → asset-sync → validate → validate-doc-types のパイプラインで処理
  • ドキュメント向けリンター: ESLint がコードを見るように、文書サイトを検証
    • validate: フラグメント解決・画像/CSS/JS の存在・重複 ID の検出
    • validate-doc-types: tools/doc-types.json の必須見出しを満たすか型検証
  • search.json 再生成: harmonize 後に再生成し、サイト内検索のリンク切れを防止

使い方

git clone https://github.com/watanabe3tipapa/quarto-plus.git
cd quarto-plus
npm install
npm run build:all          # dist/ に検証済みサイトを出力
adoc → html ─┐
              ├→ merge → harmonize → asset-sync → validate → validate-doc-types → dist/
quarto render ┘

前提: Quarto >= 1.3、Node.js >= 20、Asciidoctor >= 2.0（.adoc を使う場合のみ）。

長所

  • 書き手の自由: 文書の性質に合わせて .md / .qmd / .adoc を選択でき、統合はツールが担う
  • 一貫した出力: 見出し ID・目次・画像参照・リンクが同じルールに正規化される
  • 検証内蔵: リンク切れ・重複 ID・必須見出しの欠落をビルド時に検出
  • 豊富な雛形: 34 種のテンプレートで手順書・議事録・API 仕様などをすぐ書き始められる
  • 検索まで正規化: search.json を再生成し、検索結果のリンク切れを防止

短所・制約

  • 開発途上（調整中）: v0.3.0 時点では仕様が固まっておらず、変更の可能性がある
  • 依存が多い: Quarto + Node.js + Asciidoctor の準備が必要（.adoc を使わない場合も構成を理解する必要がある）
  • パイプライン学習コスト: harmonize / asset-sync / validate などの概念を把握する必要がある
  • テンプレートは雛形: 内容は自分で書く必要があり、生成の自動化（LLM 連携）は持たない（そこは quarto-dsh の担当）

適用例

  • 手順書（.qmd）・議事録（.md）・API 仕様（.adoc）を混在させた社内ドキュメントサイト
  • 複数リポジトリの文書を単一サイトに集約したいとき
  • リンク切れ・壊れた参照をビルド時に防ぎたいとき

関連