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=1|toDepth=2|id=toc} -->

Brief introduction explaining what this page covers.


Content organized logically...


More content...


- [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.

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=1|toDepth=2|id=toc} -->

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

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 ## 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^[3] 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^[4].

Tables

Use Markdown tables for structured data:

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

Notes and Warnings

Use blockquotes for callouts:

> **Note**: This requires version 2.0 or later.

> **Warning**: This action cannot be undone.

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^[5]: Show alternatives (e.g., Maven/Gradle)
• Accordion^[6]: Collapse optional details
• Collapse^[7]: 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^[3] - Format code blocks
• Images^[4] - Add screenshots
• UI Components^[8] - Add tabs and accordions
• Doxia Features^[9] - Advanced macros