mcpField
P
preview

preview

github.com/allenaiDocuments4360 installsUpdated today
Repository

About preview

A skill for rendering and deploying project documents, reports, and notebooks with Quarto. It guides setup for local previews, GitHub Pages deployment, and pull request previews through CI.

Key features

  1. 01Quarto local preview and rendering
  2. 02Quarto project setup guidance
  3. 03GitHub Pages deployment setup
  4. 04CI-based pull request previews
  5. 05Deployment status checks with gh

Use cases

  1. 01Previewing document changes locally
  2. 02Publishing project documentation on GitHub Pages
  3. 03Reviewing rendered documentation in pull requests
  4. 04Setting up CI checks for documentation

Install

Copy the command and run it in a terminal.

$npx skills add https://github.com/allenai/asta-plugins --skill preview

After installing, type/previewin Claude Code to confirm it loaded.

Bundled filesassets/_quarto.ymlassets/docs.yml

Details

From the project README

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

Comments

Markdown supported