--- title: Write description: Write clear, scannable MDX pages with structure, links, and media, then verify in preview. --- **Before you begin** - A [docs.page](https://docs.page) project with `docs.json` at the repository root and page files under `docs/` - Basic [Markdown familiarity](https://docs.github.com/en/get-started/writing-on-github/getting-started-with-writing-and-formatting-on-github/basic-writing-and-formatting-syntax): headings, lists, links, and fenced code blocks --- ## Write a new page Each page is a `.mdx` or `.md` file under `docs/`. Work through these steps in order: 1. **Choose a URL path:** add `docs/{path}.mdx` (or `.md`). The path without the extension becomes the URL. 2. **Declare title and description:** set `title` and `description` in YAML frontmatter at the top of the file. See [Frontmatter](#frontmatter). 3. **Make the page scannable:** structure the body with `##` headings and short paragraphs. See [Page structure and prose](#page-structure-and-prose). 4. **Help readers follow along:** add root-relative links, fenced code blocks, and images where they clarify the task. See [Links and assets](#links-and-assets). 5. **Expose the page to readers:** add it to the sidebar in [Organize](/authoring/organize), then confirm in [Preview](/authoring/preview). ## Page structure and prose Structure the body with `##` headings. The **On this page** [table of contents](/features/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. ### Frontmatter Start each page with YAML frontmatter between `---` delimiters: ```yaml --- 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](/reference/page-frontmatter). ### Where pages live 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](/authoring/redirects) when you move a published URL. ## Links and assets **Internal links:** use root-relative paths with no domain and no `.mdx` extension: ```mdx 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](/components/code-group) or [tabs](/components/tabs). See [Code blocks](/components/code-blocks) for titles and diff markers. **Images:** commit under `docs/` and reference with a leading slash (`/assets/dashboard.png`). Use [``](/components/image) when you need captions, light/dark variants, zoom behavior, or sizing, see `content.zoomImages` in [docs.json](/reference/docs-json). **Video and embeds:** [``](/components/youtube), [``](/components/vimeo), [`