# Configuration

> Configure VaraPress metadata, theme options, syntax highlighting, and page defaults.

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

VaraPress uses standard Zola configuration plus a small set of theme-specific options under `[extra]`. Keep configuration explicit and boring: site metadata in `zola.toml`, content structure in `content/`, and theme customizations in `[extra]`.

## Minimal Configuration

Start with the project metadata and theme setting:

```toml
title = "My Project"
description = "A brief description of your project"
base_url = "https://example.com"
theme = "varapress"

compile_sass = false

# Your other config options..
```

`compile_sass = false` is intentional. VaraPress uses TailwindCSS and compiled CSS assets, not Sass.

## Page Defaults

VaraPress is designed around three page surfaces:

| Surface             | Template       | Use it for                                         |
| ------------------- | -------------- | -------------------------------------------------- |
| Site index          | `landing.html` | The home page at `content/_index.md`               |
| Regular content     | `blog.html`    | Standard pages and future article/blog surfaces    |
| Documentation pages | `docs.html`    | Structured docs with sidebar and table of contents |

The site index uses `landing.html` by default through `templates/index.html`; you do not need to set it on `content/_index.md`. Treat landing pages as a blank canvas composed from shortcodes.

All other pages use `blog.html` by default for convenience. Override `template = "..."` in front matter whenever a page or section needs a different shell, for example `template = "docs.html"` for documentation content or `template = "blog.html"` for blog content.

## Theme Options

Add theme-specific values under `[extra]`:

```toml
[extra]
varapress_logo_light = "/brand/logo-black.svg"
varapress_logo_dark = "/brand/logo-white.svg"
varapress_favicon = "/favicon.svg"
varapress_show_title = true
varapress_github_repo = "owner/repo"
varapress_sidebar_links = [
  { text = "API Reference", link = "/api/" },
  { text = "Community", link = "https://example.com/community", new_tab = true },
]
```

If these values are omitted, VaraPress falls back to the official Varavel brand assets.

| Option                    | Default                     | Purpose                                                                                         |
| ------------------------- | --------------------------- | ----------------------------------------------------------------------------------------------- |
| `varapress_favicon`       | Official Varavel avatar     | Browser tab favicon URL or site-relative path.                                                  |
| `varapress_logo_light`    | Official black Varavel logo | Header logo shown while the resolved theme is light.                                            |
| `varapress_logo_dark`     | Official white Varavel logo | Header logo shown while the resolved theme is dark.                                             |
| `varapress_show_title`    | `true`                      | Shows the site title next to the docs header logo. Set `false` for logo-only headers.           |
| `varapress_github_repo`   | `"varavelio/varapress"`     | Repository used by the docs header GitHub button. Set `""` to hide it.                          |
| `varapress_sidebar_links` | `[]`                        | Flat list of extra docs sidebar links rendered after content links and before the Agents group. |

Each `varapress_sidebar_links` item accepts `text`, `link`, and optional `new_tab`. `new_tab` defaults to `false`; when set to `true`, the link opens in a new tab with `rel="noopener noreferrer"`.

## Syntax Highlighting

VaraPress includes the VDL grammar and is designed for GitHub-style dark code theme. Configure highlighting in `zola.toml`:

```toml
[markdown.highlighting]
theme = "github-dark"
extra_grammars = ["themes/varapress/grammars/vdl.json"]
```

If your site is the theme repository itself, paths may differ because the grammar lives at the repository root.

## LLM-Ready Builds

VaraPress ships a Node.js script that can run a full Zola build and then generate LLM-readable files. Authors do not need to install frontend packages or Node dependencies in their site; they only need Node.js for the script and Zola for the site build.

Run it from the root of a project that uses the theme:

```bash
# See all options
node themes/varapress/llms.mjs --help

# Run this instead of zola build
node themes/varapress/llms.mjs
```

This produces:

- `llms.txt` at the site root and inside every section.
- `llms-full.txt` at the site root with all included Markdown content concatenated.
- `index.md` files next to every included section and page URL.

Use a normal Zola build when you do not need these files:

```bash
zola build
```

Control the generated files with `[extra]`:

```toml
[extra]
varapress_llms = true
varapress_llms_full = true
varapress_llms_description_chars = 100
```

When either LLM option is enabled, documentation pages expose a compact Markdown menu for copying, opening, or downloading the generated `index.md`. The docs sidebar also adds an `Agents` section with links to the generated `llms.txt` and/or `llms-full.txt` files that are active for the site.

Exclude a single page or section from the generated LLM files with front matter:

```toml
+++
title = "Internal Notes"

[extra]
varapress_llms = false
+++
```

If you already have a built `public/` directory and only want to regenerate the LLM files, skip the Zola step:

```bash
node themes/varapress/llms.mjs --skip-zola
```

## Content Structure

A practical site usually starts with this shape:

```txt
content/
  _index.md
  docs/
    _index.md
    getting-started/
      _index.md
      installation.md
```

Use documentation pages for long-lived product docs and landing pages for marketing surfaces. Shortcodes are available in both contexts; the complete reference lives at [Shortcodes](/docs/shortcodes/).

## Next Steps

Continue with [Documentation Pages](/docs/getting-started/documentation/) to create docs content, then [Landing Pages](/docs/getting-started/landing-pages/) to compose marketing pages.