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
}

Tags vocabulary

Pick freely from:

• Shape: release, chart-explainer, case-study, tutorial
• Family: xy, network, geo, ordinal, realtime, hierarchy

Multi-tag is fine and encouraged. Don't invent new top-level tags without checking the existing taxonomy in entries.js.

The skeleton — applies to all shapes

Every entry MUST have these sections (with the names below as h2 headings, except the intro):

1. Opening paragraph (no heading) — one paragraph that orients the reader. State the chart / topic in concrete terms. Don't start with "In this post we will…". Start with the thing.
2. Why this exists / why care — answer "why should I care about this if I'm not currently using Semiotic?". Even chart-explainer posts need this: tell the data-viz audience what makes the chart-type interesting, then connect it to Semiotic's implementation.
3. The thing itself — live demo, or release-note bullets, or the comparative pair. This is the meat. Show, don't tell.
4. How to read / how it works — once the reader has seen the thing, walk them through how to read the visual encoding (for chart posts) or where to look for the API change (for releases).
5. When to reach for it / when not — guidance. Pair every "use it for X" with "don't use it for Y, use Z instead". This is the section that earns the reader's trust.
6. Wiring it up — minimal code snippet showing the prop shape. For releases, link to the changelog and migration notes.
7. Related — link to neighbor charts, related features, and the full reference page.

The Why and the When-to-reach sections are what distinguish a Semiotic blog post from the reference docs at /charts/<name>. The reference doc tells you what's there; the blog post tells you when you'd care.

Story-shape specifics

Chart explainer

• Title format: <ChartName>, explained.
• Opening: one-sentence elevator pitch. ("DifferenceChart is the chart you reach for when the story is the gap between two series, not either series on its own.")
• Why-care section: cover the general data-viz problem the chart solves, NOT the Semiotic-specific API. The same audience that reads HN data-viz threads should find this useful. Then add a paragraph relating it to Semiotic's implementation (e.g. "in Semiotic this is wired through…").
• Live demo: one self-contained chart with inline synthetic data. Keep the data small enough that the reader can imagine the underlying rows (5–15 rows is the sweet spot).
• When-to-reach section: list 3–5 cases for it, then 3 cases against it pointing to the right alternative chart.
• Wiring section: ≤15 lines of code. Just the minimum props.
• Streaming / push mode section — REQUIRED for every chart explainer. Three pieces:
  1. A live push demo using BlogPushDemo from docs/src/blog/components/BlogPushDemo.jsx. Hand it a chartRef, the frames array (one entry per step), a pushAt(ref, row, i) callback that calls the chart's push method, and a resetAt(ref) callback that calls clear(). The demo gives the reader Play / Step / Reset controls and a step counter for free.
  2. A push-mode wiring snippet — ≤15 lines — showing the ref, the push() / update() calls relevant to the chart, and any required *IdAccessor (XY charts want pointIdAccessor; ordinal charts want dataIdAccessor; network HOCs use nodeIDAccessor / edgeIdAccessor).
  3. A "why push helps here" paragraph specific to this chart's nature. Generic boilerplate is worthless; the story has to land on a property the reader can map back to their own code. Examples from the seeded entries:
     • DifferenceChart: segment recomputation is cheap and in-buffer; setting data on every tick triggers React reconciliation that push skips.
     • QuadrantChart: update(id, fn) mutates one point without re-keying the rest; preserves hover and in-flight tooltips.
     • FunnelChart: bar-and-trapezoid size deltas are animated; data resets lose the animation.

  Charts that explicitly DO NOT support push (hierarchy HOCs: OrbitDiagram, TreeDiagram, Treemap, CirclePack) get a different streaming section that explains WHY push doesn't apply (the layout reads the full tree, not incremental appends) and the pattern that does work (set the data prop to a new tree; the chart's transitions still ease cleanly between trees).

• Tags: ["chart-explainer", "<family>"].

Push-mode demo skeleton

Inside the entry file, alongside the static Body function, declare a PushDemo function that wires BlogPushDemo:

function PushDemo() {
  const chartRef = useRef(null)
  return (
    <div style={chartFrame}>
      <ThemeProvider theme="carbon-dark">
        <BlogPushDemo
          chartRef={chartRef}
          frames={DEMO_DATA}                 // array, one item per step
          pushAt={(ref, row) => ref?.push?.(row)}
          resetAt={(ref) => ref?.clear?.()}
        >
          <YourChart
            ref={chartRef}
            // ...the same props as the static demo, MINUS `data`
            pointIdAccessor="id"             // or dataIdAccessor etc.
          />
        </BlogPushDemo>
      </ThemeProvider>
    </div>
  )
}

Then reference <PushDemo /> from inside <Body>'s streaming section. Keep the same chart frame styling as the static demo so the visual continuity between the two reads as "same chart, two flavors."