Documentation
Writing guides
Generated reference tells readers what an endpoint does. Guides tell them why, when, and in what order. Write them in MDX, organise them into groups, and they appear in the sidebar above the generated reference.
Draft and publish
Guides use a draft model. Edits autosave to a working copy only you can see. Publishing promotes the draft to the live page and recompiles it.
Editing a guide's title or body writes to the draft, never to the live copy. Readers keep seeing the last published version until you publish. A guide that has never been published is not reachable at its public URL at all: it returns a 404.
- Write
Edits autosave to the draft. The sidebar marks a guide with unpublished changes.
- Preview
A preview renders your draft exactly as the published page will, through the same renderer.
- Publish
The draft becomes the live copy and the page goes public.
Groups
A group is a sidebar section. Groups can nest, so a large topic can have sub-sections.
A guide in a group is served at /<its group>/<slug>: two segments however deeply that group is nested, so nesting changes the sidebar, not the URL. A guide in no group is served at /<slug>, and moving it into a group later changes its URL.
Slugs
Slugs are lowercase, alphanumeric, and hyphenated. They're unique within a group, so the same slug can appear under two different groups.
The slug is the URL. Renaming one after people have linked to it produces a 404 with no redirect. Decide the slug when you create the page.
Writing well
The components exist to structure a page, not to decorate it. A few rules that hold up:
Markdown support
GitHub-flavoured markdown: tables, strikethrough, task lists, and autolinks. Headings become anchors automatically and feed the on-this-page rail.