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 page's address follows where it sits in your navigation: its tab, its folders, then its own name. See page addresses.
Slugs
Slugs are lowercase, alphanumeric, and hyphenated. They're unique within a group, so the same slug can appear under two different groups.
When you change a page's address, leave Keep the old address working on. Anyone following an old link is then redirected. Turn it off and those links stop working. See renaming and URLs.
Writing well
The components exist to structure a page, not to decorate it. A few rules that hold up:
The two editors
Both edit the same page, and you can switch at any time.
| Mode | Best for |
|---|---|
| Visual | Writing. Type / for callouts, cards, images, videos and steps |
| MDX | Exact control. Use the toolbar or the Insert menu for components |
You can also write pages outside the dashboard: in the Files panel, in GitHub, or by importing Markdown files from disk.
Markdown support
GitHub-flavored Markdown: tables, strikethrough, task lists and autolinks. Headings become anchors automatically, and they build the On this page rail.
Write code with a fenced block and a language, and it gets highlighting and a copy button. See code blocks.
Beyond Markdown, use components.
Linking between pages
Use the page's path on your site. In a link's dialog in the visual editor, you can pick the page instead of typing it.
See the [quickstart](/guides/get-started/quickstart).A link can point at a heading on a page, by adding the heading's text in lowercase with dashes: /guides/get-started/quickstart#make-a-request.
Page metadata
A page's title, icon, badge, lifecycle and search metadata are its page settings. In the Files panel and in GitHub, they're the file's frontmatter:
---
title: Quickstart
description: Make your first request in five minutes.
icon: rocket
badge: New
badgeColor: green
---
Your page starts here.HTML in pages
Raw HTML works, but it's sanitized when rendered, so scripts and event handlers are removed. For behavior, use custom code. For a reusable block, use a custom component.
From the CLI
Guides can be listed, read and published with octri docs guides, and generated pages with octri docs pages.