diff --git a/.claude/skills/blog-post/SKILL.md b/.claude/skills/blog-post/SKILL.md new file mode 100644 index 0000000000..be03481e5b --- /dev/null +++ b/.claude/skills/blog-post/SKILL.md @@ -0,0 +1,160 @@ +--- +name: quarto-blog-post +description: Use when writing, drafting, or editing blog posts for quarto.org, creating Quarto feature or release announcements, or reviewing blog post drafts for the Quarto website. +--- + +# Quarto Blog Post + +Write blog posts for `quarto.org/blog` matching the voice, structure, and conventions +from 40+ existing posts. + +## Setup + +1. `ls docs/blog/posts/` — browse existing posts for reference +2. Read `docs/blog/posts/_metadata.yml` — inherited by all posts (Giscus comments, + title-block-banner, left TOC, signup widget, `search: false`) +3. If the post covers a Quarto feature, read the relevant docs page for accurate + terminology and linking. + +## File Structure + +``` +docs/blog/posts/YYYY-MM-DD-slug/ + index.qmd # The post (required) + thumbnail.png # Listing card image (required) + *.png, *.jpg # Additional images + _contribs.md # Contributor list (release posts only) +``` + +Directory name: `YYYY-MM-DD-slug` — date matches frontmatter, slug is short kebab-case. + +## Frontmatter + +```yaml +--- +title: "Post Title" +description: | + One to three sentences for listing cards and social sharing. +author: Author Name +date: "YYYY-MM-DD" +categories: + - Category1 + - Category2 +image: thumbnail.png +image-alt: "Descriptive alt text for the thumbnail." +--- +``` + +**title**: Short. Release posts: `"Quarto X.Y"`. Backtick code spans OK. + +**description**: Self-contained summary (makes sense without the title). Always `|` block scalar. + +**author**: Plain string for staff (`Charlotte Wickham`). Two authors: `Name and Name`. +Guest authors use structured form with `name:` and optional `url:`. + +**date**: ISO 8601 `"YYYY-MM-DD"`. Must match directory name. + +**categories**: 2-3 per post. Use existing values — scan recent posts to check. Common: +`Releases`, `Quarto X.Y`, `Features`, `Authoring`, `Learn`, `Workshop`, `Conference`, +`Tip`, `Extensions`, `Tables`, `Teaching`, `Jupyter`. + +**image / image-alt**: `thumbnail.png` preferred. `image-alt` is mandatory. +See `references/thumbnail-guide.md` for dimensions, visual style, and design patterns. + +**Optional**: `lightbox: true` (many screenshots), `draft: true` (while developing). +Do not use `subtitle:` (phased out after 2023). + +## Post Types + +Identify the type before writing — it determines structure, opening, and closing. +Read `references/post-types.md` for detailed structure guidance per type. + +| Type | When | Key trait | +|------|------|-----------| +| **Release** | New Quarto version ships | Most structured: features → Other Highlights → Acknowledgements | +| **Feature** | Spotlight a specific capability | Concept-driven sections, docs links | +| **How-to** | Tutorial or walkthrough | Problem → solution, sequential steps | +| **News** | Short announcement, roundup | Very short, layout-heavy, minimal prose | + +## Writing Voice + +**First-person plural**: "We" for team work, "you" for the reader. + +**Warm, not marketing**: "We're excited about this feature" — good. +"This groundbreaking capability" — bad. Collegial tone, sharing with practitioners. + +**Direct openers**: Get to the point immediately. No "In this blog post, we will..." +preambles. State what happened or what the feature does, then elaborate. + +**Technical accuracy**: Use exact terminology from the docs. Link to docs rather than +trying to replicate them — the post introduces, the docs page is the reference. + +**Thank contributors**: Call out external contributors warmly inline. + +## Technical Conventions + +### Images + +Every image must have `fig-alt=` text — non-negotiable accessibility standard. + +```markdown +![](screenshot.png){fig-alt="Description of what the screenshot shows."} +``` + +Multi-image layouts use Quarto's layout system (`{layout-ncol="2"}`). +For many images, add `{.lightbox group="name"}`. + +### Code Blocks + +Always specify language. Use `filename=` labels for file content or terminal commands: + +````markdown +```{.yaml filename="_quarto.yml"} +project: + type: website +``` +```` + +### Links + +Every feature mentioned links to its docs page. Pattern: explain briefly, show example, +then link. Use site-root-relative paths: `[Feature](/docs/path.qmd)`. + +### Callouts + +Use sparingly: `.callout-tip` for post origin context, `.callout-warning` for caveats, +`.callout-note` for prerequisites. Release posts typically skip callouts. + +### Shortcodes + +- `{{< prerelease-callout X.Y type="blog" >}}` — pre-release banner (auto-disappears) +- `{{< video URL >}}` — video embed +- `{{< include file.md >}}` — include generated content + +## Workflow + +1. **Identify post type** → read `references/post-types.md` for that type +2. **Create directory**: `docs/blog/posts/YYYY-MM-DD-slug/` +3. **Write frontmatter** per schema above +4. **Draft body** following type-specific structure +5. **Add images** with `fig-alt=` on every one +6. **Link to docs** for every feature mentioned +7. **Create thumbnail** (or note one is needed) +8. **Review**: direct opener? code blocks fenced with language? all images alt-texted? + docs links present? closing matches type convention? categories correct? + +## Publishing + +When ready to publish, set the post date to today and rename the directory: + +```bash +quarto run _tools/publish-date.ts docs/blog/posts/YYYY-MM-DD-slug +``` + +This updates `date:` in frontmatter and renames the directory to match. Run it +on the day you intend to merge — avoids manual date edits if the publish date slips. + +## PR Workflow + +PR to `main` first. On merge, auto-backport creates cherry-pick PR to `prerelease`. +Push branches to `upstream` remote (quarto-dev/quarto-web), not `origin`. diff --git a/.claude/skills/blog-post/references/post-types.md b/.claude/skills/blog-post/references/post-types.md new file mode 100644 index 0000000000..cdf2475c25 --- /dev/null +++ b/.claude/skills/blog-post/references/post-types.md @@ -0,0 +1,99 @@ +# Post Type Reference + +Detailed structure guidance for each blog post type. Read the section that matches +your post — you rarely need all four. + +## Release Announcements + +The most structured type. Readers expect consistency across releases. + +**Opening**: One direct sentence announcing the release, immediately followed by +download and changelog links. No preamble. + +```markdown +Quarto 1.9 is out! You can get the current release from the +[download page](/docs/download/index.qmd). Read the full +[changelog](https://github.com/quarto-dev/quarto-cli/releases/tag/v1.9) +for a complete list of changes. +``` + +**Feature sections**: Each major feature gets a `##` heading named after the feature +(not "What's New"). Order by importance. Each section: +- Explain in 2-3 sentences +- Code example or screenshot (or both) +- Link to docs: "Learn more at [Feature Name](/docs/path)." + +**Other Highlights**: `## Other Highlights` bundles smaller improvements. Format: + +```markdown +- [Feature Name](/docs/path)---Short description of what it does. +``` + +Note the em-dash (`---`) between link and description. + +**Dependency updates**: List bundled tool updates (Pandoc, Typst, Deno) after Other +Highlights if applicable. + +**Closing**: Always `## Acknowledgements`. Thank contributors. Recent releases use +`{{< include _contribs.md >}}`. Release posts with emoji thumbnails include OpenMoji +attribution at the very end. + +**Categories**: Always `Quarto X.Y` + `Releases`. + +--- + +## Feature Announcements + +Spotlight a specific feature, often published before the corresponding release. More +varied structure than release posts. + +**Opening**: If unreleased, add prerelease callout at the very top: + +```markdown +{{< prerelease-callout 1.10 type="blog" >}} +``` + +Then a direct statement of what the feature does. Get to the point — readers clicked +because the title caught their interest. + +**Body**: Organize around the feature's concepts, not a "what's new" list. `##` +headings name the concept being explained. + +Problem/Solution framing works well for features that address a pain point: explain +the problem first, then show how the feature solves it. + +**Closing**: Link to the documentation. "Learn more on the [Feature Name](/docs/path) +page." No acknowledgements section. + +--- + +## Technical How-to Posts + +Tutorial-style walkthroughs. + +**Opening**: If based on a talk or repost, start with a `.callout-tip` providing context +and linking the original source. Then frame the use case — what problem does the reader +have? + +**Body**: Walk through steps sequentially. Heading names can be conversational — verbs +and questions are fine ("Create the content", "Why are we doing this?"). Use numbered +sub-steps when sequence matters. + +Show before/after comparisons with `{layout-ncol="2"}` divs. + +**Closing**: Brief summary of what was covered, or a "Learn more" section with resource +links. No acknowledgements. + +--- + +## News/Community Posts + +Short announcements, conference roundups, workshop materials. The lightest type. + +**Opening**: One direct summary sentence. + +**Body**: Often visual grids rather than prose. Conference roundups use +`{layout="[70,30]"}` divs pairing descriptions with thumbnails. Video posts embed +with `{{< video >}}`. + +**Closing**: May have no explicit closing — the content structure speaks for itself. diff --git a/.claude/skills/blog-post/references/thumbnail-guide.md b/.claude/skills/blog-post/references/thumbnail-guide.md new file mode 100644 index 0000000000..6d8007db8b --- /dev/null +++ b/.claude/skills/blog-post/references/thumbnail-guide.md @@ -0,0 +1,143 @@ +# Thumbnail Guide + +Design conventions for blog post listing card images, derived from 40 existing posts. + +## Dimensions and Format + +- **Size**: 1200x630 px (Open Graph / social card standard) +- **Format**: PNG preferred (34 of 40 posts use PNG) +- **HiDPI**: Some posts use 2400x1260 (2x) — same aspect ratio, sharper on retina + +The 1200x630 ratio (~1.9:1) is the current standard for all post types from 2024 onward. +Earlier posts used inconsistent sizes — don't follow those as examples. + +## Quarto Brand Colors + +Sourced from the website CSS (`index.css`): + +| Color | Hex | Usage | +|-------|-----|-------| +| Hero light blue | `#F0F5F9` | Light background for thumbnails and hero sections | +| Quarto blue | `#5286AB` | Primary brand blue — icons, elements, accents | +| Hero heading blue | `#39729E` | Darker blue for headings in light mode | +| Steel blue | `#4D6E8E` | Release post backgrounds (legacy convention) | + +**Contrast guideline**: Light backgrounds (`#F0F5F9`) with Quarto blue (`#5286AB`) +elements provide better contrast than colored backgrounds with white elements, +especially for icon compositions where the icon has its own color palette. + +## Visual Style by Post Type + +### Release posts + +All use the same template: + +- Steel blue solid background (~#4d6e8e) +- Centered Quarto logo (circle-crosshair) + wordmark in white +- Large bold version number in white (e.g., "1.9") +- One small thematic emoji-style illustration (unique per release) + +The only creative variable is the illustration — background, typography, logo placement, +and layout are identical across 1.4 through 1.9. Release thumbnails that use emoji +illustrations include an OpenMoji attribution at the end of the post. + +### Feature and how-to posts + +Two palettes available: + +- **Light background** (preferred for icon compositions): `#F0F5F9` background with + Quarto blue (`#5286AB`) icons and elements. Use when the design includes third-party + logos/icons with their own colors — avoids contrast problems. +- **Steel blue background** (legacy): `#4D6E8E` background with white icons. Works + for simple compositions but can have contrast issues with blue-toned icons. + +Content patterns: + +- **Icon compositions**: Outline icons arranged with arrows or connectors showing + a concept (e.g., Chromium → terminal + Quarto for chrome-headless-shell post) +- **Diagrams/explainers**: Simple visual showing the concept (e.g., notebook → reports + with arrow for parameterized reports post) +- **Screenshots**: Cropped screenshot of the feature output (older convention, less common now) + +### Conference and workshop posts + +Use Posit conference brand templates rather than the Quarto steel blue: + +- Dark navy or teal backgrounds with 3D isometric block illustrations +- Conference logo placement (posit::conf branding) +- Speaker/instructor names in white text + +### Partner/integration posts + +Use the partner's own logo on a white or neutral background (e.g., Hugging Face logo, +Confluence logo). No Quarto branding needed — the partner identity is the visual. + +## Creating Thumbnails + +### Prerequisites + +The screenshot step needs a headless browser. If `agent-browser` is installed +(`npm i -g agent-browser`), use the examples below. If not, any tool that can +screenshot an HTML page at a fixed viewport works — Playwright, Puppeteer, or +even opening the HTML in Chrome DevTools at a locked viewport and saving manually. + +If no headless tool is available, create the SVG and ask someone with the tooling +to generate the PNG, or open the HTML in a browser and use the OS screenshot tool +at the right dimensions. + +### HTML/CSS + screenshot approach (recommended) + +Create an HTML file sized to 1200x630 with the design, then screenshot it: + +1. **Source SVG icons** — good free sources: + - [svgrepo.com](https://www.svgrepo.com) — many Public Domain (PD) icons, no attribution needed + - [icon-icons.com](https://icon-icons.com) — CC BY 4.0 icons, attribution required +2. **Build an HTML file** — set `body` to 1200x630, embed SVG icons inline, use + flexbox for layout. Choose background color based on post type (see above). +3. **Serve and screenshot** — serve the HTML locally and screenshot at 1200x630. + Use any local HTTP server + headless browser screenshot tool. Examples: + + With `agent-browser` + a local server: + ```bash + # Serve with any static server (python, npx serve, simple-http-server, etc.) + python -m http.server 8181 -d path/to/post/dir & + agent-browser batch "set viewport 1200 630" \ + "open http://127.0.0.1:8181/thumbnail.html" \ + "screenshot path/to/thumbnail.png" + agent-browser close + ``` + + With `file://` protocol (no server needed, requires `--allow-file-access`): + ```bash + agent-browser close # Ensure clean daemon start + agent-browser --allow-file-access batch "set viewport 1200 630" \ + "open file:///absolute/path/to/thumbnail.html" \ + "screenshot path/to/thumbnail.png" + agent-browser close + ``` +4. **Save SVG source** — save a standalone `thumbnail.svg` in the post directory + alongside the PNG. This makes future edits easy (color changes, element swaps) + without recreating from scratch. +5. **Clean up** — delete the HTML source after confirming the PNG looks correct. + Keep the SVG for future reference. + +**Always use PNG as the thumbnail (`image: thumbnail.png`), never SVG.** Standalone +SVGs don't center properly in Quarto listing cards or social card previews — the +HTML uses flexbox for centering which SVG can't replicate without duplicating all +the layout logic. The SVG is only a source file for regenerating the PNG. + +The Quarto logo SVG is at the repo root: `quarto-icon.svg` (fill color `#74AADB` +— recolor to `#5286AB` for thumbnails or `white` for dark backgrounds). + +### Attribution + +When using third-party icons, add an attribution line at the very end of the post +(after the last content section). Match the format used in existing posts: + +```markdown +The [icon description] in the [listing and social card image](thumbnail.png) for this +post is by [Author](url){.external} via [source](url){.external}. +License: [CC BY 4.0](https://creativecommons.org/licenses/by/4.0/){.external} +``` + +Public Domain icons (e.g., from svgrepo.com PD collection) need no attribution. diff --git a/.github/workflows/README.md b/.github/workflows/README.md index 1f956889fd..5839ea4acb 100644 --- a/.github/workflows/README.md +++ b/.github/workflows/README.md @@ -21,6 +21,7 @@ Note that technically, is also a deploy preview on Netli - They are automically created and updated when the PR is created and updated by a user with Contributor role. - For external PR, the preview can be triggered by adding a comment `/deploy-preview` on the PR. - Any rendering to prerelease also uses a specific profile at render time, set in action using `QUARTO_PROFILE` environment variable. + - Deploy previews use the `pr-preview` profile (`_quarto-pr-preview.yml`) which sets `draft-mode: visible` so that draft blog posts and pages are rendered and visible in PR previews. This is needed because `quarto render` (used in CI) hides drafts by default, unlike `quarto preview` (used locally) which always shows them. - `update-downloads.yml` - This workflow is triggered by a cron schedule. It retrieves information about latest release and prerelease on `quarto-dev/quarto-cli` repository and updates the download links on the website. - If there is a new version detected, it will commit the modified files and trigger a deploy of the website calling `publish.yml` workflow with `workflow_call` event trigger. @@ -34,12 +35,24 @@ Note that technically, is also a deploy preview on Netli - This index file is retrieved on deployed website to be updated on Algolia. - Both `quarto.org` and `prerelease.quarto.org` indexes are updated in the same run - they each use one specific algolia index +- `draft-check.yml` - A lightweight workflow that detects `draft: true` pages among changed `.qmd` files. Runs on all PRs to `main` and `prerelease` with no `paths-ignore`, so it always creates a status check. + - Uses the reusable composite action at `.github/workflows/actions/detect-drafts/`. + - Configured as a required status check on `main` (`check-drafts` job), blocking merge until `draft: true` is removed. + - Admin override is available for intentional draft merges. + - `port-to-prerelease.yml` - This workflow is used to sync changes made to main for quarto.org to prerelease branch for prerelease.quarto.org. - It is triggered when a PR is merged in to `main`. It can also be triggered manually by adding a comment `/sync-prerelease` on a merged PR. - This workflow uses [`korthout/backport-action`](https://github.com/korthout/backport-action) to create a PR with the changes merged into `main` branch to be synced to `prerelease` branch. - It will also write a new `/deploy-preview` comment in the new PR to trigger the preview deployment from `preview.yml`. - This is possible because it uses a fine-grained PAT token which allows a workflow to trigger another using usual event (GITHUB_TOKEN does not allow that usually). This is configured in repo secrets. +## Reusable Composite Actions + +Local composite actions live in `.github/workflows/actions/`: + +- `detect-drafts/` - Scans changed `.qmd` files for `draft: true` in YAML frontmatter. Outputs `found` (true/false) and `files` (newline-separated paths). Used by both `preview.yml` (to tag drafts in the PR comment) and `draft-check.yml` (to fail the required check). +- `release-info/` - Retrieves release information from the quarto-cli repository. + ## Netlify Configurations - This repo has a `_redirects` file in the root directory. Otherwise, configuration are made in NETLIFY UI. Quarto website is inside Posit Netlify account. diff --git a/.github/workflows/actions/detect-drafts/action.yml b/.github/workflows/actions/detect-drafts/action.yml new file mode 100644 index 0000000000..aeba1df7f5 --- /dev/null +++ b/.github/workflows/actions/detect-drafts/action.yml @@ -0,0 +1,36 @@ +name: 'Detect Draft Pages' +description: 'Scan changed .qmd and .md files for draft: true in YAML frontmatter' +inputs: + changed-files: + description: 'JSON array of changed file paths (from tj-actions/changed-files)' + required: true +outputs: + found: + description: 'Whether any draft pages were found (true/false)' + value: ${{ steps.detect.outputs.found }} + files: + description: 'Newline-separated list of draft file paths' + value: ${{ steps.detect.outputs.files }} +runs: + using: composite + steps: + - id: detect + env: + CHANGED_FILES: ${{ inputs.changed-files }} + run: | + DRAFTS=$(echo "$CHANGED_FILES" | jq -r '.[]' | while read -r file; do + if [[ "$file" == *.qmd || "$file" == *.md ]] && [ -f "$file" ]; then + if sed -n '/^---$/,/^---$/p' "$file" | grep -qE '^[[:space:]]*draft:[[:space:]]*true[[:space:]]*$'; then + echo "$file" + fi + fi + done) + if [ -n "$DRAFTS" ]; then + echo "found=true" >> "$GITHUB_OUTPUT" + echo "files<> "$GITHUB_OUTPUT" + echo "$DRAFTS" >> "$GITHUB_OUTPUT" + echo "EOF" >> "$GITHUB_OUTPUT" + else + echo "found=false" >> "$GITHUB_OUTPUT" + fi + shell: bash diff --git a/.github/workflows/draft-check.yml b/.github/workflows/draft-check.yml new file mode 100644 index 0000000000..208074bd42 --- /dev/null +++ b/.github/workflows/draft-check.yml @@ -0,0 +1,44 @@ +on: + pull_request: + branches: [main, prerelease] + +name: Draft Check + +jobs: + check-drafts: + runs-on: ubuntu-latest + steps: + - name: Check out repository + uses: actions/checkout@v6 + + - name: Get changed files + id: changed-files + uses: tj-actions/changed-files@22103cc46bda19c2b464ffe86db46df6922fd323 # v47.0.5 + with: + files: | + docs/**/*.qmd + docs/**/*.md + json: true + escape_json: false + + - name: Detect draft pages + id: detect-drafts + uses: ./.github/workflows/actions/detect-drafts + with: + changed-files: ${{ steps.changed-files.outputs.all_changed_files }} + + - name: Report results + run: | + if [ "${{ steps.detect-drafts.outputs.found }}" == "true" ]; then + echo "### ⚠️ Draft pages detected" >> "$GITHUB_STEP_SUMMARY" + echo "" >> "$GITHUB_STEP_SUMMARY" + echo "Remove \`draft: true\` before merging:" >> "$GITHUB_STEP_SUMMARY" + echo '${{ steps.detect-drafts.outputs.files }}' | while read -r f; do + [ -n "$f" ] && echo "- \`$f\`" >> "$GITHUB_STEP_SUMMARY" + done + echo "::error::This PR contains pages with draft: true. Remove draft status before merging." + exit 1 + else + echo "No draft pages found." >> "$GITHUB_STEP_SUMMARY" + fi + shell: bash diff --git a/.github/workflows/preview.yml b/.github/workflows/preview.yml index 9750fb0471..7ab34706c8 100644 --- a/.github/workflows/preview.yml +++ b/.github/workflows/preview.yml @@ -116,10 +116,10 @@ jobs: fi shell: bash - - name: Render + - name: Render uses: quarto-dev/quarto-actions/render@v2 env: - QUARTO_PROFILE: ${{ steps.prerelease-docs-check.outputs.is_prerelease_docs == 'true' && 'prerelease-docs' || '' }} + QUARTO_PROFILE: ${{ steps.prerelease-docs-check.outputs.is_prerelease_docs == 'true' && 'prerelease-docs,pr-preview' || 'pr-preview' }} - name: Deploy Preview to Netlify as preview id: netlify-deploy @@ -182,6 +182,12 @@ jobs: fi shell: bash + - name: Detect draft pages + id: detect-drafts + uses: ./.github/workflows/actions/detect-drafts + with: + changed-files: ${{ steps.changed-files.outputs.all_changed_files }} + - name: Create custom PR comment if: github.event.pull_request || github.event.issue.pull_request uses: actions/github-script@v8 @@ -189,12 +195,16 @@ jobs: DEPLOY_URL: ${{ steps.netlify-deploy.outputs.deploy-url }} CHANGED_FILES: ${{ steps.changed-files.outputs.all_changed_files }} IMAGE_PAGES: ${{ steps.image-pages.outputs.pages }} + DRAFT_FILES: ${{ steps.detect-drafts.outputs.files }} + HAS_DRAFTS: ${{ steps.detect-drafts.outputs.found }} with: github-token: ${{ secrets.GITHUB_TOKEN }} script: | const prNumber = context.payload.pull_request?.number || context.payload.issue.number; const deployUrl = process.env.DEPLOY_URL; const changedFiles = JSON.parse(process.env.CHANGED_FILES || '[]'); + const draftFilesList = (process.env.DRAFT_FILES || '').trim().split('\n').filter(Boolean); + const draftSet = new Set(draftFilesList); let commentBody = `## 📝 Preview Deployment\n\n`; commentBody += `🔍 Full site preview: [${deployUrl}](${deployUrl})\n\n`; @@ -251,14 +261,16 @@ jobs: commentBody += `### 🔄 Modified Documents\n\n`; for (const [page, files] of pageToFiles) { const fileUrl = `${deployUrl}/${page}`; + const isDraft = files.some(f => draftSet.has(f)); + const draftTag = isDraft ? ' — ⚠️ `draft`' : ''; if (files.length === 1) { - commentBody += `- [${page}](${fileUrl})\n`; + commentBody += `- [${page}](${fileUrl})${draftTag}\n`; } else { // Multiple source files map to one page - show page with file summary const basenames = files.map(f => f.split('/').pop()); const shown = basenames.slice(0, 3).join(', '); const rest = basenames.length > 3 ? `, +${basenames.length - 3} more` : ''; - commentBody += `- [${page}](${fileUrl}) (${shown}${rest})\n`; + commentBody += `- [${page}](${fileUrl}) (${shown}${rest})${draftTag}\n`; } } } @@ -277,9 +289,17 @@ jobs: } } - github.rest.issues.createComment({ + // Add draft warning callout (no file list — already tagged inline above) + const hasDrafts = process.env.HAS_DRAFTS === 'true'; + if (hasDrafts) { + commentBody += `\n> [!WARNING]\n`; + commentBody += `> This PR contains pages with \`draft: true\`. Remove the draft status before merging if the content is ready to publish.\n`; + } + + await github.rest.issues.createComment({ issue_number: prNumber, owner: context.repo.owner, repo: context.repo.repo, body: commentBody - }); \ No newline at end of file + }); + diff --git a/README.md b/README.md index 023d7ef934..9fbc21fd0e 100644 --- a/README.md +++ b/README.md @@ -132,6 +132,12 @@ The group order determines which phase is active on **quarto.org** (the main sit |---|---| | `_quarto-prerelease-docs.yml` | Site-specific configuration for prerelease.quarto.org | +**CI profile** (`pr-preview`) is used by the deploy preview workflow to render `draft: true` pages as visible. `quarto render` hides drafts by default, but PR reviewers need to see them. + +| File | Purpose | +|---|---| +| `_quarto-pr-preview.yml` | Sets `draft-mode: visible` for deploy previews | + ### Subdomain variable and shortcode **`prerelease-subdomain`** — site identity variable ("am I the prerelease site?"). Default `''` in `_quarto.yml`, set to `prerelease.` in `_quarto-prerelease-docs.yml`. Use for self-referential links (e.g. RevealJS demo links back to its own site). diff --git a/_quarto-pr-preview.yml b/_quarto-pr-preview.yml new file mode 100644 index 0000000000..096d35b992 --- /dev/null +++ b/_quarto-pr-preview.yml @@ -0,0 +1,2 @@ +website: + draft-mode: visible diff --git a/_tools/README.md b/_tools/README.md new file mode 100644 index 0000000000..36da40449a --- /dev/null +++ b/_tools/README.md @@ -0,0 +1,33 @@ +# Project Scripts (`_tools/`) + +Utility scripts for the quarto-web project. Run with `quarto run` (TypeScript, R, Python, or Lua). + +## Scripts + +| Script | Language | Description | +|--------|----------|-------------| +| `publish-date.ts` | TypeScript | Set a blog post date to today and rename its directory to match | +| `algolia-add-custom-attribute.ts` | TypeScript | Post-render hook: adds custom attributes to Algolia search index | +| `reference.ts` | TypeScript | Generate reference documentation | +| `reference-cli-generate-md.R` | R | Generate CLI reference markdown | +| `gallery-screenshot.R` | R | Capture gallery screenshots | +| `sort-gallery.R` | R | Sort gallery entries | +| `release-notes.R` | R | Generate release notes content | +| `snapshot-typst.ts` | TypeScript | Capture Typst document snapshots as PNG | + +## Usage + +```bash +# Run any script +quarto run _tools/