Before you begin
- A docs.page project with
docs.jsonat the repository root and page files underdocs/ - Basic Markdown familiarity: headings, lists, links, and fenced code blocks
Each page is a .mdx or .md file under docs/. Work through these steps in order:
- Choose a URL path: add
docs/{path}.mdx(or.md). The path without the extension becomes the URL. - Declare title and description: set
titleanddescriptionin YAML frontmatter at the top of the file. See Frontmatter. - Make the page scannable: structure the body with
##headings and short paragraphs. See Page structure and prose. - Help readers follow along: add root-relative links, fenced code blocks, and images where they clarify the task. See Links and assets.
- Expose the page to readers: add it to the sidebar in Organize, then confirm in Preview.
Structure the body with ## headings. The On this page table of contents derives from Markdown heading levels, keep one main idea per section and nest subsections one level deeper. Set content.headerDepth in docs.json when you need deeper entries in that list.
Write so a busy reader can skim: state the outcome first, keep paragraphs short, use imperative voice (Run, Set, Open), and bold UI labels while putting commands and paths in backticks.
Match page shape to what the reader needs:
| Reader goal | Page shape | Link out for |
|---|---|---|
| Learn by doing | Step-by-step walkthrough | Field lookup, API tables |
| Complete one task | Focused how-to with a verify step | Architecture essays |
| Look up a value | Reference tables or property rows | Tutorial narrative |
| Understand why | Explanation with a mental model | Numbered setup steps |
Stay in one mode per page. Link to Reference and Components instead of mixing exhaustive lists into prose.
Start each page with YAML frontmatter between --- delimiters:
---
title: Install the CLI
description: Install the docs.page CLI on macOS, Linux, or Windows.
---At minimum, set title and description. Additional keys control redirects, previous/next links, hero images, and indexing, see Page frontmatter.
Store every page under docs/. The file path (without the extension) becomes the URL path:
| File | URL |
|---|---|
docs/index.mdx | / |
docs/getting-started.mdx | /getting-started |
docs/api/authentication.mdx | /api/authentication |
Create a new file when you add a topic. Rename the file and add a redirect when you move a published URL.
Internal links: use root-relative paths with no domain and no .mdx extension:
See [Preview](/authoring/preview) before you open a pull request.Code examples: wrap snippets in fenced blocks with a language tag (bash, json, tsx). For multiple equivalent snippets, use a code group or tabs. See Code blocks for titles and diff markers.
Images: commit under docs/ and reference with a leading slash (/assets/dashboard.png). Use <Image> when you need captions, light/dark variants, zoom behavior, or sizing, see content.zoomImages in docs.json.
Video and embeds: <YouTube>, <Vimeo>, <Video> (public https URL only), or <Tweet>.
Plain Markdown covers most writing. docs.page also ships built-in MDX components with no imports and no extra packages.
| Reader need | Start with |
|---|---|
| Body copy and lists | Plain Markdown |
| One highlighted snippet | Fenced code block |
| Platform or language variants | <Tabs> or <CodeGroup> |
| Prerequisites, cautions, tips | <Info>, <Warning>, or siblings |
| Collapsible sections | <Accordion> and <AccordionGroup> |
| Numbered setup flow | <Steps> |
| Custom heading anchors | Markdown ## headings (recommended) or <Heading> |
| Inline icons | <Icon> |
| API or config field rows | <Property> on Reference pages |
| Section landing links | <Card> and <CardGroup> |
Author components with PascalCase JSX tags. Unknown names show an inline error in preview, match the tag to the Components reference. For props and examples, use the Components tab; for how the library fits the product, see Features → Components.
After you edit, use Preview to confirm layout, run docs check for broken links, then continue to Publish.
| Symptom | Likely cause | Fix |
|---|---|---|
| Page returns 404 in preview | File is outside docs/ or the path does not match the URL you opened | Keep pages under docs/ and match the file path to the URL (no extension) |
| Internal link goes nowhere | Link includes a domain, file extension, or wrong path | Use root-relative paths like /authoring/preview. No https:// and no .mdx. |
| Image does not render | Asset path is wrong or the file is not committed | Store images under docs/ and reference them with a leading slash, e.g. /assets/screenshot.png |
| Inline component error in preview | Misspelled or unsupported component name | Match the tag to the Components reference. Names are PascalCase. |
{{ variable }} shows literally | Substitution used in frontmatter or the path is undefined | Use variables in the MDX body only; define values in docs.json. See Global variables or docs.json: variables. |