preview

Preview

Render and deploy project documents, reports, and notebooks using Quarto.

Usage

If _quarto.yml or .github/workflows/docs.yml is missing, complete the setup sections below first.

Push the branch. CI renders and deploys automatically. PR preview URLs: https://<owner>.github.io/<repo>/pr-preview/pr-<number>/ (private repos use an obfuscated domain but the same path structure). Check CI status with gh run list / gh run view.

For local preview: quarto preview (hot reloads). One-time build: quarto render.

Quarto Project Setup

If the project doesn't have a _quarto.yml yet, confirm the plan with the user, then:

1. Check which quarto. If not installed locally, see https://quarto.org/docs/get-started/ — or use the Workspace skill to get a devcontainer with Quarto pre-installed.
2. Copy assets/_quarto.yml to the project root and adjust the title.
3. Create an index.qmd with YAML frontmatter (title: at minimum). Use .qmd for all documents — it's Quarto's canonical format and required for full tooling support.
4. Add _site/ and .quarto/ to .gitignore.
5. Each subdirectory needs an index.qmd or its sidebar link will 404.

GitHub Pages Setup

Set this up to deploy rendered docs via GitHub Pages with PR previews. If the project doesn't have .github/workflows/docs.yml yet, confirm the plan with the user, then:

1. Copy assets/docs.yml to .github/workflows/docs.yml. This workflow renders with Quarto, validates the output (fails on warnings like broken citations), and deploys with PR preview support.
2. Pages must serve from the gh-pages branch, not "GitHub Actions" workflow mode — the artifact model can't host PR previews alongside the main site.

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

3. Require CI to pass and PRs for all changes to main. This overwrites existing branch protection (docs):

   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