Template: reference article

Information type:Reference•"What are the details?"

Structured lookup data, exact syntax, parameters, and constraints

Template

This is a starting point to copy and adapt, not a worked example. For a filled-in version, see the API documentation template, which is a specialized case of this pattern. To understand how reference material relates to other documentation modes, read Information types.

Use this structure when the reader’s primary intent is lookup - they already understand what they want to achieve and need exact syntax, parameters, commands, or configuration specifications. Unlike a concept or task article, nobody reads a reference article start to finish; they scan for the one detail they need.

Keep the primary information typeInformation typingThe discipline of classifying content by its communicative purpose (concept, task, reference) rather than writing undifferentiated prose.View in glossary → clear: a reference article routinely includes concrete syntax examples to illustrate options, but multi-step procedural tutorials belong in a task article, and overarching architectural rationales belong in a concept article.

The structure below is a practical authoring template for lightweight MarkdownMarkdownA lightweight plain-text markup language in which formatting is written with simple punctuation, such as a leading # for a heading. It is easy to write and to review under version control, but has no schema to enforce structure, so docs-as-code teams rely on templates and automated checks instead. This manual is written in MDX, a Markdown variant.View in glossary →/Astro workflows, applying the reference information-typing principle without DITA XMLDITA XMLA structured, modular XML authoring architecture built around the concept/task/reference typology and content reuse via conrefs and ditamaps.View in glossary → schemas or DTDDTD (Document Type Definition)The oldest XML schema language: it declares which elements and attributes a document may contain, and in what order. DITA XML is distributed with DTDs as well as XSD schemas.View in glossary → validation:

---
title: "<Command, option, or item name>"
description: "<One sentence: what this is a reference for>"
contentType: reference
---

## Overview

<One or two sentences of context — enough for someone who lands here
from search to know they're in the right place.>

## Syntax

<The exact, literal syntax. A code block, not prose.>

## Parameters

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| `<name>` | `<type>` | Yes/No | <what it does> |

## Examples

<At least one complete, runnable example — not a fragment.>

## Limitations

<Known constraints, unsupported combinations, or edge cases. Omit if
none exist; don't invent caveats to fill the section.>

## Related references

- [<Related reference 1>](<link>)
- [<Related reference 2>](<link>)

When to skip a section

• Limitations: only if genuine ones exist.
• Parameters: if the item being documented takes no parameters, replace the table with a one-line note saying so - don’t delete the heading silently, since its absence should be obvious, not implied.
• Never skip Syntax or Examples - a reference article without a literal, copyable form isn’t doing its job.