Rework blog-post skill for the new blog home (#2133)

* Rework blog-post skill for the open-source-website blog home

Posts are now authored in posit-dev/open-source-website: frontmatter is
scaffolded from its blog archetype via hugo new (mirroring /new-post),
docs links become absolute quarto.org URLs, thumbnails move to 1920x1080
(Typst templates rescaled and re-verified), and the old quarto.org
scaffolding, categories, publish-date.ts, and backport sections are
dropped. Release-post specifics move out of the general sections into
references/post-types.md.

* Read docs from the repo, link to quarto.org, flag pending-merge links

Drafting ahead of a release means the docs may only exist on the
prerelease branch, not yet on quarto.org. Direct the skill to source
terminology from quarto-web (working tree, then origin/prerelease),
derive absolute quarto.org URLs from repo paths, verify each link, and
flag links that won't resolve until the release-time merge.

* Add release-post prose guidance from the 1.10 draft run

Document the summary-paragraph convention (one short noun phrase per
major feature) and lean feature prose: cut why-this-matters clauses,
scope claims precisely, cover only the headline change.

* Document how to display literal shortcode syntax in posts

Verified against the ported Quarto posts and scratch renders: displayed
shortcode examples need a code context (never prose), a Quarto-side
escape (triple braces or shortcodes="false" on the fence), and the
site's escape-shortcodes Lua filter, which ported Quarto posts get via
_metadata.yml and new posts opt into via frontmatter. Escapes in prose
reach Hugo live - a known name silently renders, an unknown name fails
the site build.

* Advise on tags as the home for the old categories vocabulary

The port moved each post's quarto.org categories into its tags, so tags
carry that vocabulary forward (Releases, Quarto X.Y, Features, Learn,
...). Reuse existing corpus tags, skip a bare Quarto tag that would
duplicate source/software, and give release posts Quarto X.Y + Releases.

Author: cwickham

.claude/skills/blog-post/SKILL.md

@@ -1,70 +1,90 @@
 ---
 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.
+description: Use when writing, drafting, or editing Quarto blog posts, creating Quarto feature or release announcements, or reviewing Quarto blog post drafts. Quarto posts publish on the Posit Open Source blog (posit-dev/open-source-website), not on quarto.org.
 ---
 
 # Quarto Blog Post
 
-Write blog posts for `quarto.org/blog` matching the voice, structure, and conventions
-from 40+ existing posts.
+Write Quarto blog posts matching the voice, structure, and conventions of 40+
+prior posts. Since May 2026 the Quarto blog lives on the
+[Posit Open Source website](https://opensource.posit.co/blog/q/quarto/):
+posts are authored and published in the
+[`posit-dev/open-source-website`](https://github.com/posit-dev/open-source-website)
+repo, not in quarto-web. This skill carries the Quarto-specific knowledge
+(post types, voice, thumbnails); defer to that repo's own guides for its
+mechanics.
 
 ## 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.
+1. Locate a local clone of `posit-dev/open-source-website` — conventionally a
+   sibling of this repo (`../open-source-website`). Clone it if missing.
+   Check `git status` before branching.
+2. Read, in its `content/blog/` directory:
+   - `CLAUDE.md` — frontmatter schema and taxonomies
+   - `_authoring-guide.md` — format choice, rendering, preview, and PR flow
+3. Browse `content/blog/ported/quarto/` for prior Quarto posts. Recent ones
+   (e.g. `2026-03-24-1.9-release/`) show the current frontmatter and structure
+   conventions.
+4. If the post covers a Quarto feature, read its docs from this repo — not
+   from quarto.org — so drafting works even when the docs aren't live yet.
+   Docs for an unreleased version live on the `prerelease` branch: check the
+   working tree first, then `git fetch origin prerelease` and
+   `git show origin/prerelease:docs/<path>`. quarto.org serves `main`, so
+   anything prerelease-only won't be live until the release-time merge — see
+   § Links for how to link to it anyway.
 
 ## File Structure
 
+In the open-source-website clone, on a branch named `blog/<slug>`:
+
 ```
-docs/blog/posts/YYYY-MM-DD-slug/
-  index.qmd        # The post (required)
-  thumbnail.png    # Listing card image (required)
+content/blog/<slug>/
+  index.qmd        # Source (required)
+  index.md         # Rendered output — always commit alongside the source
+  thumbnail.png    # Hero + listing card image, 1920×1080 (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.
+The folder name is the URL slug: short kebab-case, no date prefix
+(e.g. `quarto-1-10`). The published URL becomes `/blog/YYYY-MM-DD_<slug>/`
+from the frontmatter `date`. Never scaffold under `content/blog/ported/` —
+that tree is for migrated legacy posts.
 
 ## 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."
----
-```
+Don't write the frontmatter from memory — scaffold it from the repo's Hugo
+archetype (`archetypes/blog.md`, the source of truth for the schema; see
+Workflow step 2) and fill it in. Field meanings and taxonomies are documented
+in open-source-website's `content/blog/CLAUDE.md`.
 
-**title**: Short. Release posts: `"Quarto X.Y"`. Backtick code spans OK.
+Quarto-post specifics when filling in the scaffold:
 
-**description**: Self-contained summary (makes sense without the title). Always `|` block scalar.
+**source: quarto** — required, and not in the archetype. Places the post on
+the [Quarto project listing](https://opensource.posit.co/blog/q/quarto/),
+where old quarto.org blog URLs redirect. Set `software: quarto` too.
 
-**author**: Plain string for staff (`Charlotte Wickham`). Two authors: `Name and Name`.
-Guest authors use structured form with `name:` and optional `url:`.
+**date**: a future date schedules the post — Hugo hides it until a daily
+build (8 AM UTC) on the publish date, so set the date the PR is expected to
+merge (or later). No date-fixing script needed.
 
-**date**: ISO 8601 `"YYYY-MM-DD"`. Must match directory name.
+**image / image-alt**: set `image: thumbnail.png`, 1920×1080 (16:9) — used as
+both the hero and the listing card. `image-alt` is mandatory.
+See `references/thumbnail-guide.md` for the decision between the two
+production paths (Typst, or HTML+SVG) and the HTML+SVG flow. For the Typst
+path, see `references/typst-thumbnail.md`.
 
-**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`.
+**people**: full names, individuals only — never a team name.
 
-**image / image-alt**: `thumbnail.png` preferred. `image-alt` is mandatory.
-See `references/thumbnail-guide.md` for the decision between the two production
-paths (Typst, or HTML+SVG) and the HTML+SVG flow. For the Typst path, see
-`references/typst-thumbnail.md`.
+**tags**: freeform — this is where the old quarto.org `categories` vocabulary
+lives on (`Releases`, `Quarto X.Y`, `Features`, `Authoring`, `Learn`,
+`Workshop`, `Tip`, ...; the port moved each post's categories into its tags).
+Reuse tags already present in `content/blog/ported/quarto/` sources rather
+than coining synonyms, and skip a bare `Quarto` tag — `source` and `software`
+already cover it.
 
-**Optional**: `lightbox: true` (many screenshots), `draft: true` (while developing).
-Do not use `subtitle:` (phased out after 2023).
+Never add `ported_from` or `port_status` (migration metadata), and don't carry
+over the old quarto.org schema: no `categories`, no `subtitle`, no
+`_metadata.yml` inheritance.
 
 ## Post Types
 
@@ -103,8 +123,9 @@ Every image must have `fig-alt=` text — non-negotiable accessibility standard.
 ![](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"}`.
+Multi-image layouts use Quarto's layout system (`{layout-ncol="2"}`) — a Lua
+filter in open-source-website converts these for Hugo. Don't use `.lightbox`;
+that's a quarto.org HTML feature with no equivalent in the Hugo pipeline.
 
 ### Code Blocks
 
@@ -119,29 +140,101 @@ project:
 
 ### 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)`.
+**Docs links must be absolute**: `https://quarto.org/docs/...`, never a
+`.qmd` source path or a site-root-relative path — the post no longer lives on
+quarto.org. Derive the URL from the repo path:
+`docs/<path>/<page>.qmd` → `https://quarto.org/docs/<path>/<page>.html`.
+Every feature mentioned links to its docs page. Pattern: explain briefly,
+show example, then link.
+
+**Verify every quarto.org link resolves** (e.g.
+`curl -s -o /dev/null -w '%{http_code}' <url>`). A page whose docs exist only
+on the `prerelease` branch will 404 until the release-time
+`prerelease` → `main` merge. Keep the quarto.org URL anyway — never
+substitute the prerelease site's domain — and **flag every such
+pending-merge link when handing off the draft** so it's re-checked before the
+post publishes.
+
+**Other blog posts**: link with the permalink pattern `/blog/YYYY-MM-DD_slug/`
+(see the authoring guide), never content-directory paths.
 
 ### Callouts
 
 Use sparingly: `.callout-tip` for post origin context, `.callout-warning` for caveats,
-`.callout-note` for prerequisites. Release posts typically skip callouts.
+`.callout-note` for prerequisites. Quarto callouts render correctly through
+the Hugo pipeline.
 
 ### Shortcodes
 
-- `{{< prerelease-callout X.Y type="blog" >}}` — pre-release banner (auto-disappears)
 - `{{< video URL >}}` — video embed
 - `{{< include file.md >}}` — include generated content
 
+Both are processed by Quarto at render time and work in open-source-website.
+
+**Displaying literal shortcode syntax** (showing readers what to type) takes
+three ingredients — this is how every such example in the ported Quarto posts
+works (verified empirically):
+
+1. **Put the syntax in code** — a fenced block or inline code, never prose.
+   An escape in prose reaches Hugo as a live shortcode: a name Hugo knows
+   silently renders its output in place of your example; an unknown name
+   fails the entire site build.
+2. **Escape it so Quarto doesn't execute it**: triple braces
+   (`{{{< meta state >}}}`), or the `shortcodes="false"` attribute on a
+   fenced block (`{.markdown shortcodes="false"}`). Unescaped syntax in code
+   is swallowed at the Quarto stage, leaving empty code.
+3. **Opt into the site's escape filter** in the post frontmatter:
+
+   ```yaml
+   filters:
+     - escape-shortcodes
+   ```
+
+   The filter (`content/_extensions/escape-shortcodes`) rewrites `{{<` to
+   Hugo's comment escape in code contexts, so Hugo displays the syntax
+   instead of executing it. Ported Quarto posts get it automatically via
+   `content/blog/ported/quarto/_metadata.yml`; new posts must opt in.
+
+In prose, refer to shortcodes by name instead ("the `video` shortcode").
+
+**`{{< prerelease-callout >}}` does NOT exist there** — it's a quarto-web
+extension. For a post about an unreleased feature, write a static callout
+instead, and remove it once the version ships:
+
+```markdown
+::: {.callout-note}
+This feature is available in the
+[pre-release version of Quarto](https://quarto.org/docs/download/prerelease.html)
+and will be part of the upcoming X.Y release.
+:::
+```
+
 ## 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
+2. **Branch and scaffold** in the open-source-website clone, off up-to-date
+   `main`, mirroring its `/new-post` command:
+
+   ```bash
+   git checkout -b blog/<slug>
+   hugo new blog/<slug>/index.md
+   mv content/blog/<slug>/index.md content/blog/<slug>/index.qmd
+   ```
+
+   `hugo new` fills the frontmatter from `archetypes/blog.md`, so the schema
+   stays in sync with the site. If `hugo` isn't installed, copy the
+   frontmatter from `archetypes/blog.md` by hand instead — same source of
+   truth. (In a Claude session started in that repo, the `/new-post` command
+   runs this flow interactively.)
+3. **Fill in the frontmatter**: replace the placeholder `title`, `people`,
+   and `description`; trim `topics`, `languages`, and `tags` to what applies;
+   delete unused optional fields; and set the Quarto specifics above
+   (`source: quarto`, `image`/`image-alt`, `date`)
+4. **Draft body** following type-specific structure. Body headings start at
+   `##` — the H1 comes from `title`.
 5. **Add images** with `fig-alt=` on every one
-6. **Link to docs** for every feature mentioned
-7. **Create thumbnail**:
+6. **Link to docs** with absolute quarto.org URLs for every feature mentioned
+7. **Create thumbnail** (1920×1080):
    1. Read `references/thumbnail-guide.md` § Choosing your path
    2. **Always present both options as a question to the user**, even if one
       path is the obvious recommendation. State the recommendation with
@@ -151,21 +244,27 @@ Use sparingly: `.callout-tip` for post origin context, `.callout-warning` for ca
    3. Read the chosen path's reference and execute
       (`references/typst-thumbnail.md` for Typst, rest of `thumbnail-guide.md`
       for HTML+SVG)
-8. **Review**: direct opener? code blocks fenced with language? all images alt-texted?
-   docs links present? closing matches type convention? categories correct?
+8. **Render**: from the post directory, `quarto render index.qmd` — this
+   produces the `index.md` Hugo builds from. Commit `index.qmd`, `index.md`,
+   and any generated outputs together.
+9. **Validate**: from the open-source-website root:
+
+   ```bash
+   uv run scripts/validate-blog-posts.py content/blog/<slug>/index.md
+   ```
+
+   In a Claude session started in that repo, the `/check-post` and
+   `/review-post` commands run validation and a content review interactively.
+10. **Review**: direct opener? code blocks fenced with language? all images
+    alt-texted? absolute docs links, each verified live or flagged as
+    pending-merge? closing matches type convention? frontmatter complete
+    (`people`, `topics`, `source: quarto`)?
 
 ## 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`.
+Open a PR against `main` in `posit-dev/open-source-website` — never push
+directly to `main`. Posit org members push branches to the repo itself (no
+fork needed); a Netlify preview is posted on the PR automatically, and merging
+requires one approving review from someone with Write access. To schedule a
+post, set a future `date` and merge — it goes live on that date's morning
+build. Details: `content/blog/_authoring-guide.md` § Publishing your post.

.claude/skills/blog-post/assets/thumbnail-diagram.typ

@@ -1,9 +1,9 @@
 #import "@preview/cetz:0.3.4"
 
 #set page(
-  width: 1200pt,
-  height: 630pt,
-  margin: 50pt,
+  width: 1920pt,
+  height: 1080pt,
+  margin: 80pt,
   fill: rgb("#447099"),
 )
 
@@ -15,17 +15,17 @@
 #align(center)[
   #stack(
     dir: ltr,
-    spacing: 16pt,
-    align(horizon)[#image("quarto-logo-trademark-light.svg", height: 90pt)],
-    align(horizon)[#text(baseline: -8pt, size: 90pt, weight: "bold")[2]],
+    spacing: 26pt,
+    align(horizon)[#image("quarto-logo-trademark-light.svg", height: 144pt)],
+    align(horizon)[#text(baseline: -13pt, size: 144pt, weight: "bold")[2]],
   )
 
-  #v(10pt)
-  #text(size: 56pt, weight: "bold")[Replace this title]
+  #v(16pt)
+  #text(size: 90pt, weight: "bold")[Replace this title]
 
-  #v(10pt)
+  #v(16pt)
 
-  #cetz.canvas(length: 45pt, {
+  #cetz.canvas(length: 72pt, {
     import cetz.draw: *
 
     // Ellipse node — white fill, dark blue label.
@@ -38,12 +38,12 @@
         stroke: white,
         name: name,
       )
-      content((x, y), text(fill: rgb("#1f3a52"), weight: "bold", size: 20pt)[#label])
+      content((x, y), text(fill: rgb("#1f3a52"), weight: "bold", size: 32pt)[#label])
     }
 
     // Edge — white line connecting two named nodes.
     let edge(a, b) = {
-      line(a, b, stroke: (paint: white, thickness: 1.5pt))
+      line(a, b, stroke: (paint: white, thickness: 2.5pt))
     }
 
     // Replace the placeholder graph below with your own nodes + edges.

.claude/skills/blog-post/assets/thumbnail-text.typ

@@ -1,7 +1,7 @@
 #set page(
-  width: 1200pt,
-  height: 630pt,
-  margin: 50pt,
+  width: 1920pt,
+  height: 1080pt,
+  margin: 80pt,
   fill: rgb("#447099"),
 )
 
@@ -13,14 +13,14 @@
 #align(center + horizon)[
   #stack(
     dir: ltr,
-    spacing: 16pt,
-    align(horizon)[#image("quarto-logo-trademark-light.svg", height: 90pt)],
-    align(horizon)[#text(baseline: -8pt, size: 90pt, weight: "bold")[2]],
+    spacing: 26pt,
+    align(horizon)[#image("quarto-logo-trademark-light.svg", height: 144pt)],
+    align(horizon)[#text(baseline: -13pt, size: 144pt, weight: "bold")[2]],
   )
 
-  #v(20pt)
-  #text(size: 56pt, weight: "bold")[Replace this title]
+  #v(32pt)
+  #text(size: 90pt, weight: "bold")[Replace this title]
 
-  #v(10pt)
-  #text(size: 32pt)[Replace this subtitle (optional)]
+  #v(16pt)
+  #text(size: 52pt)[Replace this subtitle (optional)]
 ]