# Documentation

> Create structured documentation pages with the VaraPress docs layout.

Canonical HTML: https://press.varavel.com/docs/getting-started/documentation/
Markdown: https://press.varavel.com/docs/getting-started/documentation/index.md

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:

```toml
+++
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`:

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

Then create subsections for groups of related pages:

```toml
+++
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.

## Configure Sidebar Groups

Each subsection renders as a collapsible sidebar group. Groups are open by default, which keeps first-time navigation straightforward.

To make a section closed by default, set `varapress_sidebar_open = false` under `[extra]` in that section's `_index.md`:

```toml
+++
title = "Reference"
weight = 3

[extra]
varapress_sidebar_open = false
+++
```

This only controls the initial state. If the reader has already opened or closed the group, their saved preference takes precedence. If the current page is inside the group, VaraPress opens it automatically so the active page is never hidden.

## Write Pages for Navigation

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

```toml
+++
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:

````markdown
```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](/docs/shortcodes/) reference when you need exact parameters, examples, and live previews.