blog-post

Writing a Semiotic blog post

This skill writes one entry for the Semiotic blog. The blog lives at /blog/; entries live at /blog/<slug>/. Three story shapes are supported — pick the one that matches what's being written:

1. Chart explainer — single chart, "what / why / when / wiring".
2. Release summary — what's new in a version, ordered by impact.
3. Narrative / case study — comparative posts ("X vs Y"), walkthroughs, recreations of historical visualizations.

Every entry follows the same structure regardless of shape. The why-care section is non-negotiable: the post has to give the reader a reason to read it that lands even if they're not currently using Semiotic. The blog isn't reference docs; it's a publication that happens to be hosted on the docs site.

Before writing anything

Ask the user for the author byline unless they've already given one. Don't assume "Elijah Meeks" by default — many entries will be co-authored or attributed to "Semiotic Team" for releases. One short question, then proceed.

File structure

For a new entry with slug <slug>:

1. Body component — docs/src/blog/entries/<slug>.jsx. Default export is { slug, title, subtitle, author, date, tags, excerpt, component, ogChart? }. The component is a React function returning JSX (the entry's body — no header, no chrome, the BlogEntryView wraps it).
2. Register in registry — docs/src/blog/entries.js imports the new file and adds it to blogEntries.
3. Register in metadata mirror — docs/src/blog/entries-meta.js gets the same metadata object (without component, without the React imports). This mirror is read by the OG-card generator and the prerender script, both of which run under plain Node and can't load JSX.

Both registry files must stay in sync. The OG-card generator and prerender script read entries-meta.js; the React app reads entries.js.

Required fields

{
  slug: "kebab-case-route",
  title: "Title-Case Headline",
  subtitle: "One or two sentences orienting the reader.",
  author: "Author Name",                  // ASK THE USER if unspecified
  date: "YYYY-MM-DD",                     // ISO; controls sort order
  tags: ["release"] | ["chart-explainer", "xy"] | ...,
  excerpt: "2–3 sentence preview shown on the index card.",
  component: Body,                        // function returning JSX
  ogChart: { component: "DifferenceChart" }, // optional, see OG step
}