preview

プレビュー

Quarto を使用して、プロジェクトのドキュメント、レポート、ノートブックをレンダリングしてデプロイします。

使用方法

_quarto.yml または .github/workflows/docs.yml がない場合は、まず以下のセットアップ手順を完了してください。

ブランチをプッシュします。CI が自動的にレンダリングしてデプロイします。PR のプレビュー URL：https://<owner>.github.io/<repo>/pr-preview/pr-<number>/（プライベートリポジトリではドメインが難読化されますが、パスの構造は同じです）。gh run list / gh run view で CI のステータスを確認します。

ローカルでプレビューするには、quarto preview を実行します（ホットリロードに対応しています）。一度だけビルドするには、quarto render を実行します。

Quarto プロジェクトのセットアップ

プロジェクトに _quarto.yml がまだない場合は、ユーザーに計画を確認してから、次の手順を実行します。

1. which quarto を確認します。ローカルにインストールされていない場合は、https://quarto.org/docs/get-started/ を参照するか、Workspace スキルを使って Quarto が事前にインストールされた開発用コンテナを取得します。
2. assets/_quarto.yml をプロジェクトのルートにコピーし、タイトルを調整します。
3. YAML フロントマター（最低限 title:）を含む index.qmd を作成します。すべてのドキュメントに .qmd を使用してください。これは Quarto の標準形式であり、すべてのツール機能を利用するために必要です。
4. _site/ と .quarto/ を .gitignore に追加します。
5. サブディレクトリごとに index.qmd が必要です。ない場合、サイドバーのリンクは 404 エラーになります。

GitHub Pages のセットアップ

レンダリングしたドキュメントを GitHub Pages でデプロイし、PR のプレビューを利用できるようにするには、このセットアップを行います。プロジェクトに .github/workflows/docs.yml がまだない場合は、ユーザーに計画を確認してから、次の手順を実行します。

1. assets/docs.yml を .github/workflows/docs.yml にコピーします。このワークフローは Quarto でレンダリングし、出力を検証して（引用の不備などの警告があると失敗します）、PR のプレビューに対応した形でデプロイします。
2. Pages の配信元は「GitHub Actions」ワークフローモードではなく、gh-pages ブランチにする必要があります。アーティファクトモデルでは、メインサイトと並行して PR のプレビューをホストできません。

   gh api repos/{owner}/{repo}/pages -X POST --input - <<'EOF'
   {"build_type":"legacy","source":{"branch":"gh-pages","path":"/"}}
   EOF
   

3. main へのすべての変更について、CI の通過と PR を必須にします。これにより、既存のブランチ保護が上書きされます（ドキュメント）。

   gh api repos/{owner}/{repo}/branches/main/protection -X PUT --input - <<'EOF'
   {
     "required_status_checks": {"strict": false, "contexts": ["build-and-deploy"]},
     "enforce_admins": false,
     "required_pull_request_reviews": {"required_approving_review_count": 0},
     "restrictions": null
   }
   EOF