## Documentation index This index lists every available documentation page and its Markdown source. - [Documentation](https://vara.varavel.com/docs/index.md) - [Introduction](https://vara.varavel.com/docs/introduction/index.md) - [Getting Started](https://vara.varavel.com/docs/getting-started/index.md) - [Installation](https://vara.varavel.com/docs/getting-started/installation/index.md) - [Quick Start](https://vara.varavel.com/docs/getting-started/quick-start/index.md) - [Composing a Landing Page](https://vara.varavel.com/docs/getting-started/composing-landing-page/index.md) - [Fundamentals](https://vara.varavel.com/docs/fundamentals/index.md) - [Project Structure](https://vara.varavel.com/docs/fundamentals/project-structure/index.md) - [Page Generators](https://vara.varavel.com/docs/fundamentals/page-generators/index.md) - [Site Settings](https://vara.varavel.com/docs/fundamentals/site-settings/index.md) - [Search and LLM Output](https://vara.varavel.com/docs/fundamentals/search-and-llms/index.md) - [Customization](https://vara.varavel.com/docs/fundamentals/customization/index.md) - [Functions and Filters](https://vara.varavel.com/docs/fundamentals/functions-and-filters/index.md) - [Templates](https://vara.varavel.com/docs/templates/index.md) - [vara-landing](https://vara.varavel.com/docs/templates/landing/index.md) - [vara-docs](https://vara.varavel.com/docs/templates/docs/index.md) - [vara-docs-raw](https://vara.varavel.com/docs/templates/docs-raw/index.md) - [vara-docs-search-index](https://vara.varavel.com/docs/templates/docs-search-index/index.md) - [vara-docs-llms-txt](https://vara.varavel.com/docs/templates/docs-llms-txt/index.md) - [vara-docs-llms-full-txt](https://vara.varavel.com/docs/templates/docs-llms-full-txt/index.md) - [vara-sitemap-xml](https://vara.varavel.com/docs/templates/sitemap-xml/index.md) - [vara-404](https://vara.varavel.com/docs/templates/404/index.md) - [Components](https://vara.varavel.com/docs/components/index.md) - [Alert](https://vara.varavel.com/docs/components/alert/index.md) - [Badge](https://vara.varavel.com/docs/components/badge/index.md) - [Button](https://vara.varavel.com/docs/components/button/index.md) - [Container](https://vara.varavel.com/docs/components/container/index.md) - [Icon](https://vara.varavel.com/docs/components/icon/index.md) - [Keyboard Key](https://vara.varavel.com/docs/components/kbd/index.md) - [Header](https://vara.varavel.com/docs/components/header/index.md) - [Hero](https://vara.varavel.com/docs/components/hero/index.md) - [Content Split](https://vara.varavel.com/docs/components/content-split/index.md) - [Features](https://vara.varavel.com/docs/components/features/index.md) - [Stats](https://vara.varavel.com/docs/components/stats/index.md) - [FAQ](https://vara.varavel.com/docs/components/faq/index.md) - [Testimonial](https://vara.varavel.com/docs/components/testimonial/index.md) - [Carousel](https://vara.varavel.com/docs/components/carousel/index.md) - [Call to Action](https://vara.varavel.com/docs/components/cta/index.md) - [Footer](https://vara.varavel.com/docs/components/footer/index.md) - [Troubleshooting](https://vara.varavel.com/docs/troubleshooting/index.md) ## Documentation content The complete documentation for this website follows, reproduced verbatim from every page. --- # Documentation Welcome to the **Vara** documentation. Vara is a clean, fast, and responsive theme for [Veta](https://veta.varavel.com), the static site generator by Varavel. It gives you the templates, components, and assets to build a documentation site and a landing page from a single project. ## How the documentation is organized - **Getting Started** - install the theme and create your first pages. - **Fundamentals** - how the theme works: project structure, page generators, site settings, search, and customization. - **Templates** - every page template, what it does, and how to configure it. - **Components** - the catalog of building blocks available for your content. - **Troubleshooting** - quick fixes for the issues people run into most often. If you are new here, start with the [introduction](./introduction/), then follow the [installation guide](./getting-started/installation/). Each page has a table of contents on the right when it contains multiple headings. --- # Introduction Vara is a theme for **Veta**, the static site generator by Varavel. It provides the page templates, components, and assets you need to build a documentation site and a landing page, so you can focus on the content instead of the frontend. ## How Veta and Vara work together Veta turns project files into a static site. Your project declares which pages to generate, and Vara provides the presentation layer for them. A typical Veta project built with Vara has three parts: 1. **Page generators** (`pages/*.js`) - declare each route and the template it uses. 2. **Markdown content** (`content/`) - written by you, optionally composed with Vara components. 3. **Site settings** (`data/site.yaml`) - branding and behavior that the theme reads. The theme stays out of your content. You decide what the site contains; Vara decides how it looks. ## What Vara provides - **Page templates** for landing pages, documentation pages, the not-found page, an XML sitemap, a search index, and LLM-friendly Markdown output. - **A focused component collection** for documentation content and landing-page sections. - **A visual system** with light and dark mode, a theme picker, self-hosted fonts, and bundled icons. - **Client-side features** such as full-text documentation search and on-demand syntax highlighting. ## What Vara does not provide - **Page generators.** Veta themes can only distribute `templates/`, `components/`, `filters/`, `functions/`, `data/`, and `public/`. Your project owns `pages/*.js` and therefore decides what gets built. - **Configuration.** Your project's `veta.yaml` controls the build, Tailwind CSS entrypoints, and output settings. This separation keeps the site structure explicit and prevents a theme from creating unexpected routes. ## Design principles Vara follows three principles: 1. **Simple** - few moving parts, easy to understand and to extend. 2. **Fast** - static output with minimal JavaScript, loaded only when a page needs it. 3. **Idiomatic** - built around Veta's own concepts: templates, components, filters, and functions. ## Next steps - [Install the theme](./getting-started/installation/). - [Create your first pages](./getting-started/quick-start/). - Browse the [templates](./templates/) and [components](./components/) when you are ready to compose. --- # Getting Started This section walks you through adding Vara to a Veta project and creating your first pages. - **[Installation](./installation/)** - add the theme, wire up the stylesheet, and verify the setup. - **[Quick Start](./quick-start/)** - create a landing page and a documentation page. - **[Composing a Landing Page](./composing-landing-page/)** - assemble a full landing page and add your own components. ## Prerequisites - A working [Veta](https://veta.varavel.com) installation. - A Veta project with a `veta.yaml` file. ## How a Veta page is built Veta does not infer routes from Markdown files. Instead, JavaScript page generators in `pages/*.js` decide what gets built. Each generator returns an array of pages, and every page names a template from the theme: ```js export default function({ files, parse }) { const md = parse.markdown(files.readFile("content/index.md")); return [ { permalink: "/", template: "vara-landing", title: "Home", content: parse.renderComponents(md.html), }, ]; } ``` Once a page exists, everything else - layout, navigation, search, metadata - comes from the template and the site settings you configure in `data/site.yaml`. The theme includes reference generators for both the landing page and the documentation site. You can use them as a starting point and adapt them to your project. --- # Installation ## 1. Add the theme Declare the theme in your `veta.yaml`. Remote themes use the `owner/repository@ref` form: ```yaml theme: source: "varavelio/veta-theme-vara@main" ``` Pin the `ref` (recommended) to a release tag or a commit SHA when you want reproducible builds: ```yaml theme: source: "varavelio/veta-theme-vara@v1.0.1" ``` ## 2. Configure the stylesheet Veta ships Tailwind CSS as part of the binary, so you don't need to install anything extra. Just point Veta at the theme's stylesheet in your `veta.yaml`: ```yaml tailwindcss: stylesheets: - styles.css minify: true ``` The theme provides `public/styles.css` for you, so there's nothing to create by hand. You'll only add that file when you want to extend the styles, as shown next. ### Extending styles To add your own styles, create `public/styles.css` and import the theme's styles first, then write your own Tailwind CSS after them: ```css /* public/styles.css */ @import "./styles_vara.css"; /* your own styles go here */ ``` Vara always reads from `public/styles.css`. When that file doesn't exist, the theme's bundled version is used as-is. ## 3. Add your site settings Create a `data/site.yaml` with at least a title and description: ```yaml title: "My Project" description: "The product documentation and landing page for my project." site_url: "https://example.com" ``` The theme reads these values for the document title, meta description, and header branding. See [Site settings](../fundamentals/site-settings/) for the full list. ## 4. Verify Run the development server: ```sh veta dev ``` Open the URL Veta prints. You should see the theme's base styles applied - self-hosted fonts, light and dark mode, and the default neutral palette. ## Next steps - [Create your first pages](./quick-start/). - Learn how the theme is structured in [Project structure](../fundamentals/project-structure/). --- # Quick Start This guide creates a project with a landing page at `/` and a small documentation site at `/docs/`. ## 1. Create the landing page generator Create `pages/pages.js` to render `content/index.md` with the `vara-landing` template: ```js export default function({ data, files, parse }) { const md = parse.markdown(files.readFile("content/index.md")); return [ { permalink: "/", template: "vara-landing", title: md.frontmatter.title || data.site.title, description: md.frontmatter.description || data.site.description, content: parse.renderComponents(md.html), }, ]; } ``` ## 2. Write the landing page Create `content/index.md` and compose it with Vara components: ```md --- title: "My Project" description: "A short description of the project." --- ``` ## 3. Create the documentation generator Create `pages/docs.js` to turn every Markdown file under `content/docs/` into a page using the `vara-docs` template: ```js export default function({ files, parse }) { return files.listFiles("content/docs/**/*.md").map((path) => { const page = parse.markdown(files.readFile(path)); return { permalink: files.toPermalink(path, { stripPrefix: "content/" }), template: "vara-docs", title: page.frontmatter.title || "Untitled", description: page.frontmatter.description || "", weight: Number(page.frontmatter.weight) || 999999, icon: page.frontmatter.icon || "", content: parse.renderComponents(page.html), }; }); } ``` This generator is intentionally short. The theme's reference generator goes further: it skips pages with `draft: true` in their frontmatter and passes `disable_search` through so a page can opt out of the index. See [Page generators](../fundamentals/page-generators/) for the full set of fields a docs page can carry. ## 4. Add a documentation page Create `content/docs/getting-started/hello.md`: ```md --- title: "Hello" weight: 1 --- # Hello This is my first documentation page. ``` Add an index page at `content/docs/index.md` if you want a landing page for the section: ```md --- title: "Documentation" weight: 0 --- # Documentation The documentation for my project lives here. ``` ## 5. Configure the site Add a `data/site.yaml`: ```yaml title: "My Project" description: "A short description of the project." site_url: "https://example.com" ``` ## 6. Run it ```sh veta dev ``` Visit `/` for the landing page and `/docs/getting-started/hello/` for the documentation page. ## Next steps - Learn how documentation pages are organized in [Page generators](../fundamentals/page-generators/). - Customize the sidebar, search, and branding in [Site settings](../fundamentals/site-settings/). - Browse the [components](../components/) to enrich your content. --- # Composing a Landing Page The quick start leaves you with a single hero. This guide builds a complete landing page section by section, then shows how to create your own component so the page can grow with your project. A landing page is a stack of sections, and most sections accept the same surface controls: `container`, `background`, and `class`. The order of the components in your Markdown is the order they appear on the page, so start with the entry point and work your way down. ## The page shell Everything lives in `content/index.md`. Build the page top to bottom. ### 1. Header The header carries the brand, navigation, and a primary action: ```html ``` ### 2. Hero The hero is the first thing visitors see. Give it a headline, one clear sentence, and a pair of actions: ```html ``` ### 3. Features Summarize what makes the product worth trying: ```html ``` ### 4. Stats Specific numbers build trust: ```html ``` ### 5. A content split Use a split when a workflow or a benefit deserves more room: ```html ``` ### 6. FAQ Address the questions that stop people from signing up: ```html Yes - one project, unlimited dashboards, and community support. Data is encrypted in transit and at rest, and you can export everything at any time. Most integrations come with one-click import, and the API covers the rest. ``` ### 7. Call to action Close the page with one clear next step: ```html ``` ### 8. Footer End with the footer so every page has a consistent exit: ```html ``` ## Making it yours The bundled sections cover the common path, but your landing page will eventually need something specific - a logo cloud, a pricing table, a comparison. That is where Vara shines: components are just templates, so adding your own takes minutes. ### Your first component Create `components/vara-logo-cloud.j2`. The filename becomes the tag name, so keep the `vara-` prefix and kebab-case: ```html

Trusted by teams at

{{ props.content|safe }}
``` Use it as a paired tag anywhere in your page. Whatever you put between the tags is passed to `props.content`: ```html Acme Northwind ``` ### What your components can use Your components live in the same world as the theme's, so they can reach for everything Vara ships: - **Props** - read `props.` for every attribute, and `props.content` for the paired body. - **Macros** - import the theme's macros for consistent UI, for example `{% import "../templates/vara/macros/button.j2" button %}`. - **Functions and filters** - call theme helpers such as `vara_icon`, `vara_site_setting`, and `vara_compact_number`. - **Layout primitives** - compose with `` when you want the same sizing as the rest of the page. Here is a component that combines a title, paired content, and a button macro: ```html {% import "../templates/vara/macros/button.j2" button %}

{{ props.title|default:"A heading you can set" }}

{% if props.content|vara_trim %}
{{ props.content|safe }}
{% endif %} {% if props.cta_label and props.cta_href %}
{{ button(props.cta_label, props.cta_href, "", "", "", "lg", "md", "solid", "neutral", "true", "false", "button", "desk:w-auto") }}
{% endif %}
``` ### Props stay strings Component attributes are strings, so keep the same conventions the theme uses: quote every value, use `"true"` / `"false"` for booleans, and accept a `class` prop so users can extend your component: ```html
``` ## Keeping the page maintainable - Give every section a matching `container` so the page feels aligned. - Alternate `background` values (`base-100` and `base-200`) to separate sections visually. - Keep one idea per section - if one grows past a few paragraphs, split it. - Check the page on a narrow screen; every section should read comfortably on mobile. ## Next steps - Browse the [component catalog](../components/) for everything else that ships with Vara. - Learn how to [override the theme](../fundamentals/customization/) or change its look. - Read about [page generators](../fundamentals/page-generators/) when you are ready to restructure the site. --- # Fundamentals This section explains how the theme works so you can use it confidently and extend it when you need to. - **[Project structure](./project-structure/)** - what the theme ships and where each piece lives. - **[Page generators](./page-generators/)** - how pages are declared and wired to templates. - **[Site settings](./site-settings/)** - every setting the theme reads from `data/site.yaml`. - **[Search and LLM output](./search-and-llms/)** - client-side search, Markdown actions, and `llms.txt` files. - **[Customization](./customization/)** - colors, fonts, icons, dark mode, and overriding the theme. - **[Functions and filters](./functions-and-filters/)** - the template helpers worth using in your own components. You don't need to read all of these before writing content. Start with the ones that match your task, and come back when you want to dig deeper. --- # Project Structure Vara distributes the standard Veta theme directories: `templates/`, `components/`, `filters/`, `functions/`, `data/`, and `public/`. Project files always override theme files with the same path, so you can customize the theme without forking it. ## Templates `templates/` contains the page templates you reference from your generators: | Template | Purpose | | ------------------------- | -------------------------------------------------------- | | `vara-landing` | Landing page built from your `page.content`. | | `vara-docs` | Documentation page with header, sidebar, TOC, and pager. | | `vara-docs-raw` | The raw Markdown source of a documentation page. | | `vara-docs-search-index` | The JSON index used by client-side search. | | `vara-docs-llms-txt` | A plain-text index of every documentation page. | | `vara-docs-llms-full-txt` | The same index plus the full content of every page. | | `vara-sitemap-xml` | An XML sitemap of the site's HTML routes. | | `vara-404` | The not-found page. | See the [Templates](../templates/) section for a description of each one. ## Components `components/` holds a small collection of reusable building blocks. Each component is a file named `vara-.j2` and is used as a custom HTML tag in your Markdown: ```html ``` Components that take dynamic content or render interactive behavior use Alpine.js, which is bundled with the theme. See the [Components](../components/) section for the full catalog. ## Filters and functions `filters/` and `functions/` contain the template helpers the theme uses. They carry the `vara_` prefix because they ship in the consuming project's namespace. Most of them are internal plumbing for the theme's own templates, but a handful are worth reaching for in your own components. See [Functions and filters](./functions-and-filters/) for the curated list. ## Data `data/` provides the theme's default configuration: - `site_default.js` - every setting Vara understands, with its default value. - `vara.js` - a few runtime values such as the current year, used for the footer copyright. You override defaults with your own `data/site.yaml` in the project. See [Site settings](./site-settings/). ## Public assets `public/` contains the compiled assets the theme serves: - `_vara/css/` - the Tailwind CSS base stylesheet and theme styles. - `_vara/js/` - the JavaScript bundles (head, landing, docs, and docs search). - `_vara/fonts/` - the self-hosted Geist fonts. All theme-owned assets live under `public/_vara/` so they never collide with your own files. Your project's `public/` directory is composed alongside the theme's. ## Your project's side The directories Vara does not ship are the ones you own: - `pages/` - your JavaScript page generators. - `content/` - your Markdown content. - `data/site.yaml` - your configuration overrides. - `veta.yaml` - build, Tailwind CSS, and theme configuration. ## Reference generators The theme repository includes working generators in `pages/` so you can see how everything is wired: - `pages/pages.js` - the landing page, the not-found page, and the sitemap. - `pages/docs.js` - every documentation page plus the search index and `llms.txt` outputs. Adapt them to your project, or write your own from the [Page generators](./page-generators/) guide. --- # Page Generators In Veta, pages are not discovered from Markdown. Your project declares them in JavaScript files under `pages/`. Each generator returns an array of pages, and every page names a template from the theme. This guide shows the generators the theme itself uses, adapted so you can copy them into your project. ## The landing page The `vara-landing` template renders `page.content` as the whole page. Read `content/index.md`, render it, and pass it along: ```js // pages/pages.js export default function({ data, files, parse }) { const md = parse.markdown(files.readFile("content/index.md")); return [ { permalink: "/", template: "vara-landing", title: md.frontmatter.title || data.site.title, description: md.frontmatter.description || data.site.description, content: parse.renderComponents(md.html), }, ]; } ``` `parse.renderComponents` resolves Vara component tags after the Markdown is rendered, which is how `` and friends end up in your content. ## The documentation pages The `vara-docs` template is used for every page under the docs root. The generator reads the Markdown, extracts a few frontmatter fields, and passes the rendered content: ```js // pages/docs.js export default function({ files, parse }) { return files.listFiles("content/docs/**/*.md") .filter((path) => !parse.markdown(files.readFile(path)).frontmatter.draft) .map((path) => { const page = parse.markdown(files.readFile(path)); return { permalink: files.toPermalink(path, { stripPrefix: "content/" }), template: "vara-docs", title: page.frontmatter.title || "Untitled", description: page.frontmatter.description || "", weight: Number(page.frontmatter.weight) || 999999, icon: page.frontmatter.icon || "", content: parse.renderComponents(page.html), disable_search: page.frontmatter.disable_search === true, }; }); } ``` ### Fields the theme reads | Field | Used for | | ---------------- | ---------------------------------------------------------------- | | `template` | The template to render. | | `permalink` | The page's route. | | `title` | Document title, sidebar label, breadcrumb, and pager. | | `description` | The meta description and search result snippets. | | `content` | The rendered page body. | | `weight` | Ordering in the sidebar, pager, and LLM indexes. | | `icon` | The icon shown next to the page in the sidebar. | | `disable_search` | Excludes the page from the search index when `true`. | | `lang` | The page language, used by the search index (`"en"` by default). | ### Frontmatter fields For a documentation page, Vara reads these frontmatter fields: | Field | Purpose | | ---------------- | ----------------------------------------------------- | | `title` | Required. The page title. | | `description` | Optional. Shown in search results and metadata. | | `weight` | Optional. Controls ordering. Lower values come first. | | `icon` | Optional. An icon name for the sidebar. | | `draft` | Optional. Skips the page when `true`. | | `disable_search` | Optional. Excludes the page from search when `true`. | ### The raw Markdown version Documentation pages also get a `vara-docs-raw` page at the same permalink with `index.md` appended. This is what the "View Markdown", "Copy Markdown", and "Ask AI" actions point to: ```js pages.push({ permalink: permalink + "index.md", template: "vara-docs-raw", title, description, weight, icon, content: pageMarkdown, }); ``` The `vara-docs-raw` template writes the original Markdown, with an optional hierarchical index prepended when `docs_llms_index` is enabled. ## The support pages A full documentation site also needs three support routes. They require no content of their own: ```js pages.push({ permalink: "/docs/vara-docs-search-index.json", template: "vara-docs-search-index", sitemap: false, }); pages.push({ permalink: "/docs/llms.txt", template: "vara-docs-llms-txt", }); pages.push({ permalink: "/docs/llms-full.txt", template: "vara-docs-llms-full-txt", }); ``` If you change `docs_root_permalink` or `docs_search_index_permalink`, update these permalinks to match - the templates resolve their own output from those settings, but the routes themselves come from your generator. ## The not-found page and the sitemap The `vara-404` template is a self-contained page. The `vara-sitemap-xml` template lists the site's HTML routes: ```js pages.push({ permalink: "/404.html", template: "vara-404", title: "Page not found", description: "The requested page could not be found.", sitemap: false, content: "", }); pages.push({ permalink: "/sitemap.xml", template: "vara-sitemap-xml", }); ``` ### Sitemap behavior HTML routes are included in the sitemap automatically. Other output formats need `sitemap: true`, and any page can opt out with `sitemap: false`. The not-found page and the search index opt out above because they are not meaningful for search engines. ## Sorting Documentation pages are sorted by `weight`, then by title. The theme's own generator applies that ordering before building the search index and LLM outputs, so keep your generator consistent if you want the same order everywhere. --- # Site Settings Vara reads its configuration from your project's `data/site.yaml`. The theme's defaults live in its own `data/site_default.js`; your file only needs to override what you care about. When a template asks for a value, it checks `data.site` first and falls back to the theme default. Empty strings are treated as unset, so `""` falls through to the default; `false`, `0`, and empty collections are kept. ## Core settings | Setting | Default | Description | | ------------- | -------------- | --------------------------------------------------------------------------------------------------------------- | | `title` | `""` | The site title. Used in the document title, header branding, and social metadata. | | `description` | `""` | Default meta description, used when a page has none. | | `site_url` | `""` | The public base URL. Used for canonical and Open Graph URLs, the sitemap, and the absolute links in LLM output. | | `favicon` | Varavel avatar | The site favicon. | | `logo_light` | Varavel logo | The brand logo for light surfaces. | | `logo_dark` | Varavel logo | The brand logo for dark surfaces. | A minimal `data/site.yaml`: ```yaml title: "Acme" description: "Documentation and landing page for Acme." site_url: "https://acme.example.com" favicon: "/favicon.svg" logo_light: "/images/logo-dark.svg" logo_dark: "/images/logo-light.svg" ``` ### `site_url` Set this to the deployed origin (for example `https://acme.example.com`). Vara uses it only where an absolute URL is required - canonical tags, Open Graph, the sitemap, and LLM output. Navigation links stay relative so local previews keep working. If `site_url` is missing or invalid, Vara falls back to root-relative URLs. ## The not-found page | Setting | Default | Description | | ----------------- | ------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `not_found_links` | one link: `Go home` → `/` | Ordered links on the 404 page. Each entry needs `title` and `href`, and may have `icon` and `new_tab`. The first valid link is the primary action; the rest are secondary. | ```yaml not_found_links: - title: "Go home" href: "/" icon: "house" - title: "Read the docs" href: "/docs/" icon: "book-open-text" - title: "View the source" href: "https://github.com/example/project" icon: "github" new_tab: true ``` ## Documentation settings Documentation settings are namespaced with `docs_`. They only affect the `vara-docs` template. ### Branding | Setting | Default | Description | | ----------------- | ----------------- | -------------------------------------------------------- | | `docs_favicon` | site `favicon` | Favicon used on documentation pages. | | `docs_logo_light` | site `logo_light` | Brand logo for light surfaces on documentation pages. | | `docs_logo_dark` | site `logo_dark` | Brand logo for dark surfaces on documentation pages. | | `docs_show_logo` | `true` | Show the brand logo in the docs header. | | `docs_show_title` | `true` | Show the site title next to the logo in the docs header. | Set `docs_show_logo: false` when your documentation site has no logo, or `docs_show_title: false` when the logo artwork already includes the title. Setting both hides the brand link from the docs header. ### Header and GitHub | Setting | Default | Description | | ------------------- | ------- | ---------------------------------------------------------------------------------------------------------------------------------------------------- | | `docs_github_repo` | `""` | Repository in `owner/name` format. When set, the docs header shows a GitHub button with star count fetched at build time. | | `docs_header_links` | `[]` | Ordered links shown in the desktop header and the mobile navigation drawer. Each entry needs `title` and `href`, with optional `new_tab` and `icon`. | ```yaml docs_github_repo: "acme/project" docs_header_links: - title: "Blog" href: "/blog/" - title: "GitHub" href: "https://github.com/acme/project" new_tab: true icon: "github" ``` ### Sidebar | Setting | Default | Description | | ------------------------ | ------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `docs_sidebar_sections` | `[]` | Creates or extends sidebar sections. Sections merge with the generated ones by stable `id`; links with matching `href` values are merged instead of duplicated. | | `docs_sidebar_collapsed` | `false` | Collapse sidebar groups by default. The visitor's open/closed state is remembered. | The sidebar is built from your documentation pages. The first segment of each permalink below the docs root becomes a section, and pages two levels deep become links within it. ```yaml docs_sidebar_sections: - id: "guide" title: "Guide" icon: "book-open-text" weight: 10 links: - title: "Introduction" href: "/docs/guide/introduction/" - title: "Contributing" href: "/docs/guide/contributing/" ``` The stable `id` is the first permalink segment below the docs root. Use it to reorder a generated section or to attach extra links to it. ### Search and LLM output | Setting | Default | Description | | ----------------------------- | ----------------------------------- | ---------------------------------------------------------------------------------------------------------------- | | `docs_search` | `true` | Enable client-side documentation search. | | `docs_search_index_permalink` | `/docs/vara-docs-search-index.json` | The route of the search index. Your generator must create that route with the `vara-docs-search-index` template. | | `docs_llms` | `true` | Enable the "Agents" sidebar section and the Markdown actions menu on documentation pages. | | `docs_llms_index` | `true` | Prepend a hierarchical index to each `vara-docs-raw` page. | See [Search and LLM output](./search-and-llms/) for how these features work together. ### Content | Setting | Default | Description | | ----------------------------- | ---------- | ------------------------------------------------------------------------------------------------------------------------ | | `docs_credits_footer` | `true` | Show the "Built with veta and veta-theme-vara" line below the documentation content. | | `docs_root_permalink` | `/docs/` | The logical root of the documentation tree. It may be nested or `/`. Deployment prefixes belong in `site_url`. | | `docs_shiki` | `true` | Enable client-side syntax highlighting with the fixed `github-light` and `github-dark` themes. | | `docs_shiki_custom_languages` | one: `vdl` | Extra languages for syntax highlighting. Each entry requires an exact `id` and a CORS-accessible TextMate grammar `url`. | ```yaml docs_shiki_custom_languages: - id: "toml" url: "https://cdn.example.com/toml.tmLanguage.json" ``` The custom language `id` must match the code fence language you use in Markdown: ````md ```toml theme: source: "varavelio/veta-theme-vara" ``` ```` --- # Search and LLM Output Documentation sites built with Vara get three content features out of the box: client-side search, on-demand syntax highlighting, and LLM-friendly Markdown output. ## Client-side search When `docs_search` is enabled, the docs header shows a search field. Opening it (or pressing `Ctrl`/`Cmd` + `K`) runs a full-text search over your documentation, entirely in the browser. ### How the index works At build time, the `vara-docs-search-index` template produces a JSON index. The theme builds it from every `vara-docs` page under the docs root, storing the title, description, and rendered content of each page. The search UI loads the index lazily - the first time you hover or focus the search field - and builds a MiniSearch engine from it in the background. Queries match page titles and section headings, with fuzzy matching for longer terms. ### Customizing what gets indexed Exclude a page from search with `disable_search: true` in its frontmatter. Pages marked as drafts are not generated at all. ### When the index is missing The search dialog shows a clear error if the index cannot be loaded. That happens when your generator does not create the search index route. Make sure it produces a page with the `vara-docs-search-index` template at `docs_search_index_permalink` (default `/docs/vara-docs-search-index.json`), or disable search with `docs_search: false`. ## Syntax highlighting Code blocks are highlighted on demand with the `github-light` and `github-dark` themes, following the site's active theme. Vara overrides their backgrounds to match the theme's surfaces and renders that background while the highlighter loads, so blocks never flash unstyled. The language of each code fence is detected from its rendered `language-*` class and loaded only when needed: ````md ```js const answer = 42; ``` ```` Extra languages beyond Shiki's bundled set can be added with `docs_shiki_custom_languages`. The entry's `id` must match the code fence language. Highlighted blocks include a copy button that appears on hover. It is wired to the clipboard API and disabled automatically when the clipboard is unavailable. To disable highlighting entirely, set `docs_shiki: false`. ## Markdown actions Every documentation page that has content shows a **"Ask AI"** menu next to the table-of-contents toggle. From it you can: - Open the page's Markdown source in an AI assistant: ChatGPT, Claude, Grok, Perplexity, or DeepSeek. - Copy a ready-made prompt for asking about the page. - Copy, view, or download the raw Markdown. These actions rely on the raw Markdown version of each page (`vara-docs-raw`), so they only appear when your generator produces it. They are tied to the `docs_llms` setting - set it to `false` to hide both the menu and the "Agents" sidebar section. ## llms.txt output Vara generates two plain-text files that describe your documentation for LLMs: | File | Contents | | --------------- | ----------------------------------------------------------------------------------------------------------- | | `llms.txt` | A hierarchical index of every documentation page, with absolute links to each page and its Markdown source. | | `llms-full.txt` | The same index followed by the complete content of every page, reproduced verbatim. | Both are generated from the `vara-docs-raw` pages under the docs root, in the same order the sidebar uses. Their routes are `/docs/llms.txt` and `/docs/llms-full.txt` by default, and they appear under the **Agents** section in the sidebar. `docs_llms_index` controls whether each individual `vara-docs-raw` page also prepends a small index before its own content. This is useful when a single Markdown file is handed to an assistant directly. --- # Customization Vara is designed to look good on its own, but it is meant to be adapted. Because the theme is built with Tailwind CSS and structured around Veta's concepts, most customizations stay small and local to your project. ## Colors Vara uses a small set of design tokens that map to Tailwind utility classes: | Token | Light | Dark | Typical use | | --------------- | ----------- | ----------- | ------------------------ | | `base-100` | white | black | Page and header surfaces | | `base-200` | neutral-100 | neutral-900 | Card and panel surfaces | | `base-300` | neutral-200 | neutral-800 | Hover surfaces | | `base-400` | neutral-300 | neutral-700 | Borders and dividers | | `content` | neutral-950 | neutral-50 | Primary text | | `content-muted` | neutral-500 | neutral-400 | Secondary text | | `info` | blue-500 | blue-500 | Informational accents | | `success` | emerald-500 | emerald-500 | Success accents | | `warning` | orange-500 | orange-500 | Warning accents | | `error` | red-500 | red-500 | Error accents | Components use these tokens directly, so changing them restyles the whole site. Add your own overrides after the theme import in your stylesheet: ```css @import "./_vara/css/base.css"; @theme { --color-info: var(--color-sky-500); } ``` The full token definitions live in `public/_vara/css/base.css`. ## Dark mode Light and dark mode are built in. The theme starts by following the operating system preference, remembers the visitor's choice in `localStorage`, and reacts to system changes while it is set to "system". Landing pages get a theme picker through the `` component, and documentation pages always show one in the header. The picker offers System, Light, and Dark. ## Typography Vara ships with the Geist Sans and Geist Mono variable fonts, self-hosted under `public/_vara/fonts/` so no external requests are needed. Sans is used for interface and content text; mono is used for code, keyboard keys, and metrics. Add a `font-sans` or `font-mono` override in your stylesheet to change the families site-wide. ## Icons The theme bundles an icon set with thousands of SVGs - Lucide icons plus Simple Icons - stored under `templates/vara/icons/`. Use them anywhere with the `` component: ```html ``` Lucide names collide with Simple Icons names on purpose; when that happens, the Simple Icons variant is prefixed with `si-` (for example, `x` is the Lucide version and `si-x` is the brand version). To use an icon in your own template, call the `vara_icon` function with the icon name and optional classes: ``` {{ vara_icon("check", "size-4") | safe }} ``` Missing icons render a visible warning glyph instead of breaking the build. ## Writing content ### Component attributes Component attributes are strings. Quote every value, use `"true"` / `"false"` for booleans, and use the predictable `item_N_*` families for bounded lists of records. Markdown inside a component's body is rendered before the component resolves it, so paired components receive real HTML, not raw Markdown. Set `class` on a component to extend it with your own utilities. ### Headings inside components On documentation pages, headings only join the table of contents and receive anchor links when they live in the page's prose. Components render with a `not-prose` marker, so headings inside them stay out of the TOC on purpose - an accordion question or a card title is embedded content, not a section of the article. Use `class="not-prose"` on your own markup when you want the same opt-out. See [vara-docs](../templates/docs/) for details. ### Links and assets Use root-relative paths for internal links and assets. Vara resolves them with Veta's deployment-aware `url()` helper, so your site keeps working when deployed below a path prefix. When a link opens in a new tab, the theme adds `rel="noopener noreferrer"` automatically. ## Overriding the theme Veta composes the theme and the project into one filesystem, and project files win. To customize the theme without forking it, add files with the same path to your project: ```txt theme/templates/vara-docs.j2 templates/vara-docs.j2 # your override ``` You can override a template, replace a component, or extend the styles. The rest of the theme keeps working as before. ### Adding your own components Components are just templates in `components/`. Add a new file there, and it becomes available as a custom tag in your content: ```html ``` Your components can import the theme's macros and call its functions, so they stay consistent with the rest of the site. Keep domain-specific components in your project - the theme's own collection stays small and general-purpose by design. --- # Functions and Filters Vara ships a set of template helpers under the `vara_` prefix. Most of them do internal plumbing - building the sidebar, pagination, search index, and similar - and you never need to touch them. This page covers the small set that is genuinely useful when you write your own components or templates. Functions are called like any Pongo function, and filters are applied with a pipe: ```text {{ vara_icon("rocket", "size-5") }} {{ repo.stars|vara_compact_number }} ``` ## Functions ### `vara_icon` Renders one of the bundled SVG icons by name. Pass optional utility classes for size and color: ```text {{ vara_icon("check", "size-4 text-success")|safe }} ``` Icon names come from the theme's icon set - the same names the `` component accepts. Browse them in the [icon explorer](/icons/). Missing names render a visible warning glyph instead of failing the build. ### `vara_absolute_url` Resolves a path against your `site_url` and returns an absolute URL. Useful for social metadata or generated output that needs a full link: ```text {{ vara_absolute_url(page.permalink) }} ``` Absolute HTTP URLs pass through unchanged. When `site_url` is missing or invalid, the result falls back to a root-relative path. ### `vara_github_repo` Fetches public metadata for an `owner/name` repository at build time: stars, forks, and the latest release tag. It is what powers the GitHub button in the docs header, and it works the same way in your own components: ```text {% set repo = vara_github_repo("varavelio/veta") %} {% if repo.ok %} {{ repo.stars|vara_compact_number }} stars {% endif %} ``` The result is cached per repository during a build, so you can call it in several places without extra requests. Failed lookups return a safe empty result rather than breaking the build. ## Filters ### `vara_trim` Trims leading and trailing whitespace, treating empty values as empty strings. Ideal for optional-value conditionals in components: ```text {% if props.description|vara_trim %}

{{ props.description }}

{% endif %} ``` ### `vara_compact_number` Formats a number compactly - `12400` becomes `12.4k`, and `2100000` becomes `2.1M`. Non-finite input becomes `0`. Handy for stats, repository counts, or any metric with large values: ```text {{ repo.stars|vara_compact_number }} ``` ## What is not covered here Everything else under theme's `functions/` and `filters/` directories is theme plumbing: sidebar navigation, pagination, search indexing, sitemap generation, and the like. The theme keeps those stable, but they exist to serve its own templates. If a helper is not listed on this page, treat it as internal and prefer the public API above in your own code. --- # Templates Templates are the page-level layouts of the theme. Your page generators reference them by name, and each template decides how the page is rendered around your content. Vara ships eight templates: | Template | Page | What it renders | | ------------------------------------------------ | ------------------- | ---------------------------------------------------------------- | | [vara-landing](./landing/) | Landing pages | Your content as a full page, with the landing JavaScript bundle. | | [vara-docs](./docs/) | Documentation pages | Header, sidebar, content, table of contents, and pager. | | [vara-docs-raw](./docs-raw/) | Raw Markdown | The original Markdown source of a docs page. | | [vara-docs-search-index](./docs-search-index/) | JSON | The search index consumed by client-side search. | | [vara-docs-llms-txt](./docs-llms-txt/) | Plain text | A hierarchical index of every documentation page. | | [vara-docs-llms-full-txt](./docs-llms-full-txt/) | Plain text | The index plus the full content of every page. | | [vara-sitemap-xml](./sitemap-xml/) | XML | The site's sitemap. | | [vara-404](./404/) | Not found | A self-contained 404 page. | The landing, docs, and 404 templates build on a shared base that provides the document shell, SEO metadata, fonts, and styles. The data templates (search index, llms output, sitemap) do not use that shell - they output their own format. Each page below describes what the template expects from the page object and how to configure it. --- # vara-landing The `vara-landing` template renders your page content as a full-page landing site. It loads the landing JavaScript bundle, which starts Alpine and registers the shared theme controls used by interactive components such as ``. ## When to use it Use `vara-landing` for any page that is not documentation: marketing pages, home pages, project showcases, and single-purpose pages. The template places no constraints on your content - it renders whatever the page's `content` contains. ## Page fields | Field | Purpose | | ------------- | ------------------------------------------------------ | | `content` | The rendered page body, composed with Vara components. | | `title` | The document title and metadata. | | `description` | The meta description. | | `lang` | Optional. The page language; defaults to `en`. | ## Declaring the page ```js { permalink: "/", template: "vara-landing", title: "Home", description: "The landing page for the project.", content: parse.renderComponents(md.html), } ``` ## The base shell Like the docs and 404 templates, `vara-landing` builds on the theme's base template, which provides: - The document shell with `` and ``. - Title, meta description, canonical, and Open Graph metadata. - The site favicon and the compiled stylesheet. - The head JavaScript bundle that applies the saved theme before first paint. You can supply extra metadata through page fields such as `description`, `keywords`, and `og_type`. ## What your content includes Landing pages are typically composed with the landing-page components: ``, ``, ``, ``, ``, ``, ``, ``, ``, and ``. --- # vara-docs The `vara-docs` template is the heart of the documentation site. It provides the full documentation chrome around your content: a header, a search field, a collapsible sidebar, a table of contents, previous and next navigation, and page metadata. ## When to use it Use `vara-docs` for every page under your documentation root. The template handles navigation and reading experience, so your generator only needs to supply content and a few ordering fields. ## Layout A documentation page is composed of: - **Header** - brand, search field, header links, the GitHub button, and the theme picker. - **Sidebar** - the documentation tree, built from your pages and `docs_sidebar_sections`. On small screens it becomes a drawer. - **Content** - breadcrumbs, the rendered article, optional page links, previous/next pager, and the credits footer. - **Table of contents** - on wide screens it sits to the right; on small screens it opens as a panel. The template loads the docs JavaScript bundle, which handles the sidebar, TOC, anchor links, back-to-top button, and syntax highlighting. ## Reading experience A few behaviors make long documentation pleasant to read, and they come ready out of the box: - **Table of contents** - on wide screens, the right rail lists the page's headings and highlights the section you are reading; on small screens it opens as a slide-over panel. - **Heading links** - every heading in the page body gets a small anchor link that appears on hover, so readers can copy a direct link to any section. - **Sidebar memory** - the sidebar keeps its scroll position between pages and remembers which groups you have expanded or collapsed. - **Back to top** - after scrolling down, a small button appears and glides you back to the top. - **Search shortcut** - press `Ctrl`/`Cmd` + `K` to open search from anywhere in the documentation. ### Which headings make it into the TOC The table of contents is built from the page's `h2` and `h3` headings, and those are the only ones that get anchor links. Headings that live inside a component are excluded on purpose: components render with a `not-prose` marker, so anything you place inside them is treated as embedded content rather than part of the article. If you want a heading to be navigable, write it as a regular Markdown heading in the page body instead of nesting it in a component. ## Page fields | Field | Purpose | | ------------------- | ----------------------------------------------------------------------- | | `content` | The rendered article body. Empty pages render as section landing pages. | | `title` | Document title, sidebar label, and breadcrumb. | | `description` | Meta description and search snippets. | | `weight` | Ordering in the sidebar, pager, and LLM indexes. | | `icon` | An icon shown next to the page in the sidebar. | | `disable_search` | Exclude the page from search when `true`. | | `docs_footer_links` | Optional links rendered between content and the pager. | ### `docs_footer_links` Each entry needs `title` and `href`, and may have an `icon`. Links open in a new tab unless you set `new_tab: false`. The theme's own generator uses this to add an "Edit this page" link. ## Declaring the page ```js { permalink: "/docs/guide/installation/", template: "vara-docs", title: "Installation", description: "How to install the project.", weight: 2, icon: "download", content: parse.renderComponents(md.html), docs_footer_links: [ { title: "Edit this page", href: "https://github.com/example/project/edit/main/content/docs/guide/installation.md", icon: "pencil-line" }, ], } ``` ## Configuration Most of the template's behavior is controlled by the `docs_*` site settings: - Branding and the GitHub button: `docs_favicon`, `docs_logo_light`, `docs_logo_dark`, `docs_show_logo`, `docs_show_title`, `docs_github_repo`, `docs_header_links`. - Sidebar: `docs_sidebar_sections`, `docs_sidebar_collapsed`. - Features: `docs_search`, `docs_llms`, `docs_credits_footer`, `docs_shiki`, `docs_root_permalink`. See [Site settings](../fundamentals/site-settings/) for the full reference. ## Related templates The documentation site is supported by three companion templates: - [vara-docs-raw](./docs-raw/) - the Markdown source of each page, used by the Markdown actions. - [vara-docs-search-index](./docs-search-index/) - the JSON index for client-side search. - [vara-docs-llms-txt](./docs-llms-txt/) and [vara-docs-llms-full-txt](./docs-llms-full-txt/) - the LLM indexes. --- # vara-docs-raw The `vara-docs-raw` template outputs the original Markdown source of a documentation page as a plain-text page. It is what powers the Markdown actions menu (View, Copy, Download, and "Ask AI") and the LLM indexes. ## When to use it Create one `vara-docs-raw` page for every documentation page, at the same permalink with `index.md` appended: ```js { permalink: "/docs/guide/installation/index.md", template: "vara-docs-raw", title: "Installation", description: "How to install the project.", weight: 2, icon: "download", content: pageMarkdown, } ``` The template expects the **unrendered Markdown** in `page.content`, not the rendered HTML. ## Index prefix When `docs_llms_index` is enabled, the template prepends a small hierarchical index of every documentation page to its output, followed by a heading and the page's content reproduced verbatim: ```txt ## Documentation index This index lists every available documentation page and its Markdown source. - [Documentation](https://example.com/docs/) - [Installation](https://example.com/docs/guide/installation/) ## Documentation content The documentation for the current page follows, reproduced verbatim. # Installation ... ``` Set `docs_llms_index: false` to output the page's Markdown alone. --- # vara-docs-search-index The `vara-docs-search-index` template produces the JSON index that the client-side search reads. It collects every `vara-docs` page under the docs root that does not opt out, and serializes it as a JSON document. ## When to use it Create one page with this template, at the route your search will load: ```js { permalink: "/docs/vara-docs-search-index.json", template: "vara-docs-search-index", sitemap: false, } ``` The route must match `docs_search_index_permalink` (default `/docs/vara-docs-search-index.json`). If you change that setting, update the generator to match. ## What gets included Each page contributes its permalink, title, description, rendered content, and language. Pages marked `disable_search: true` are excluded, and the search dialog reports a configuration error when the index route is missing. See [Search and LLM output](../fundamentals/search-and-llms/) for how the index is consumed. --- # vara-docs-llms-txt The `vara-docs-llms-txt` template outputs a plain-text file that lists every documentation page with an absolute link to it. It follows the `llms.txt` convention so AI assistants can discover your documentation. ## When to use it Create a page with this template at `/docs/llms.txt`: ```js { permalink: "/docs/llms.txt", template: "vara-docs-llms-txt", } ``` If you change `docs_root_permalink`, update the generator to match - the sidebar links to the index using that setting. ## Output The file is built from the `vara-docs-raw` pages under the docs root, in the same order the sidebar uses. Nested pages are indented to reflect the hierarchy: ```txt ## Documentation index This index lists every available documentation page and its Markdown source. - [Documentation](https://example.com/docs/) - [Installation](https://example.com/docs/guide/installation/) ``` Absolute links are resolved with `site_url`. See [Site settings](../fundamentals/site-settings/) for details. For a version that also includes the full content of every page, see [vara-docs-llms-full-txt](./docs-llms-full-txt/). --- # vara-docs-llms-full-txt The `vara-docs-llms-full-txt` template is the extended version of `vara-docs-llms-txt`. It produces the same hierarchical index, followed by the complete content of every documentation page, reproduced verbatim. ## When to use it Create a page with this template at `/docs/llms-full.txt`: ```js { permalink: "/docs/llms-full.txt", template: "vara-docs-llms-full-txt", } ``` This file is larger than `llms.txt` by design - it gives an assistant the entire documentation in a single download, which is convenient but slower to fetch. Publish both files and let each reader choose. ## Output ```txt ## Documentation index This index lists every available documentation page and its Markdown source. - [Documentation](https://example.com/docs/) - [Installation](https://example.com/docs/guide/installation/) ## Documentation content The complete documentation for this website follows, reproduced verbatim from every page. --- # Installation ... ``` The content comes from the `vara-docs-raw` pages, so each section is the original Markdown. Set `docs_llms: false` to hide both LLM files from the sidebar. --- # vara-sitemap-xml The `vara-sitemap-xml` template generates an XML sitemap of your site's routes, ready to submit to search engines. ## When to use it Create one page with this template at `/sitemap.xml`: ```js { permalink: "/sitemap.xml", template: "vara-sitemap-xml", } ``` ## Which pages are included HTML routes are included automatically. Other output formats - such as the search index and LLM files - are left out unless a page opts in with `sitemap: true`. Any page can opt out with `sitemap: false`, which is how the not-found page stays out of the sitemap. Entries are deduplicated by permalink, and each location is resolved to an absolute URL with `site_url`: ```xml https://example.com/ https://example.com/docs/ ``` See [Page generators](../fundamentals/page-generators/) for more on sitemap opt-in and opt-out. --- # vara-404 The `vara-404` template renders a self-contained not-found page with a large "404" backdrop, a short message, and a set of helpful links. ## When to use it Create one page with this template at `/404.html`: ```js { permalink: "/404.html", template: "vara-404", title: "Page not found", description: "The requested page could not be found.", sitemap: false, content: "", } ``` The page sets `noindex` metadata and is excluded from the sitemap. ## Configuring the links The links on the page come from the `not_found_links` setting. The first valid entry is rendered as the primary action; the rest appear as secondary actions: ```yaml not_found_links: - title: "Go home" href: "/" icon: "house" - title: "Read the docs" href: "/docs/" icon: "book-open-text" ``` Each entry needs `title` and `href`, and may have an `icon` and `new_tab`. See [Site settings](../fundamentals/site-settings/) for details. ## Hosting notes The page is produced as a static `/404.html` file. Most static hosts serve it automatically when a route is missing. If yours does not, configure the host to use `404.html` as the custom error page. Because hosts serve that file from any missing URL depth (for example `example.com/nested/path/`), the template resolves its stylesheet, scripts, and link URLs with `vara_absolute_url` instead of Veta's relative `url()` helper. Set `site_url` in your project so those URLs resolve to your domain; without it, assets fall back to root-relative paths. --- # Components Vara includes a deliberately small set of components for documentation content and landing pages. They cover the common foundations without preventing your project from adding its own. ## How to use components Use components as custom HTML tags in your Markdown. Vara's generators render Markdown first and then resolve component tags, so components can appear anywhere in a page: ```html ``` Paired components receive their already-rendered inner content: ```html Any Markdown or component output can live here. ``` ### Props Component attributes are strings: - Quote every value. - Booleans use `"true"` and `"false"`. - Repeated records use predictable families such as `item_1_title`, `item_2_title`, and so on. Every component accepts a `class` prop for targeted styling with your own utilities. ## Available components ### Content foundations Small components for use inside documentation and rich text: - [Alert](./alert/) - contextual callouts. - [Badge](./badge/) - compact labels and statuses. - [Button](./button/) - links and native buttons. - [Container](./container/) - constrained content layout. - [Icon](./icon/) - bundled Lucide and Simple Icons. - [Keyboard key](./kbd/) - keyboard shortcuts and key names. ### Landing-page sections Larger sections for composing landing pages: - [Header](./header/) - responsive site navigation. - [Hero](./hero/) - centered or split page introduction. - [Content split](./content-split/) - explanatory copy with supporting media. - [Features](./features/) - reusable feature cards. - [Stats](./stats/) - semantic metrics in cards or a strip. - [FAQ](./faq/) - single-open accordion with composable items. - [Testimonial](./testimonial/) - a focused customer quote. - [Carousel](./carousel/) - a generic slider for any collection of slides. - [Call to action](./cta/) - centered or inline conversion panel. - [Footer](./footer/) - site metadata and secondary navigation. These components intentionally omit product-specific recipes such as pricing, forms, and team grids. Add those in your own `components/` directory when your content model is known. ## Customization Components use Vara's design tokens, so they inherit the site's colors and dark mode automatically. Internal links and assets are resolved with Veta's deployment-aware `url()` helper, which keeps them portable across root domains and deployment subdirectories. --- # Alert Use `` for notes, guidance, warnings, and status feedback. It is static by default; set `role="status"` or `role="alert"` only for content that changes after the page loads. ## Usage ```html ``` ## Preview ## Props | Prop | Type | Default | Description | | --------------- | ------ | ----------- | ----------------------------------------------- | | `title` | string | `""` | Bold heading text. | | `description` | string | `""` | Supporting description. | | `color` | string | `"neutral"` | One of: neutral, info, success, warning, error. | | `icon` | string | auto | Override the icon associated with the color. | | `role` | string | `""` | Optional live-region role: status or alert. | | `heading_level` | string | `"3"` | Semantic title level: 3 or 4. | | `class` | string | `""` | Additional CSS classes. | The `description` prop takes precedence over the paired body. If you omit it, the component renders its inner content instead. ## Colors ## Custom icon Pass any icon name from the bundled icon set to replace the default one: ```html ``` ## Richer content For more than a title and a description, use a paired tag. Its body is rendered as Markdown before it reaches the component: ```html Make sure you have read the [introduction](/docs/). If you already have an account, you can **skip this step**. ``` --- # Badge The `` component renders a compact status label. ## Usage ```html ``` ## Preview ## Props | Prop | Type | Default | Description | | --------- | ------ | ----------- | ----------------------------------------------- | | `text` | string | `""` | Badge text. Falls back to slot content. | | `size` | string | `"md"` | One of: sm, md, lg. | | `variant` | string | `"soft"` | One of: soft, solid, outline. | | `color` | string | `"neutral"` | One of: neutral, info, success, warning, error. | | `class` | string | `""` | Additional CSS classes. | ## Variants ### Soft ### Solid ### Outline ## Sizes ## With a slot Provide a `text` prop or put the label between the tags. Both are equivalent: ```html New ``` --- # Button `` renders an anchor when `href` is present and a native button otherwise. Use links for navigation and buttons for actions. ## Usage ```html ``` ## Preview
## Props | Prop | Type | Default | Description | | ------------ | ------ | ------------ | --------------------------------------------------------- | | `label` | string | slot content | Visible action label. | | `href` | string | `""` | Destination. Its presence selects anchor rendering. | | `target` | string | `""` | Link target, such as `_blank`. | | `type` | string | `"button"` | Native button type. | | `icon_start` | string | `""` | Decorative icon before the label. | | `icon_end` | string | `""` | Decorative icon after the label. | | `size` | string | `"md"` | One of: sm, md, lg. | | `variant` | string | `"solid"` | One of: solid, outline, ghost. | | `color` | string | `"neutral"` | One of: neutral, info, success, warning, error. | | `radius` | string | `"md"` | One of: sm, md, lg, full. | | `full_width` | string | `"false"` | Stretch to the available width. | | `disabled` | string | `"false"` | Disable native buttons or render links non-interactively. | | `class` | string | `""` | Additional CSS classes. | Root-relative `href` values are deployment-aware. New-tab links automatically receive `rel="noopener noreferrer"`. ## Icons Decorative icons can sit on either side of the label: ```html ``` ## Variants
--- # Container `` is the minimal layout primitive for project-specific compositions. It accepts paired content and applies a consistent maximum width. ## Usage ```html Contained content stays readable at every viewport size. ``` ## Preview Contained content stays readable at every viewport size. ## Props | Prop | Type | Default | Description | | --------- | ------ | ---------- | ---------------------------------- | | `size` | string | `"md"` | One of: xs, sm, md, lg, xl, full. | | `padding` | string | `"true"` | Apply standard horizontal padding. | | `align` | string | `"center"` | One of: left, center, right. | | `class` | string | `""` | Additional CSS classes. | ## Sizes | `size` | Maximum width | | ------ | ------------- | | `xs` | 28rem | | `sm` | 48rem | | `md` | 72rem | | `lg` | 80rem | | `xl` | 120rem | | `full` | 100% | The paired body is trusted rendered content. Use it for author-controlled Markdown and component output, not unsanitized external HTML. --- # Icon `` renders an optimized SVG from Vara's icon bundle. Icons are decorative by default; provide `label` only when the icon carries meaning without adjacent text. ## Usage ```html ``` ## Preview ## Props | Prop | Type | Default | Description | | ------- | ------ | ------- | ------------------------------------------------- | | `name` | string | `""` | Bundled icon filename without `.svg`. | | `label` | string | `""` | Accessible name for a meaningful standalone icon. | | `class` | string | `""` | Size, color, and positioning utilities. | ## Accessibility Decorative SVGs are hidden from assistive technology and cannot receive focus. When an icon carries meaning on its own, add a `label` so screen readers announce it. ## Brand icons The bundle includes both Lucide icons and Simple Icons brand marks. When a name exists in both sets, the brand version is prefixed with `si-`: ```html ``` ## Where to find icon names The bundle follows the Lucide and Simple Icons catalogs, and this site ships a searchable explorer of every bundled icon: - [Browse the icon explorer](/icons/) Use the name as shown in the explorer. Remember to prefix a brand icon with `si-` when it shares a name with a Lucide icon. ## Missing icons If an icon is missing, Vara renders a visible error glyph instead of failing the build, so a typo never breaks your site. --- # Keyboard Key Use `` for key names in shortcut instructions. It renders the semantic `` element. ## Usage ```html Press + to search. ``` ## Preview Press + to search. ## Props | Prop | Type | Default | Description | | ------- | ------ | ------------ | ----------------------- | | `text` | string | slot content | Key label. | | `size` | string | `"md"` | One of: sm, md, lg. | | `class` | string | `""` | Additional CSS classes. | ## In a sentence Combined with Markdown, key names read naturally in instructions: ```html Press + + to open the command palette. ``` ## With a slot The label can also be placed between the tags: ```html Press Enter to submit. ``` --- # Header `` provides the site chrome needed by a landing page: responsive branding, desktop and mobile navigation, theme switching, and one primary action. ## Usage ```html ``` ## Preview ## Props | Prop | Type | Default | Description | | ------------- | ------ | ----------- | ------------------------------------------------------ | | `title` | string | site title | Brand title. | | `logo_light` | string | site logo | Logo for light surfaces. | | `logo_dark` | string | site logo | Logo for dark surfaces. | | `logo_alt` | string | title | Accessible logo text when the visible title is hidden. | | `home_href` | string | `"/"` | Brand-link destination. | | `links` | string | `""` | Comma-separated `Label\|href` navigation records. | | `cta_label` | string | `""` | Primary action label. Requires `cta_href`. | | `cta_href` | string | `""` | Primary action destination. | | `cta_variant` | string | `"solid"` | Primary action style. | | `cta_color` | string | `"neutral"` | Primary action color. | | `show_logo` | string | `"true"` | Show the brand logo. | | `show_title` | string | `"true"` | Show the visible brand title. | | `show_theme` | string | `"true"` | Show the theme picker control. | | `sticky` | string | `"false"` | Keep the header at the viewport top. | | `container` | string | `"lg"` | One of: xs, sm, md, lg, xl, full. | | `class` | string | `""` | Additional header classes. | ## Behavior The mobile navigation closes on Escape and on outside clicks. Long logos and titles shrink safely instead of overflowing. The theme picker appears by default. Set `show_theme="false"` when you want a quiet header, and `sticky="true"` to keep the header at the top while scrolling. ## Hiding the logo or the title Sites without a logo can hide it while keeping the title, and logos that already include the title as part of the artwork can hide the title instead: ```html ``` ```html ``` The logo keeps the `logo_alt` text as its accessible name whenever the title is hidden. When both are hidden the header renders without a brand link. ## With a logo Pass logo URLs for light and dark surfaces. When only one is given, it is used for both: ```html ``` --- # Hero `` establishes the page's primary message. Use `layout="centered"` for a focused introduction or the default split layout for supporting media or a concise value panel. ## Usage ```html ``` ## Preview ## Props | Prop | Default | Description | | ---------------------------- | ------------ | ----------------------------------------------------------------- | | `layout` | `"split"` | `split` or `centered`. | | `eyebrow` | `""` | Small label above the title. | | `title` | `""` | The main headline. | | `description` | `""` | Supporting copy below the title. | | `caption` | `""` | Small text under the actions. | | `heading_level` | `"1"` | Title level: 1 or 2. Use `2` when embedded below another heading. | | `primary_label` | `""` | Primary action label. Requires `primary_href`. | | `primary_href` | `""` | Primary action destination. | | `primary_target` | `""` | Primary action link target, such as `_blank`. | | `primary_icon` | `""` | Decorative icon on the primary action. | | `primary_variant` | `"solid"` | Primary action style. | | `primary_color` | `"neutral"` | Primary action color. | | `secondary_label` | `""` | Secondary action label. Requires `secondary_href`. | | `secondary_href` | `""` | Secondary action destination. | | `secondary_target` | `""` | Secondary action link target, such as `_blank`. | | `secondary_icon` | `""` | Decorative icon on the secondary action. | | `secondary_variant` | `"outline"` | Secondary action style. | | `secondary_color` | `"neutral"` | Secondary action color. | | `image_src` | `""` | An image as the supporting media. | | `image_alt` | `""` | Required when `image_src` is set. | | `image_width` | `""` | Optional intrinsic image width. | | `image_height` | `""` | Optional intrinsic image height. | | `panel_icon` | `""` | Icon for the text-panel media variant. | | `panel_title` | `""` | Panel heading. | | `panel_description` | `""` | Panel supporting copy. | | `item_1`, `item_2`, `item_3` | `""` | Panel checklist items. | | `media_position` | `"end"` | `start` or `end`. | | `background` | `"base-100"` | Section surface. | | `container` | `"lg"` | One of: xs, sm, md, lg, xl, full. | | `class` | `""` | Additional section classes. | Actions render only when both their label and destination are present. Attribute text is escaped; use project components for deliberately rich hero copy. ## Centered layout For a focused introduction without supporting media: ```html ``` ## Using an image ```html ``` Hero images load eagerly with a high priority since they sit above the fold. --- # Content Split Use `` for product explanations, benefits, workflows, and other two-column narratives below the hero. ## Usage ```html ``` ## Preview ## Props | Prop | Default | Description | | -------------------------------------- | ------------ | -------------------------------------------------- | | `media_position` | `"end"` | `start` or `end`. | | `eyebrow` | `""` | Small label above the title. | | `title` | `""` | The section heading. | | `description` | `""` | Supporting copy below the title. | | `heading_level` | `"2"` | Section title level: 2 or 3. | | `item_1`, `item_2`, `item_3`, `item_4` | `""` | Semantic checklist items. | | `primary_label` | `""` | Primary action label. Requires `primary_href`. | | `primary_href` | `""` | Primary action destination. | | `primary_target` | `""` | Primary action link target, such as `_blank`. | | `primary_icon` | `""` | Decorative icon on the primary action. | | `primary_variant` | `"solid"` | Primary action style. | | `primary_color` | `"neutral"` | Primary action color. | | `secondary_label` | `""` | Secondary action label. Requires `secondary_href`. | | `secondary_href` | `""` | Secondary action destination. | | `secondary_target` | `""` | Secondary action link target, such as `_blank`. | | `secondary_icon` | `""` | Decorative icon on the secondary action. | | `secondary_variant` | `"outline"` | Secondary action style. | | `secondary_color` | `"neutral"` | Secondary action color. | | `image_src` | `""` | An image as the supporting media. | | `image_alt` | `""` | Required when `image_src` is set. | | `image_width` | `""` | Optional intrinsic image width. | | `image_height` | `""` | Optional intrinsic image height. | | `panel_icon` | `""` | Icon for the text-panel media variant. | | `panel_title` | `""` | Panel heading. | | `panel_description` | `""` | Panel supporting copy. | | `background` | `"base-100"` | Section surface. | | `container` | `"lg"` | One of: xs, sm, md, lg, xl, full. | | `class` | `""` | Additional section classes. | When no image or panel is supplied, the component becomes a single-column content section rather than rendering placeholder UI. ## Using an image ```html ``` Images load lazily and keep their aspect ratio. The panel variant is the simpler choice when you have no image to show. --- # Features `` is the general card collection for capabilities, integrations, resources, and short process summaries. Use project-specific components when records need a richer domain model. ## Usage ```html ``` ## Preview ## Props | Prop | Default | Description | | ---------------------------------- | -------------- | -------------------------------------------------------- | | `eyebrow`, `title`, `description` | `""` | Section introduction. | | `columns` | `"3"` | Two, three, or four desktop columns. | | `item_N_title` | `""` | Required field for each rendered card, from 1 through 6. | | `item_N_description` | `""` | Supporting copy. | | `item_N_icon` | `""` | Decorative bundled icon. | | `item_N_badge` | `""` | Compact metadata label. | | `item_N_href` | `""` | Optional destination. | | `item_N_link_label` | `"Learn more"` | Link label when a destination exists. | | `heading_level` | `"2"` | Section title level: 2 or 3. | | `background`, `container`, `class` | varies | Surface and layout customization. | Cards without links do not present hover behavior. Linked cards expose a visible keyboard focus state. ## With links Give a card a destination and its own link label: ```html ``` --- # Stats Use `` for a small set of measurable outcomes. The component uses a definition list so labels and values remain associated for assistive technology. ## Usage ```html ``` ## Preview ## Props | Prop | Default | Description | | ---------------------------------- | --------- | --------------------------------------- | | `variant` | `"cards"` | `cards` or `strip`. | | `columns` | `"4"` | Two, three, or four desktop columns. | | `stat_N_value` | `""` | Required value for records 1 through 6. | | `stat_N_label` | `""` | Required metric definition label. | | `stat_N_description` | `""` | Optional context. | | `eyebrow`, `title`, `description` | `""` | Section introduction. | | `heading_level` | `"2"` | Section title level: 2 or 3. | | `background`, `container`, `class` | varies | Surface and layout customization. | Values are rendered in a mono typeface so columns of numbers align. Only complete records (value and label together) are rendered. ## Strip variant For a horizontal strip without card surfaces: ```html ``` --- # FAQ `` renders an accordion section. Pair it with `` elements: only one item stays open at a time, and every item body can hold any content, from plain text to other components. ## Usage ```html Yes. The free plan covers a single project with the core features. You can cancel or downgrade from the billing settings. ``` ## Preview Yes. The free plan covers a single project with the core features. You can cancel or downgrade from the billing settings. Team pricing starts at ten seats and includes shared billing. ## FAQ items `` is a single accordion entry. Give it a unique `id` and a `question`, then put any content in the body — paragraphs, lists, alerts, or other components. ```html ``` Only one item inside the same `` stays open at a time. Item questions render as level three headings, below the section title. ## Props ``: | Prop | Default | Description | | ---------------------------------- | --------- | ---------------------------------------- | | `open_first` | `"false"` | Open the first item when the page loads. | | `eyebrow`, `title`, `description` | `""` | Section introduction. | | `heading_level` | `"2"` | Section title level: 2 or 3. | | `background`, `container`, `class` | varies | Surface and layout customization. | ``: | Prop | Default | Description | | ---------- | ------- | -------------------------------------------- | | `id` | `""` | Unique accordion entry identifier. Required. | | `question` | `""` | Question shown in the expandable trigger. | --- # Testimonial `` focuses on one credible statement instead of presenting a dense carousel or decorative quote grid. It uses `figure`, `blockquote`, and `figcaption` semantics. ## Usage ```html ``` ## Preview ## Props | Prop | Default | Description | | ---------------------------------- | ----------------------- | --------------------------------------------------------- | | `quote` | `""` | Testimonial text. | | `author` | `""` | Attribution name. | | `author_role` | `""` | Role or organization. | | `avatar_src` | `""` | Optional avatar URL. | | `avatar_alt` | `""` | Avatar alternative text; keep empty when decorative. | | `avatar_width`, `avatar_height` | `""` | Optional intrinsic image dimensions. | | `author_href` | `""` | Optional link to the author's website or profile. | | `author_href_target` | `"_blank"` | Link target for the author. | | `quote_href` | `""` | Optional link to the original quote. | | `quote_label` | `"View original quote"` | Label for the original-quote link. | | `result_value`, `result_label` | `""` | Optional highlighted outcome; both are required together. | | `background`, `container`, `class` | varies | Surface and layout customization. | Internal author and quote destinations are deployment-aware. New-tab links automatically receive `rel="noopener noreferrer"`. ## Without extras A minimal testimonial needs only a quote and an author: ```html ``` ## With an avatar ```html ``` --- # Carousel `` is a generic slider. Every element inside the paired tag becomes one slide, so it works with existing components such as ``, feature cards, or simple markup. ## Usage ```html ``` ## Preview ## Props | Prop | Type | Default | Description | | ----------------- | ------ | ------------ | ------------------------------------------------- | | `label` | string | `"Carousel"` | Accessible region label. | | `slides_per_view` | string | `"1"` | One, two, or three slides per view at desk width. | | `show_controls` | string | `"true"` | Show the previous and next buttons. | | `show_dots` | string | `"true"` | Show the slide indicator dots. | | `background` | string | `"base-100"` | Section surface. | | `container` | string | `"lg"` | One of: xs, sm, md, lg, xl, full. | | `class` | string | `""` | Additional section classes. | ## Behavior The track uses native scroll snapping and works with touch, trackpad, and keyboard. Controls and dots update from the scroll position, and dots only render when the carousel has more than one slide. Slides per view above one is applied at the desk breakpoint only; on smaller screens each slide stays full width. ## Multiple slides per view ```html
First article
Second article
Third article
``` --- # Call to Action `` provides the final conversion panel for a landing page. Use the centered layout for page endings and the inline layout between longer content sections. ## Usage ```html ``` ## Preview ## Props | Prop | Default | Description | | ------------------- | ------------ | -------------------------------------------------- | | `layout` | `"centered"` | `centered` or `inline`. | | `eyebrow` | `""` | Small label above the title. | | `title` | `""` | The panel heading. | | `description` | `""` | Supporting copy below the title. | | `caption` | `""` | Small text under the actions. | | `heading_level` | `"2"` | Section title level: 2 or 3. | | `primary_label` | `""` | Primary action label. Requires `primary_href`. | | `primary_href` | `""` | Primary action destination. | | `primary_target` | `""` | Primary action link target, such as `_blank`. | | `primary_icon` | `""` | Decorative icon on the primary action. | | `primary_variant` | `"solid"` | Primary action style. | | `primary_color` | `"neutral"` | Primary action color. | | `secondary_label` | `""` | Secondary action label. Requires `secondary_href`. | | `secondary_href` | `""` | Secondary action destination. | | `secondary_target` | `""` | Secondary action link target, such as `_blank`. | | `secondary_icon` | `""` | Decorative icon on the secondary action. | | `secondary_variant` | `"outline"` | Secondary action style. | | `secondary_color` | `"neutral"` | Secondary action color. | | `background` | `"base-100"` | Section surface. | | `container` | `"lg"` | One of: xs, sm, md, lg, xl, full. | | `class` | `""` | Additional section classes. | Actions are omitted unless both label and destination are present, preventing placeholder links from reaching production. ## Inline layout For a compact panel that sits beside longer content: ```html ``` --- # Footer `` supplies a restrained ending for landing pages. It shows your copyright and links, with an optional repository link and a small credit line. ## Usage ```html ``` ## Preview ## Props | Prop | Type | Default | Description | | -------------- | ------ | ---------- | ------------------------------------------------------------------------ | | `copyright` | string | `""` | Optional copyright text. `%year%` (or `% year %`) uses the current year. | | `links` | string | `""` | Comma-separated `Label\|href` records. | | `github_href` | string | `""` | Optional repository destination. | | `github_label` | string | `"GitHub"` | Accessible repository-link label. | | `show_credit` | string | `"true"` | Show the veta and veta-theme-vara credits. | | `container` | string | `"lg"` | One of: xs, sm, md, lg, xl, full. | | `class` | string | `""` | Additional footer classes. | ## The copyright year The `%year%` placeholder is replaced with the current year at build time. It tolerates whitespace (`% year %`) and any casing. Internal links are deployment-aware. The GitHub link opens in a new tab with the appropriate `rel` protection. ## Hiding the credit line The credit line links to the veta and veta-theme-vara repositories. Set `show_credit="false"` when you prefer a fully silent footer: ```html ``` --- # Troubleshooting A few issues come up often enough that it is worth having the answers handy. If your problem is not here, start with the page that covers the feature - most topics in this documentation have a "when it breaks" note near the end. ## The page looks unstyled or blank Check that `veta.yaml` points at the theme's stylesheet: ```yaml tailwindcss: stylesheets: - styles.css minify: true ``` If you created your own `public/styles.css`, make sure it imports the theme's styles first: ```css @import "./styles_vara.css"; ``` ## A component does not render Components are resolved after Markdown, as custom tags. The usual culprits: - The tag name has a typo or does not start with `vara-`. - The component file is not in `components/` with a `.j2` extension. - The tag is inside a fenced code block, where it is shown as code on purpose. - A paired component is missing its closing tag. ## The search dialog reports a configuration error The search dialog shows an error when it cannot load the index. Make sure your generator creates a page with the `vara-docs-search-index` template at `docs_search_index_permalink` (default `/docs/vara-docs-search-index.json`), or disable search with `docs_search: false`. See [Search and LLM output](../fundamentals/search-and-llms/). ## A heading does not appear in the table of contents The TOC is built from the `h2` and `h3` headings that live in the page's prose. Headings inside components are excluded because components render with a `not-prose` marker. Move the heading out of the component if you want it to be navigable. See [vara-docs](../templates/docs/). ## The 404 page does not show The theme generates a static `404.html`. Most static hosts serve it automatically for missing routes; if yours does not, point the host at `404.html` as the custom error page. ## An icon renders a warning glyph The icon name does not match a file in the theme's icon set. Check the spelling, and remember that brand icons use the `si-` prefix when they collide with a Lucide name. See [Icon](../components/icon/). ## A draft page still appears on the site The theme skips pages whose frontmatter has `draft: true`, but only when your generator applies that filter. If you wrote your own generator, add the same `draft` check. See [Page generators](../fundamentals/page-generators/). ## Links look wrong after deploying Set `site_url` to your public origin in `data/site.yaml`. Interactive navigation stays relative, while canonical tags, the sitemap, and LLM output use the absolute base URL. See [Site settings](../fundamentals/site-settings/). ## The year in the footer is not replaced The footer replaces the `%year%` placeholder (with flexible spacing and any casing). If you wrote your own footer, use the `vara_component_footer_copyright` function, which reads the year from the theme data. See [Footer](../components/footer/).