Configuration

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:

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:

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]:

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

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:

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

# 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:

zola build

Control the generated files with [extra]:

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

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

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

Content Structure

A practical site usually starts with this shape:

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.

Next Steps

Continue with Documentation Pages to create docs content, then Landing Pages to compose marketing pages.