Authoring with the CMS

This page documents the Keystatic browser editor. Open /keystatic while the dev server is running, edit a page under Documentation, change the text or metadata, and save. In local mode, Keystatic writes MDX and uploaded images into the working copy.

What writers can do here

• Rich prose: headings, bold, lists, links, tables, code blocks, and images.
• Structured metadata through friendly form fields: title, summary, software generation, machine types, visibility, and publication state.
• Visibility defaults to private for new pages — publishing is a deliberate choice, never an accident.
• Insertable rich-editor controls: warnings, images with draggable numbered callouts, diagrams, shared-content includes, settings/API references, applicability sections, hardware revision and machine-type sections, troubleshooting, compatibility matrices, parameters, and download links.

Image workflow

In an image block, upload a file or search the saved-image library to reuse an existing image. New images are stored below public/images/uploads/<document-path>/ with a lowercase kebab-case name. Save, reopen the document, and use Search saved images to find and insert it again. On the production CMS the saved-image list is read live from the branch you have selected, so an image added to that branch appears after Refresh library without waiting for a deployment; a different branch shows its own images. If GitHub cannot be reached or you are not signed in, the block says so and keeps the image you already chose; it never falls back to the older deployed list. If a name already exists for that document, the next upload receives a suffix; it will not silently replace the existing asset.

Files in public/ are publicly accessible. Do not upload private or restricted material. The CMS does not upload attachments or video: use Cloudflare R2 and a Download link for installers, archives, large PDFs, and video. In the Download block, enter the complete https:// URL of the file. A bare R2 object key is not accepted (no R2 download base is configured, and a key would become a broken link on this site): the editor refuses to save it and the build fails on it. Private files need a protected delivery route; a private page does not make a public asset private.

Diagrams and code-owned content

Use the Diagram (editable SVG) block to create or edit a drawing in diagrams.net. The CMS saves a visible SVG with the editable draw.io model embedded. Save the document after the diagram so the block stores its generated path. Keep the SVG and its embedded model together; do not replace it with a flattened image.

The editor provides forms for the common technical components, but component implementation, release registries, content schemas, and platform configuration remain code-owned. Add a new component to both the Keystatic editor schema and the MDX auto-import map before authors use it.

A page is editable in the CMS tree when its body uses only components the editor knows. A block of plain import lines at the top of the page is fine: the editor shows it as “Page imports (kept as written)” and saves it unchanged. A page stays code-owned (no edit link; hover the label to see why) if it uses a component the editor does not support, has an export or other code at the top, or has an import anywhere after the first line of content.

Also editable in the CMS

The Release registry collection in Keystatic edits the version data that drives the version selector and applicability — structured fields, no Markdown, the CMS’s strongest use case.