Documentation

Documentation pages are for durable product knowledge: installation guides, API notes, tutorials, architecture explanations, and reference material. VaraPress gives these pages a dedicated docs shell with sidebar navigation, table of contents, heading anchors, syntax highlighting, and theme switching.

When to Use Docs Pages

Use docs pages when the reader is trying to understand or operate the product. Good docs content is specific, linkable, and organized into sections.

Use docs.html for this surface:

+++
title = "Install My Project"
description = "Install and verify the project locally."
template = "docs.html" # Optional, this is the default
+++

Create a Docs Section

Create a section index at content/docs/_index.md:

+++
title = "Documentation"
template = "docs.html"
sort_by = "weight"
+++

Then create subsections for groups of related pages:

+++
title = "Getting Started"
template = "docs.html"
weight = 1
+++

The sidebar is generated from your Zola section tree. Use weight to control ordering and keep page titles short enough to scan.

Write Pages for Navigation

Each docs page should have a clear title, a concise description, and an explicit weight:

+++
title = "Configuration"
description = "Configure project metadata and theme options."
template = "docs.html"
weight = 2
+++

Headings inside the page become table-of-contents entries. Keep heading levels meaningful and avoid skipping from ## to #### unless the structure genuinely requires it.

Markdown and Code Blocks

Write normal Markdown. VaraPress styles rich text through the docs layout and supports highlighted code blocks:

```toml
theme = "varapress"
```

Use fenced code blocks for commands, configuration, and examples. This makes docs easier to scan and keeps long instructions copyable.

Shortcodes in Docs

Shortcodes are available inside documentation pages, use them sparingly for callouts, actions, or compact visual sections when they make the explanation clearer.

Use the Shortcodes reference when you need exact parameters, examples, and live previews.