quarto-pe — 知る（知識・リファレンス）

公式仕様に基づく実在キーだけを体系化した Quarto チートシート兼リファレンスサイトの解説

概要

quarto-pe は、Quarto の設定ファイル _quarto.yml 記法 と本文の Q markdown 構文 を、ひとつの場所にまとめたチートシート兼リファレンスサイトです。「pe」は Personal Edition（個人備忘録） の意味で、ネット上に散在する不正確な情報を渡り歩く代わりに、公式仕様に基づく実在キー・実コマンドだけ を精査して体系化することを方針としています。

  • リポジトリ: https://github.com/watanabe3tipapa/quarto-pe
  • 公開サイト: https://watanabe3tipapa.github.io/quarto-pe/
  • ライセンス: MIT（v0.4.0）

役割

「Quarto を正しく使うための知識」を提供します。設定キーが実在するか・コマンドが実在するか・記法が正しいか、という問いに、手元の Quarto 1.3+ で実際に検証した上で答えます。

営み quarto-pe の対応物
設定キーを調べる _quarto.yml 記法リファレンス（project / format / website / book / execute / vars を体系化）
本文の書き方を学ぶ Q markdown 記法（見出し・Div・Callout・相互参照・数式・変数）
最初の設定を用意する 設定テンプレート集（15 セクション）をコピペ
動的コンテンツを試す R チャンク・パラメータ・Observable JS の実動サンプル
構造化・多形式を仕上げる 相互参照・Callout・レイアウト・文献管理の適用例
公開する GitHub Actions による GitHub Pages 自動デプロイ

特徴

  • 体系化されたリファレンス: _quarto.yml の全キーをカテゴリ別に整理
  • Q markdown 記法: 見出し・Div・Callout・相互参照・数式・変数・shortcode を実サンプル付きで解説
  • 実動サンプル: コードチャンク・Observable JS がその場で動く
  • テンプレート集: プロジェクト設定 / 出力形式 / サイト / ブログ / 書籍などの雛形
  • 正確性: 実在しない記法（defaults キー、output-extensions、quarto check project、lang: jp など）は全面修正済み
  • CI 自動公開: quarto render → _site/ → GitHub Pages

使い方

git clone https://github.com/watanabe3tipapa/quarto-pe.git
cd quarto-pe
quarto preview        # ローカル確認
quarto render         # レンダリング（_site/ に出力）
quarto render reference.qmd   # 単一ファイルだけ

main への push で GitHub Actions が自動ビルド・デプロイします。

長所

  • 正確性が担保されている: 実在キー・実コマンドだけを掲載し、誤記を排除する方針
  • 体系的: 散在するキーをカテゴリ別に一覧化
  • コピペで即利用: テンプレート集から自分のプロジェクトに貼るだけ
  • 実動体験: コードチャンクや Observable JS が動くので「書いてみる」と「動かしてみる」を同時に学べる
  • quarto-dsh の知識基盤: YAML キー辞書・記法辞書の出典

短所・制約

  • 個人備忘録ベース: 網羅性は公式ドキュメントには及ばず、更新は手動に依存する
  • R 依存: コードチャンクの実動には R が別途必要（書式の学習だけなら不要）
  • 検証時点の情報: 掲載内容は「手元の Quarto 1.3+ で検証した時点」のもので、Quarto のバージョンアップに追随が必要
  • ツールではない: リファレンス・テンプレート集であり、自動検証や自動化の機能は持たない（そこは quarto-dsh の担当）

適用例

  • プロジェクトを新規作成するときの _quarto.yml の土台づくり
  • 「この設定キーは実在するのか」を確認する辞書代わり
  • コールアウト・相互参照など Q markdown 記法の学習・復習

関連