Writing a Documentation Page

Page Template

A well-structured page follows this pattern:

keywords: relevant, search, terms
description: A one-sentence summary for search engines.

# Page Title

<!-- MACRO{toc|fromDepth=2|toDepth=3|id=toc} -->

Brief introduction explaining what this page covers.

## First Section

Content organized logically...

## Second Section

More content...

## See Also

- [Related Page](related.html)

Front Matter

Start every page with metadata headers:

keywords: api, configuration, setup
description: How to configure the API client.

See Front Matter Headers^[1] for all options, including configuration settings^[2] that let you enable or disable features on individual pages.

Page Title

Use a single # heading as your page title:

# Configuring the API Client

This becomes:

• The page header
• The browser tab title (with project name)
• The search index entry

Table of Contents

For longer pages, add the ToC macro right after the title:

# Page Title

<!-- MACRO{toc|fromDepth=2|toDepth=3|id=toc} -->

The ToC floats on the right (desktop) or displays inline (mobile). See Table of Contents^[3].

Introduction

Write 1-3 sentences explaining what the reader will learn. This helps readers confirm they're on the right page.

Sections

Organize content with ## (level 2) headings:

## Installation

Steps to install...

## Configuration

How to configure...

## Usage

How to use...

Tips:

• Keep sections focused on one topic
• Use consistent heading levels (## for main sections, ### for subsections)
• Each heading becomes a linkable anchor

Code Examples

Include practical code examples:

```xml
<dependency>
  <groupId>com.example</groupId>
  <artifactId>my-library</artifactId>
  <version>1.0.0</version>
</dependency>
```

See Code Highlighting^[4] for supported languages.

Images

Add screenshots and diagrams:

![Configuration dialog](images/config-dialog.png)

Images are automatically:

• Displayed as clickable thumbnails
• Converted to WebP for performance

Use ![inline](image.png) for small icons. See Images^[5].

Tables

Use Markdown tables for structured data:

| Parameter | Type | Description              |
| --------- | ---- | ------------------------ |
| `timeout` | int  | Request timeout in ms    |
| `retries` | int  | Number of retry attempts |

Callouts (Notes and Warnings)

Use callout syntax^[6] for important information:

> [!NOTE]
> This requires version 2.0 or later.

> [!WARNING]
> This action cannot be undone.

> [!TIP]
> Use keyboard shortcuts for faster navigation.

See UI Components^[6] for all callout types (NOTE, TIP, IMPORTANT, WARNING, CAUTION).

Cross-References

Link to related pages:

See [Configuration Reference](settings.html) for details.

For external links:

See the [Maven documentation](https://maven.apache.org).

Interactive Elements

For complex content, consider:

• Tabs^[7]: Show alternatives (e.g., Maven/Gradle)
• Accordion^[8]: Collapse optional details
• Collapse^[9]: Hide advanced content

Checklist

Before publishing, verify:

• [ ] Front matter (keywords, description) is set
• [ ] Title is clear and descriptive
• [ ] Introduction explains the page purpose
• [ ] Code examples are tested and correct
• [ ] Images have alt text
• [ ] Links work correctly
• [ ] ToC is included for long pages

Next Steps

• Code Highlighting^[4] - Format code blocks
• Images^[5] - Add screenshots
• UI Components^[10] - Add tabs and accordions
• Doxia Features^[11] - Advanced macros
• Configuration Reference^[12] - All customization options