--- title: Documentation content templates description: Copy-ready MDX starting points for how-to guides, tutorials, explanations and reference pages in a Reed project. --- These templates are starting points, one for each of the four [content types](/docs/guides/content-types). They are written for Reed: frontmatter carries only `title` and `description`, and every component comes from the [fixed catalog](/docs/authoring/components). To use one: 1. Copy the template that matches the page's type into a new `.mdx` file. 2. Replace every bracketed placeholder with real content. 3. Add or reorder sections where your subject needs it. 4. Delete every section that does not apply. An empty "Troubleshooting" heading is worse than none. The templates use components sparingly on purpose. Most of a good page is headings, prose, lists and fenced code, which read equally well in the rendered page, in a diff and in the page's markdown mirror. Each component below is there because it does something markdown cannot. Three rules hold for every template: - **No H1 in the body.** The `title` becomes the H1. Headings start at `##` and never skip a level, or `reed check` reports `DS-A02`. - **Fences stay at the top level.** Keep fenced code out of `Step`, `Tab`, `Card` and `Accordion`. A nested fence only parses when it and the tags around it sit on their own lines, with blank lines between, so the top level is the safer habit. See [MDX pitfalls](/docs/authoring/mdx-pitfalls). - **Links carry the base.** Reed does not rewrite links in prose. On a site with `base: "/docs"`, a link to another page is written `/docs/`, in markdown and in every `href`. ## How-to guide template Use a how-to guide when the reader already knows the product and needs to finish one specific task. It goes straight to the solution. ````mdx --- title: "[Verb] [object], e.g. Rotate an API key" description: "[Do the task] to [reach the outcome]." --- One or two sentences on what this guide gets done, and when you would need it. ## Prerequisites List only what the task truly requires: - [Setup or configuration that must already exist] - [Permissions the reader needs] - [Related features that must be configured first] ## [Name the task as an action] 1. Open [location] and go to [specific place]. 2. Select [button or option]. 3. Enter [required value]. 4. Select [confirmation button]. Then run the command, or edit the file, that completes the change: ```bash [command the reader can copy and adapt] ``` [The one mistake readers most often make here, and how to avoid it.] ## Verify the result [Only when success is not obvious: what the reader should see, and where.] ## Troubleshooting - **[Symptom as the reader would describe it]:** [Cause and fix.] - **[Another symptom]:** [Cause and fix.] ## Related tasks - [Title of a related how-to guide] — [when to read it instead] - [Title of the next logical task] ```` The list keeps the steps and the fence stays below it. If every list item ended up holding its own code block, `reed check` would suggest `Steps` with `DS-D04`. Since these templates keep fences out of `Step`, the better fix is usually one `##` heading per step. ## Tutorial template Use a tutorial to teach a newcomer through hands-on practice. It walks through one complete, working example with a clear outcome. ````mdx --- title: "[Build or do] [specific outcome]" description: "Learn to [outcome] by [method], step by step." --- Say what the reader will have built by the end, what they will be able to do next, and roughly how long it takes. ## Before you start - [Knowledge the reader needs] - [Tools, accounts or access] ## 1. [First action] [Exactly what to do. No alternatives.] ```bash [first command] ``` [What that just did, in one or two sentences, and why it matters.] ## 2. [Second action] [The next step, building on the first.] ```bash [second command] ``` [A milestone the reader can see: "Your site now builds without errors."] ## 3. [Third action] [Keep each step a concrete action, not theory. Make the choice for the reader.] ## Next steps You [one sentence summarizing what was built]. From here: - [A how-to guide for the most common next task] - [An explanation page for readers who want to know how it works] - [The reference page they will come back to] ```` Numbered `##` headings do the job `Steps` would do here, and they keep each command in a top-level fence. The stages also appear in the table of contents. Reed's own [Quickstart](/docs/quickstart) uses this shape. Use one `Check` at a real milestone, not after every step. Three or more callouts in a row draw a `DS-D06` suggestion, and a page full of them has no emphasis left. ## Explanation template Use an explanation when the reader needs to understand a concept, a design decision or how a complex feature works. It builds understanding instead of giving instructions. ```mdx --- title: "How [concept] works" description: "What [concept] is, why it exists, and where it fits in [product]." --- Open with what this page explains and why a reader would care. Define the concept in plain language: what it is, what it does, why it exists. Compare it to something the reader already knows when a comparison genuinely helps. ## How [concept] works Describe the mechanism, the architecture or the process, one idea per section. ![[Describe the diagram for a reader who cannot see it]](https://example.com/diagram.png) ## Why [the design decision] Say why it works this way. Name the tradeoffs, the alternatives that were considered, and the constraints that ruled them out. ## When to use [concept] - **[Situation]:** why this is the right approach there. - **[Another situation]:** why it fits. - **Not for [situation]:** what to use instead. ## How it relates to [neighboring feature] Connect the concept to the rest of the system and to the reader's workflow. ## Common misconceptions Correct the misunderstandings you actually hear, one at a time. ## Further reading - [A how-to guide that puts this concept to work] - [The reference page for its settings] ``` Replace the image URL with your own. The alt text is not optional: an image without it is `DS-A01`. Write alt text that says what the diagram shows, not "diagram". ## Reference template Use reference when the reader needs to look up exact details. It favors accuracy, consistency and scannability over everything else. ````mdx --- title: "[Feature or API name] reference" description: "Every [parameter, option and field] of [feature or API], with types and defaults." --- One sentence on what this feature or endpoint does. ## Parameters [What it controls. One or two sentences.] [What it controls, and what happens at the default.] [What turning it on changes.] [What each option does.] ## Response [What the field contains.] [What the field contains, and when it is absent.] ```json { "[field]": "[value]", "[field]": 123 } ``` ## Examples ### Minimal request ```bash [the smallest call that works] ``` ### Full request ```bash [a call that sets most of the parameters above] ``` ## Limits - [Rate limits, size limits, maximum values] - [Edge cases and what happens at them] ## Related references - [Title of a related reference page] ```` `ParamField` takes the parameter's name in `name`, and `ResponseField` requires both `name` and `type`. Use `in` on a `ParamField` to say where a parameter goes — `query`, `path`, `header`, `body` or `cookie`. The full prop list is in [API reference components](/docs/reference/components/api). The examples sit under their own headings, so their fences are not adjacent. If you show one call in several languages, put the fences in a `CodeGroup` and title each with its language. Adjacent fences in different languages outside one draw a `DS-D03` suggestion to use `CodeGroup` — see [Format code](/docs/authoring/formatting/code). If you document an HTTP API from an OpenAPI spec, you may not need this template at all: Reed renders endpoint pages from the spec with its own generated layout. `ParamField` and `ResponseField` are for hand-written API pages like this one. ## Related pages Decide which template a page needs. The sentence-level rules the templates assume. When a component earns its place, and when it does not. Frontmatter, page ids and links.