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 type 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 Markdown/Astro workflows, applying the reference information-typing principle without DITA XML schemas or DTD 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.