Writing an editorial

How to add an editorial or a material: file locations, frontmatter fields, MDX and math, and where the visualization goes.

Editorials and materials are plain MDX files committed to the repository. Content has no database. Files under content/ are compiled at build time.

Where files go

Editorials: content/editorials/<subject>/<slug>.mdx
Materials: content/materials/<subject>/<slug>.mdx

<subject> is informatics, physics or astronomy. The URL's slug comes from the filename and not the title, so renaming a title never changes a published URL.

Editorial frontmatter

Field	Notes
`title`	Up to 120 characters.
`subject`	Must match the folder the file is in.
`hook`	Up to 280 characters. One sentence that makes someone want to read on.
`tags`	Short, lowercase labels.
`principle`	The general idea this editorial teaches. Free text on purpose.
`errorType`	Optional. The specific mistake it corrects. Free text.
`vizConfig`	Which visualization engine to use, and its configuration.
`publishedAt`	An ISO date, 2020 or later. Earlier dates are rejected as placeholder data.
`author`	Who wrote it.
`syllabusTopic`	Optional. A topic id from the syllabus for the same subject.

The body is everything after the frontmatter, written in Markdown/MDX.

Math

Use $...$ for inline math and $$...$$ for display math. Both compile to static KaTeX HTML at build time.

Placing the visualization

Put <Interactive /> on its own line where the visualization should appear, usually between the idea and the full proof. If you forget it, the visualization still renders, just after the hook with a small notice, so an editorial never ships without one.

Choosing a visualization engine

Set vizConfig.discriminant to one of graph-array-stepper, trajectory-sandbox, orbital-sandbox, composed-scene or programmable-scene. The first three are configured in frontmatter. The last two are built visually in the scene builder. Copy from these real examples:

content/editorials/informatics/binary-search-on-answer.mdx for graph-array-stepper
content/editorials/physics/projectile-range-symmetry.mdx for trajectory-sandbox
content/editorials/astronomy/eccentric-transit-duration.mdx for orbital-sandbox

Materials

A material is shorter and unsigned. It has a title, subject, topic (a syllabus topic id), summary (up to 280 characters) and a body. There is at most one material per topic, and no visualization is required.

Checking your work

Run pnpm generate to validate frontmatter and pnpm test to check that every material and editorial points at a real syllabus topic. Never rename a syllabus topic's id. Change its name instead.

Editing in the browser

You can also write and edit content in the browser. See Editing with Keystatic.