# Voxx

A zero-friction CMS for you and your agents.

---

# Introduction

Source: https://voxx.prudentbird.com/docs
Date: 1970-01-01T00:00:00.000Z

Voxx is a zero-friction, file-based CMS. You point it at a folder of markdown
and it ships a **blog**, a **docs site**, or a **changelog** — no database, no
admin UI, no lock-in. Every page is a plain `.md` file with a little YAML
frontmatter, so humans and agents can read and write your content with the
same tools they use for code.

This page — and every page in this section — is rendered by Voxx from a
markdown file in the [repository](https://github.com/prudentbird/voxx). The
sidebar, the "On this page" widget, the prev/next pager, the sitemap, and the
`llms.txt` behind this site all come from the engine described here.

## Why files

Prose wants to be prose — headings, paragraphs, the occasional list — not rows
in a database. Keeping each page as one file means you can:

- grep, diff, branch, and review content exactly like code
- edit anywhere, in any editor, offline
- let an agent discover, read, and write pages directly — no API tokens, no
  custom integration

A folder of files will outlive every CMS.

## One engine, three surfaces

Voxx renders three kinds of content, all through the same pipeline:

| Surface   | Shape              | Convention                                        |
| --------- | ------------------ | ------------------------------------------------- |
| Blog      | Flat, newest-first | `2026-06-11-hello.md` date-stamps a post          |
| Docs      | Ordered tree       | Folders become sections; `01-` prefixes pin order |
| Changelog | Versioned timeline | `1.4.0.md` becomes a release with a stable anchor |

Need more than one on the same site? Mount them side by side with
[collections](/docs/reference/collections).

## What you get out of the box

- GitHub-flavored markdown with [Shiki](https://shiki.style) syntax
  highlighting (light **and** dark)
- An "On this page" table of contents built from your headings
- Open Graph, Twitter cards, type-aware JSON-LD, and canonical URLs
- `sitemap.xml`, RSS, and `llms.txt`, each toggled per surface
- Styles that [inherit your design tokens](/docs/reference/theming) — shadcn
  variables just work

## How the pieces fit

- **[`@prudentbird/voxx-core`](/docs/reference/core-api)** is the portable engine: plain
  async functions in, structured data out. It has no opinion about your
  framework.
- **The [`voxx` CLI](/docs/reference/cli)** scaffolds a surface into your
  Next.js app — real, editable files you own — or renders a self-contained
  static site for any other stack.

Ready? Head to [Getting started](/docs/getting-started).

---

# Getting started

Source: https://voxx.prudentbird.com/docs/getting-started
Date: 1970-01-01T00:00:00.000Z

Every Voxx setup starts the same way — pick a surface, run one command:

```bash
npx @prudentbird/voxx init            # a blog
npx @prudentbird/voxx init docs       # a docs site
npx @prudentbird/voxx init changelog  # a release-notes page
```

`voxx init` looks at the directory you run it in and does the right thing:

- **Next.js app detected** — it scaffolds routes under `app/` (or `src/app/`),
  writes a `voxx.json` and sample content, and wraps your `next.config` with
  [`withVoxx`](#rendering-modes) when it can do so safely. The generated
  components live in a `_voxx/` folder inside the mounted route — they're plain
  files you own and restyle.
- **No Next.js** — it asks whether you want a static site (rendered with
  `voxx build`) or a fresh app via `create-next-app`, then scaffolds into
  your choice.

Then install the engine the scaffolded files import:

```bash
npm i @prudentbird/voxx-core
```

Set `site.url` in `voxx.json`, start your dev server, and open the mount path
(`/blog`, `/docs`, or `/changelog`). That's the whole loop: write markdown,
refresh, publish on deploy.

## Common flags

Every preset accepts the same flags:

| Flag            | Default       | What it does                             |
| --------------- | ------------- | ---------------------------------------- |
| `--base /notes` | `/<preset>`   | Mount path — scaffolded routes follow it |
| `--dir content` | `content`     | Where your markdown lives                |
| `--app src/app` | auto-detected | The Next.js app directory                |
| `--force`       | off           | Overwrite files that already exist       |

## Rendering modes

Voxx adapts to the host app instead of reconfiguring it. The default data layer
memoizes filesystem reads for the life of each deploy, so pages prerender and
content reads cost nothing at request time. No whole-app rendering switch comes
with it, and existing routes keep behaving exactly as they did.

`withVoxx` wires only the serverless plumbing every Voxx app needs. It keeps
`@prudentbird/voxx-core` external and traces `voxx.json` plus your content
directories into the serverless bundle so runtime reads resolve. It never sets
`cacheComponents`, so how the rest of your app renders stays your call:

```ts
import type { NextConfig } from "next";
import { withVoxx } from "@prudentbird/voxx-core/next";

const nextConfig: NextConfig = {};

export default withVoxx(nextConfig);
```

Apps that already enable Next's Cache Components get a matching data layer built
on the `"use cache"` directive, pinned to the `max` lifetime so it refreshes
only on rebuild. `voxx init` detects `cacheComponents: true` in your
`next.config` and scaffolds that variant automatically. Pass
`--cache-components` or `--no-cache-components` to choose the variant yourself.

On Next 16+, `voxx init` wraps your config when it has a recognizable shape.
Otherwise it prints the snippet to add yourself.

## Pick your surface

Each surface has its own one-page guide:

- [Start a blog](/docs/getting-started/blog)
- [Start a docs site](/docs/getting-started/docs)
- [Start a changelog](/docs/getting-started/changelog)
- [Static sites](/docs/getting-started/static-sites) — any stack, no framework

---

# Start a blog

Source: https://voxx.prudentbird.com/docs/getting-started/blog
Date: 1970-01-01T00:00:00.000Z

From the root of your Next.js app:

```bash
npx @prudentbird/voxx init
npm i @prudentbird/voxx-core
```

This writes:

```
voxx.json                          # config (autocompleted via JSON schema)
content/2026-01-15-hello-world.md  # a sample post (date prefix orders files; the URL uses the slug)
app/blog/page.tsx                  # the /blog index — lists all posts
app/blog/[slug]/page.tsx           # one post (+ metadata + static params)
app/blog/layout.tsx                # imports the Voxx stylesheet
app/blog/_voxx/*                   # data layer + components, yours to edit
app/sitemap.ts                     # sitemap.xml
app/robots.ts                      # robots.txt
app/blog/rss.xml/route.ts          # /blog/rss.xml
app/llms.txt/route.ts              # /llms.txt
app/llms-full.txt/route.ts         # /llms-full.txt
```

Set `site.url` in `voxx.json`, run your dev server, and open `/blog`.

## Write a post

Drop a `.md` file in your content folder, or let the CLI do it:

```bash
npx @prudentbird/voxx new "Why files win"
```

That creates `content/2026-06-11-why-files-win.md` with frontmatter filled
in. The date prefix keeps posts sorted by creation date on disk and doubles
as the publish date when frontmatter doesn't say otherwise. Prefer flat
names? Pass `--flat`.

A post is just this:

```markdown
---
title: Why files win
description: A short summary used for SEO and excerpts.
date: 2026-06-11
tags: [craft, tooling]
---

Prose wants to be prose — not rows in a database. Just write and commit.
```

`title` is the only required field — see the
[frontmatter reference](/docs/writing/frontmatter) for everything else.

## What blogs get by default

Blogs ship with every feature flag on: table of contents, RSS, sitemap,
`llms.txt`, tags, and reading time. Turn any of them off in
[`voxx.json`](/docs/reference/configuration):

```jsonc
{ "features": { "readingTime": false } }
```

Posts are sorted newest-first. Drafts (`draft: true`) stay out of the index,
the feeds, and the sitemap until you flip them or build with drafts enabled.

---

# Start a docs site

Source: https://voxx.prudentbird.com/docs/getting-started/docs
Date: 1970-01-01T00:00:00.000Z

From the root of your Next.js app:

```bash
npx @prudentbird/voxx init docs
npm i @prudentbird/voxx-core
```

This writes:

```
voxx.json                        # config, with type: "docs"
content/index.md                 # the docs landing page
content/01-getting-started/      # a sample section
  index.md                       #   the section's landing page
  01-installation.md             #   an ordered page inside it
app/docs/[[...slug]]/page.tsx    # one route renders the whole tree
app/docs/layout.tsx              # the docs shell — sidebar, theme toggle
app/docs/_voxx/*                 # nav, drawer, pager, TOC — yours to edit
app/sitemap.ts                   # sitemap.xml
app/llms.txt/route.ts            # /llms.txt
instrumentation.ts               # dev content watcher (live reload)
```

Open `/docs` and you'll see the sidebar built from your folders, a prev/next
pager that walks the tree in order, and an "On this page" widget built from
your headings. The shell is self-contained — your site title at the top of
the sidebar, a theme toggle pinned to the bottom, a drawer on mobile. See
[Layouts](/docs/reference/layouts) for how it's arranged and how to keep
your app's own navbar out of it.

## The conventions

Three rules drive the whole thing:

1. **Folders become sections.** `content/guides/deploy.md` ships at
   `/docs/guides/deploy` and nests under a "Guides" node in the sidebar.
2. **`index.md` lands a section.** It gives the section node its title and
   URL; without one the section is a label in the sidebar. A root `index.md`
   is the docs landing page itself.
3. **Numeric prefixes pin order without touching URLs.** `01-install.md`
   ships at `/docs/install`; the `01-` only decides where it sorts. The same
   works on folders: `02-writing/` → `/docs/writing`.

The full details — ordering precedence, slugs, nesting — live in
[Organizing docs](/docs/writing/organizing-docs).

## Add a page

```bash
npx @prudentbird/voxx new "Deploying" --section guides --order 3
```

creates `content/guides/03-deploying.md`. Or just create the file — the CLI
is a convenience, never a requirement.

## Live reload

Editing a `.md` file updates the page in `next dev` without a manual refresh.
Voxx reads content off the filesystem rather than importing it, so Next's HMR
does not see those edits on its own.

The default static data layer reads fresh content in development, so edits show
up on the next request with nothing extra to run.

Cache Components mode holds content in the cache across requests, so the
scaffolded `instrumentation.ts` starts a dev-only watcher (shipped in
`@prudentbird/voxx-core`) that bumps `_voxx/content-version.ts` whenever content
or `voxx.json` changes:

```ts
export async function register() {
  if (process.env.NEXT_RUNTIME !== "nodejs") return;
  const { registerContentWatcher } = await import("@prudentbird/voxx-core");
  await registerContentWatcher();
}
```

The cached `data.ts` threads that version into its `"use cache"` calls, so a
bump both refreshes the open page and busts the content cache. It runs in
development only; production builds are untouched. Delete `instrumentation.ts`
to opt out.

## What docs get by default

Docs sites default to: table of contents, sitemap, and `llms.txt` **on**;
RSS, tags, and reading time **off** — those are blog concerns.
Any flag can be overridden in [`voxx.json`](/docs/reference/configuration).

This very site is the output of these conventions — the sidebar to your left
is a folder listing.

---

# Start a changelog

Source: https://voxx.prudentbird.com/docs/getting-started/changelog
Date: 1970-01-01T00:00:00.000Z

From the root of your Next.js app:

```bash
npx @prudentbird/voxx init changelog
npm i @prudentbird/voxx-core
```

This writes:

```
voxx.json                        # config, with type: "changelog"
content/0.1.0.md                 # a sample release
app/changelog/page.tsx           # the timeline — all releases, one page
app/changelog/layout.tsx         # imports the Voxx stylesheet
app/changelog/_voxx/*            # the release list, yours to edit
app/changelog/rss.xml/route.ts   # /changelog/rss.xml — a release feed
app/llms.txt/route.ts            # /llms.txt
app/llms-full.txt/route.ts       # /llms-full.txt
```

Open `/changelog` for a single page of releases, newest first, each with a
stable anchor link you can share (`/changelog#1-4-0`).

## Cut a release

```bash
npx @prudentbird/voxx new "1.4.0"
```

creates `content/1.4.0.md`, pre-dated today:

```markdown
---
title: v1.4.0
version: "1.4.0"
date: 2026-06-11
---

### Added

- Collections: mount a blog, docs, and changelog on one site.
```

The version comes from the filename (`1.4.0.md`, `v2.0.0-beta.1.md` both
work) or from `version:` in frontmatter — frontmatter wins. The body is
ordinary markdown; headings like `### Added` / `### Fixed` are a convention,
not a requirement.

## What changelogs get by default

Changelogs default to: RSS and `llms.txt` **on** (release feeds are useful);
table of contents, sitemap, tags, and reading time **off** —
one timeline page doesn't need them. Override anything in
[`voxx.json`](/docs/reference/configuration).

---

# Static sites

Source: https://voxx.prudentbird.com/docs/getting-started/static-sites
Date: 1970-01-01T00:00:00.000Z

Voxx doesn't require Next.js — or any framework. `voxx build` renders your
whole collection to plain HTML and CSS:

```bash
npx @prudentbird/voxx init          # choose "static site" when asked
npx @prudentbird/voxx build         # -> dist/
```

The output depends on your content type:

- **Blog** — an index page plus one page per post
- **Docs** — every page with the sidebar, pager, and TOC baked in; if there's
  no root `index.md`, Voxx emits a landing page so the base path isn't a 404
- **Changelog** — the release timeline on a single page

Alongside the pages you get `rss.xml`, `sitemap.xml`, `robots.txt`,
`llms.txt`, and `llms-full.txt`, following the same
[feature flags](/docs/reference/configuration#features) as everything
else, plus the Voxx stylesheet under `dist/_voxx/`. Images and other
non-markdown files in your content folder are copied through, and relative
references like `![diagram](./diagram.png)` are resolved to where they
land. Multi-collection configs build every collection in one pass.

```bash
npx @prudentbird/voxx build --out public    # somewhere other than ./dist
npx @prudentbird/voxx build --drafts        # include draft pages
```

Preview locally with the built-in dev server — it rebuilds on change and
includes drafts by default:

```bash
npx @prudentbird/voxx dev                   # http://localhost:4321
```

Or serve the built folder with anything that can serve files:

```bash
npx serve dist
```

## Bring your own framework

The static builder and the Next.js scaffolding are both thin layers over
[`@prudentbird/voxx-core`](/docs/reference/core-api), whose public API is plain async
functions:

```ts
import { getPosts, buildSeo, renderRss } from "@prudentbird/voxx-core";

const posts = await getPosts(); // reads voxx.json, returns Post[]
```

If you're on Astro, Remix, SvelteKit, or a hand-rolled build script, call
the engine directly — every `Post` carries rendered HTML, a TOC, SEO-ready
fields, and its final URL.

---

# Writing content

Source: https://voxx.prudentbird.com/docs/writing
Date: 1970-01-01T00:00:00.000Z

Everything Voxx publishes is a markdown file: YAML frontmatter on top, prose
below. There's no editor to learn and no required workflow — create files by
hand, with `voxx new`, or let an agent write them.

```markdown
---
title: Hello, world
description: An optional summary used for SEO and excerpts.
---

## Why files win

Prose wants to be prose. Just write and commit.
```

## What the renderer gives you

Voxx renders GitHub-flavored markdown — tables, task lists, strikethrough,
autolinks — and adds:

- **Syntax highlighting** via Shiki, with paired light/dark themes
- **Heading anchors** — every heading gets an id and a self-link, so deep
  links work with JavaScript disabled
- **A table of contents** collected from your `h2`/`h3` headings, which
  powers the "On this page" widget
- **Excerpts and reading time**, derived from the body unless frontmatter
  says otherwise

Raw HTML passes through untouched, so `<details>`, `<video>`, and custom
embeds work inside markdown. Only `.md` files are picked up — there's no
MDX compiler, so `.mdx` is deliberately ignored rather than silently
stripped of its JSX.

## Filename conventions

Filenames carry meaning, and each surface reads them differently:

| Surface   | Filename              | Meaning                               |
| --------- | --------------------- | ------------------------------------- |
| Blog      | `2026-06-11-hello.md` | Date-stamps the post; slug is `hello` |
| Docs      | `01-install.md`       | Pins sidebar order; slug is `install` |
| Changelog | `1.4.0.md`            | Names the release version             |

Frontmatter always wins over the filename — an explicit `date:`, `order:`,
`slug:`, or `version:` overrides whatever the name implies.

## `voxx new`

The CLI knows which surface it's in (from `voxx.json`) and creates the right
kind of file:

```bash
voxx new "Why files win"                       # blog: 2026-06-11-why-files-win.md
voxx new "Deploying" --section guides --order 3  # docs: guides/03-deploying.md
voxx new "1.4.0"                               # changelog: 1.4.0.md
```

If a slug is already taken, `voxx new` suggests a free one instead of
overwriting. It never touches existing files.

## In this section

- [Frontmatter](/docs/writing/frontmatter) — every field, and what's derived
  when you leave it out
- [Organizing docs](/docs/writing/organizing-docs) — folders, ordering, and
  `index.md`
- [Writing releases](/docs/writing/releases) — version files and the timeline

---

# Frontmatter

Source: https://voxx.prudentbird.com/docs/writing/frontmatter
Date: 1970-01-01T00:00:00.000Z

Frontmatter is the YAML block between `---` fences at the top of a file.
Only `title` is required — everything else is optional, validated, and
falls back to something sensible.

```yaml
---
title: Hello, world
description: An optional summary used for SEO and excerpts.
date: 2026-06-10
updated: 2026-06-11
slug: hello-world
tags: [css, ui]
category: Craft
order: 2
version: "1.4.0"
draft: false
image: /og/hello.png
author: { name: Jane Doe, url: https://jane.example }
excerpt: A hand-written excerpt, if the derived one won't do.
---
```

## Field reference

| Field         | Type     | Notes                                                                                     |
| ------------- | -------- | ----------------------------------------------------------------------------------------- |
| `title`       | string   | **Required.** The page heading and `<title>`                                              |
| `description` | string   | Used for SEO and list excerpts                                                            |
| `date`        | date     | Publish date — see [precedence](#how-dates-are-resolved)                                  |
| `updated`     | date     | Shown as modified time in SEO output and sitemaps                                         |
| `slug`        | string   | Overrides the filename-derived slug                                                       |
| `tags`        | string[] | Blog taxonomy; flows into RSS categories and SEO keywords                                 |
| `category`    | string   | Passthrough: exposed on `Post` for your own components; no built-in Voxx surface reads it |
| `order`       | number   | Manual position in docs navigation                                                        |
| `version`     | string   | Release version (changelog) — overrides the filename                                      |
| `draft`       | boolean  | Hidden everywhere until published (default `false`)                                       |
| `image`       | string   | Social/OG image; falls back to `seo.defaultImage`                                         |
| `author`      | author   | One or more authors — see [Authors](#authors). Overrides `site.author` for this page      |
| `excerpt`     | string   | Overrides the derived excerpt                                                             |

Unknown keys are ignored, not errors — annotate your files however you like.
An empty value (`description:` with nothing after it) is treated as absent.
Invalid values fail loudly with the file's name in the message.

## How dates are resolved

Voxx tries three sources, in order:

1. `date:` in frontmatter
2. A `YYYY-MM-DD-` filename prefix (`2026-06-10-hello.md`)
3. The file's creation time on disk

So a blog can be nothing but date-prefixed files with `title:` — Voxx fills
in the rest.

## Authors

`author` accepts a bare name, an object with an optional `url`, or a list
mixing both:

```yaml
author: Jane Doe
# or
author: { name: Jane Doe, url: https://jane.example }
# or several
author:
  - { name: Jane Doe, url: https://jane.example }
  - Sam Rivera
```

Each author renders as a byline on the post (names with a `url` become
links) and flows into Open Graph and JSON-LD metadata. When a post sets no
`author`, Voxx falls back to `site.author` from `voxx.json`.

## Drafts

`draft: true` keeps a page out of everything — lists, feeds, sitemaps,
`llms.txt`, and its own URL. Nobody can read a draft by guessing the link.
To preview drafts, use [`voxx dev`](/docs/reference/cli#voxx-dev) (which
includes them by default), pass `--drafts` to
[`voxx build`](/docs/reference/cli#voxx-build), or set
`content.drafts: true` while developing.

To publish a draft's page for sharing while keeping it out of lists and
feeds, set the collection's [`drafts: "unlisted"`](/docs/reference/configuration#content)
instead — the page builds and is reachable by URL, but stays hidden.

## Derived values

When you don't provide them, Voxx computes:

- **Slug** — from the filename, after stripping date/order prefixes, then
  slugified (`Älä Hätäile.md` → `ala-hataile`)
- **Excerpt** — the first ~180 characters of body text, with code blocks,
  headings, images, and markup stripped
- **Reading time** — at 200 words per minute, minimum one minute

---

# Organizing docs

Source: https://voxx.prudentbird.com/docs/writing/organizing-docs
Date: 1970-01-01T00:00:00.000Z

A docs collection mirrors its folder. There's no separate navigation config
to maintain: the tree on disk _is_ the sidebar, the URL structure, and the
prev/next order.

```
content/docs/
  index.md                     → /docs               (the landing page)
  01-getting-started/
    index.md                   → /docs/getting-started
    01-blog.md                 → /docs/getting-started/blog
    02-docs.md                 → /docs/getting-started/docs
  02-writing/
    index.md                   → /docs/writing
    01-frontmatter.md          → /docs/writing/frontmatter
  03-reference/                  (no index.md — a label-only section)
    01-configuration.md        → /docs/reference/configuration
```

That's this site's actual layout — compare it with the sidebar.

## Ordering

Within each level, pages sort by explicit order first, then alphabetically.
"Explicit order" comes from, in order of precedence:

1. `order:` in frontmatter
2. A numeric filename prefix: `01-install.md`, `2_setup.md`, `10.faq.md`
   (up to four digits, separated by `-`, `_`, or `.`)
3. For an `index.md`, the prefix on its folder (`01-getting-started/`)

Prefixes never reach the URL — `01-install.md` ships at `…/install`. Pages
without any order sort alphabetically after the ordered ones, so you can be
strict where order matters and lazy where it doesn't.

## `index.md`

An `index.md` represents its folder:

- **In a section** — it becomes the section's landing page, and gives the
  sidebar node its title and URL.
- **At the root** — it becomes the collection's landing page, served at the
  base path itself (`/docs`).
- **Absent** — the section still appears in the sidebar, but as a plain
  label (the folder name, humanized: `03-reference/` → "Reference"). On
  static builds, a missing root index gets a generated landing page so the
  base path isn't a 404.

## Titles and the sidebar

Sidebar entries use each page's `title:`. Only the label-only sections fall
back to humanized folder names. The prev/next pager at the bottom of every
page walks the same depth-first order the sidebar shows.

## Nesting

Trees can nest as deep as you need — every folder level becomes a URL
segment and a sidebar level. In practice two levels (section / page) read
best; if you're reaching for a third, consider whether it should be a new
section instead.

---

# Writing releases

Source: https://voxx.prudentbird.com/docs/writing/releases
Date: 1970-01-01T00:00:00.000Z

A changelog collection is a folder of release files. Each file is one
release; the page at the base path renders them all as a single timeline,
newest first.

```
content/changelog/
  1.4.0.md          → /changelog#1-4-0
  1.3.0.md          → /changelog#1-3-0
  v1.3.0-beta.1.md  → /changelog#v1-3-0-beta-1
```

## Naming releases

The version comes from the filename when it looks like one — `1.4.0.md`,
`v2.0.md`, `2.0.0-rc.1.md` all parse — or from frontmatter, which always
wins:

```markdown
---
title: The collections release
version: "1.4.0"
date: 2026-06-11
---

### Added

- Collections: mount a blog, docs, and changelog on one site.

### Fixed

- Order prefixes no longer leak into URLs.
```

Quote the version (`"1.4.0"`) so YAML doesn't read it as a number. `title`
is still required; if you have nothing better, `voxx new "1.4.0"` defaults
it to `v1.4.0`.

## Dates drive the timeline

Releases sort by `date`, newest first — version numbers name releases but
don't order them. Give every release an explicit date; "what shipped when"
is the whole point of a changelog.

## Anchors

Every release gets a stable anchor derived from its slug, so you can link
to `/changelog#1-4-0` from release tweets, commit messages, or upgrade
guides and the link keeps working as new releases land above it.

## Body conventions

The body is ordinary markdown. Grouping changes under `### Added`,
`### Changed`, `### Fixed`, and `### Removed` (_à la_
[Keep a Changelog](https://keepachangelog.com)) reads well in the timeline,
but Voxx doesn't enforce it — paragraphs, bullets, even images all render
fine.

If the changelog shares a site with other surfaces, see
[Collections](/docs/reference/collections).

---

# Configuration

Source: https://voxx.prudentbird.com/docs/reference/configuration
Date: 1970-01-01T00:00:00.000Z

All configuration lives in one file, `voxx.json`, at the root of your
project. Only `site.title` and `site.url` are required; everything else has
a default — and several defaults are [type-aware](#type-aware-defaults).

```jsonc
{
  "$schema": "./node_modules/@prudentbird/voxx-core/voxx.schema.json",
  "site": {
    "title": "Acme",
    "description": "Tools for people who ship.",
    "url": "https://acme.dev",
    "author": { "name": "Acme", "url": "https://acme.dev/about" },
    "locale": "en-US",
  },
  "content": {
    "type": "docs", // "blog" | "docs" | "changelog"
    "dir": "content/docs",
    "basePath": "/docs",
    "drafts": false,
  },
  "theme": {
    "preset": "default",
    "css": null,
    "codeTheme": "github-light github-dark",
  },
  "features": {
    "toc": true,
    "rss": true,
    "sitemap": true,
    "llmsTxt": true,
    "tags": true,
    "readingTime": true,
  },
  "seo": {
    "openGraph": true,
    "twitter": "@acme",
    "jsonLd": true,
    "defaultImage": "/og.png",
  },
}
```

The `$schema` line gives you autocomplete and validation in any
JSON-schema-aware editor. It's generated from the same schema that validates
the file at runtime, so the two can't drift.

## `site`

| Key           | Default   | Notes                                                      |
| ------------- | --------- | ---------------------------------------------------------- |
| `title`       | —         | **Required.** Site name in feeds, SEO, and JSON-LD         |
| `url`         | —         | **Required.** Origin for canonical URLs and absolute links |
| `description` | `""`      | Used in feeds, `llms.txt`, and index pages                 |
| `author`      | —         | `{ name, url? }` — default author for SEO output           |
| `locale`      | `"en-US"` | Open Graph locale and date formatting                      |

## `content`

The single-collection shorthand: one content type, one folder, one mount
path.

| Key        | Default          | Notes                                             |
| ---------- | ---------------- | ------------------------------------------------- |
| `type`     | `"blog"`         | `"blog"`, `"docs"`, or `"changelog"`              |
| `dir`      | `"content/blog"` | Markdown folder, resolved relative to `voxx.json` |
| `basePath` | `"/blog"`        | URL prefix the collection is mounted at           |
| `drafts`   | `false`          | Draft visibility — see below                      |

`drafts` is tri-state:

- `false` (default) — drafts are excluded everywhere.
- `true` — drafts are built and listed like published posts. Useful while
  developing, but a footgun in production; `voxx build` warns when it's set.
- `"unlisted"` — drafts are built and reachable by URL (for sharing a
  preview link), but hidden from listings, RSS, sitemap, and `llms.txt`.

To mount more than one surface, use `collections` instead — it replaces
`content` entirely. See [Collections](/docs/reference/collections).

## `features`

Each flag turns one output on or off: the "On this page" TOC, RSS, the
sitemap, `llms.txt`, tags, and reading time.

`tags` is presentation-only: it gates the tag chips on post cards (the
static builder's index page and the scaffolded blog post list) and nothing
else. RSS `<category>` elements, Open Graph article tags, and JSON-LD
keywords always flow from frontmatter
[`tags`](/docs/writing/frontmatter#field-reference), whether the flag is on
or off.

### Type-aware defaults

Defaults follow your content type, so each surface starts sensible without
any flags:

| Flag          | blog | docs    | changelog |
| ------------- | ---- | ------- | --------- |
| `toc`         | on   | on      | **off**   |
| `rss`         | on   | **off** | on        |
| `sitemap`     | on   | on      | **off**   |
| `llmsTxt`     | on   | on      | on        |
| `tags`        | on   | **off** | **off**   |
| `readingTime` | on   | **off** | **off**   |

An explicit value in `voxx.json` always wins. With multiple collections, the
defaults follow the _first_ collection's type.

## `theme` and `seo`

Covered in their own pages: [Theming](/docs/reference/theming) and
[SEO and feeds](/docs/reference/seo).

## Loading rules

`voxx.json` is resolved from the directory you run in (or `cwd`/`path`
options on the [core API](/docs/reference/core-api)). Relative `dir` paths
resolve against the config file's directory. Validation errors name the
offending field; a missing config tells you to run `voxx init`.

---

# Collections

Source: https://voxx.prudentbird.com/docs/reference/collections
Date: 1970-01-01T00:00:00.000Z

One site often needs more than one surface — product docs next to a blog
next to release notes. `collections` mounts several folders at once, each
with its own type, directory, and base path:

```jsonc
{
  "site": { "title": "Acme", "url": "https://acme.dev" },
  "collections": [
    { "name": "blog" },
    { "name": "docs", "type": "docs" },
    { "name": "releases", "type": "changelog", "basePath": "/changelog" },
  ],
}
```

When `collections` is present it replaces the `content` block entirely.

## Per-collection defaults

Each entry fills itself in from its `name` and `type`:

| Key        | Default          | Example above              |
| ---------- | ---------------- | -------------------------- |
| `name`     | the `type`       | `"releases"`               |
| `type`     | `"blog"`         | `"changelog"`              |
| `dir`      | `content/<name>` | `content/releases`         |
| `basePath` | `/<name>`        | overridden to `/changelog` |
| `drafts`   | `false`          | —                          |

`drafts` is per-collection and tri-state — `false`, `true`, or `"unlisted"`
(built and reachable by URL but hidden from listings and feeds). See
[`content.drafts`](/docs/reference/configuration#content) for the full
breakdown.

So `{ "name": "docs", "type": "docs" }` reads `content/docs/` and mounts at
`/docs` with zero further config.

## The first collection is the default

The first entry backs the single-collection API: `getPosts()` with no
arguments reads it, and the type-aware
[feature defaults](/docs/reference/configuration#type-aware-defaults) follow
its type. Reach the others by name:

```ts
import { getPosts, getPost } from "@prudentbird/voxx-core";

const posts = await getPosts(); // first collection
const docs = await getPosts({ collection: "docs" }); // by name
const page = await getPost("guides/deploy", { collection: "docs" });
```

Asking for a name that isn't defined fails with a message listing the
collections that are.

## Routes per collection

Each collection is its own surface, so each gets its own routes. Run
`voxx init` once per surface with matching `--base` flags, or hand-wire
extra routes against the core API — the scaffolded files are small and make
a good template. Feeds are per-surface too: pass the right collection's
posts to `renderRss` or `renderLlmsTxt` and mount the route where it
belongs (`/blog/rss.xml`, `/changelog/rss.xml`, …).

For static sites, [`voxx build`](/docs/reference/cli#voxx-build) handles
all of this itself: it renders every collection, writes a feed per blog or
changelog surface under its base path, and emits one combined
`sitemap.xml`, `robots.txt`, and sectioned `llms.txt` at the root.

---

# Theming

Source: https://voxx.prudentbird.com/docs/reference/theming
Date: 1970-01-01T00:00:00.000Z

Voxx ships **element-only** styles: prose, code blocks, the TOC, the docs
sidebar, the pager. It never styles your page chrome, and it never defines
your design tokens — it _reads_ them.

## Token inheritance

Every color in `voxx.css` reads a host token first and falls back to a
built-in default:

```css
.voxx-prose {
  color: var(--foreground, var(--voxx-fg));
}
```

- **Your app defines shadcn-style tokens** (`--background`, `--foreground`,
  `--border`, `--primary`, …) — Voxx matches your design automatically.
  Restyle every page at once by editing your `globals.css`.
- **It doesn't** — Voxx's own light/dark fallbacks keep things looking good.
  `voxx init` detects this case and drops in `voxx-globals.css`, a
  copy-from token set you can grow into.

Dark mode follows the shadcn convention: a `.dark` class on an ancestor
wins, `prefers-color-scheme` covers the rest.

## The stylesheet

The scaffolded layout imports the stylesheet like any other file:

```tsx
import "@prudentbird/voxx-core/theme/voxx.css";
```

(`voxx init` copies it into your app's `_voxx/` folder instead, so you can
edit it line by line; `voxx build` ships it under `dist/_voxx/`.) All
selectors are flat, prefixed classes — `.voxx-prose`, `.voxx-toc`,
`.voxx-nav`, `.voxx-pager` — easy to override from your own CSS, no
specificity battles.

## Code highlighting

Code blocks are highlighted at build time by [Shiki](https://shiki.style).
`theme.codeTheme` takes one theme, or a light/dark pair that switches with
your site's mode:

```jsonc
{ "theme": { "codeTheme": "vitesse-light vitesse-dark" } }
```

Any [Shiki theme name](https://shiki.style/themes) works. Because
highlighting happens at build time, no highlighter ships to the client.

## Custom stylesheet

To take over completely, point `theme.css` at your own file and import that
from your layout instead. The rendered markup is stable, semantic HTML with
the class names above — your stylesheet has everything it needs to hook
into.

---

# SEO and feeds

Source: https://voxx.prudentbird.com/docs/reference/seo
Date: 1970-01-01T00:00:00.000Z

Publishing well is most of why a CMS exists, so Voxx treats SEO as output,
not homework. Every page gets a complete, framework-neutral SEO payload;
feeds and indexes come from the same data.

## Per-page metadata

`buildSeo(post, config)` assembles everything a `<head>` needs:

- **Canonical URL** — `site.url` + the post's URL
- **Open Graph** — title, description, images, locale, published/modified
  times, authors, and tags
- **Twitter card** — `summary_large_image`, with `seo.twitter` as the
  site/creator handle
- **JSON-LD** — typed per surface: `BlogPosting` for blogs, `TechArticle`
  for docs, `Article` for changelog entries

Descriptions fall back from `description:` to the derived excerpt; images
fall back from `image:` to `seo.defaultImage`; authors fall back from
`author:` to `site.author`. In the Next.js scaffold, a small `toMetadata`
helper maps this payload onto `generateMetadata` — on other stacks, render
the same fields into your own templates.

Toggle the pieces in `voxx.json`:

```jsonc
{
  "seo": {
    "openGraph": true,
    "twitter": "@acme",
    "jsonLd": true,
    "defaultImage": "/og.png",
  },
}
```

## RSS

`renderRss(posts, config)` produces an RSS 2.0 feed with stable GUIDs,
tags as categories, full HTML bodies in `content:encoded`, and a
self-referencing atom link. The feed lives under its collection's base
path — `/blog/rss.xml`, `/changelog/rss.xml` — in both the scaffold and
static builds, one per surface. On by default for blogs and changelogs (a
release feed is a nice thing to subscribe to).

## Sitemap and robots.txt

`renderSitemap(posts, config)` covers the collection index and every page,
with `lastmod` from `updated:` falling back to `date:`. The Next.js
scaffold uses `app/sitemap.ts` instead, feeding the same data through
Next's metadata route. Alongside it, `renderRobotsTxt(config)` (or the
scaffolded `app/robots.ts`) emits a `robots.txt` that points crawlers at
the sitemap.

## llms.txt

Voxx generates an [`llms.txt`](https://llmstxt.org) — a markdown index of
your site (title, summary, and a linked, described list of every page) that
agents can fetch to orient themselves before crawling. `llms-full.txt`
goes further and concatenates the full markdown body of every page into one
document, ideal for stuffing a context window. Both are served by the
scaffold and written by static builds.

This site's own [/llms.txt](/llms.txt) and [/llms-full.txt](/llms-full.txt)
are the live output.

## Drafts stay out

Draft pages are excluded from feeds, sitemaps, and `llms.txt` along with
everything else — flipping `draft: false` publishes a page everywhere at
once.

---

# CLI

Source: https://voxx.prudentbird.com/docs/reference/cli
Date: 1970-01-01T00:00:00.000Z

```
voxx init [blog|docs|changelog] [--dir <content>] [--base <path>] [--app <dir>] [--force]
voxx init --add [blog|docs|changelog] [--name <name>] [--dir <dir>] [--base <path>] [--app <dir>]
voxx new "Title" [--collection <name>] [--dir <content>] [--date <YYYY-MM-DD>] [--slug <slug>] [--flat] [--section <path>] [--order <n>]
voxx build [--out <dir>] [--drafts]
voxx dev [--port <n>]
voxx telemetry [status|enable|disable]
```

The CLI is a convenience layer — everything it does, you could do by hand
with files and [`@prudentbird/voxx-core`](/docs/reference/core-api).

## `voxx init [preset]`

Scaffolds a surface. The preset (default `blog`) picks the sample content
and routes; the flags place them:

| Flag                    | Default       | What it does                                  |
| ----------------------- | ------------- | --------------------------------------------- |
| `--base /notes`         | `/<preset>`   | Mount path — scaffolded routes follow it      |
| `--dir content`         | `content`     | Content folder written into `voxx.json`       |
| `--app src/app`         | auto-detected | The Next.js app directory                     |
| `--cache-components`    | auto-detected | Force the Cache Components data layer          |
| `--no-cache-components` | auto-detected | Force the static data layer                   |
| `--force`               | off           | Overwrite existing files (default: skip them) |

With a Next.js app detected, `init` writes the routes for the preset, the
`_voxx/` data layer and components, `llms.txt` and `llms-full.txt` routes,
plus a sitemap and `robots.ts` (blog, docs) and an RSS route at
`<base>/rss.xml` (blog, changelog) where the type calls for them. On Next 16+ it also wraps
your `next.config` with `withVoxx` (from `@prudentbird/voxx-core/next`) when the config's shape is
unambiguous — otherwise it tells you what to add.

`init` scaffolds the static data layer by default, which needs no rendering-mode
changes. When your `next.config` already enables `cacheComponents: true`, it
scaffolds the Cache Components data layer instead. Pass `--cache-components` or
`--no-cache-components` to pick the variant directly.

If your app already defines design tokens (`--background` and friends in a
`globals.css`), Voxx inherits them; if not, `init` adds a starter
`voxx-globals.css`.

Without Next.js, `init` asks: static site (just `voxx.json` + content,
rendered by `voxx build`) or a new app via `create-next-app`. In a
non-interactive shell it defaults to static.

`init` is idempotent — existing files are skipped and reported, never
overwritten, unless you pass `--force`.

## `voxx init --add <preset>`

Adds a second (or third…) collection to a site that already has a
`voxx.json` — `voxx init --add docs` on a blog gives you a
[multi-collection](/docs/reference/collections) site:

| Flag                  | Default          | What it does                                                                            |
| --------------------- | ---------------- | --------------------------------------------------------------------------------------- |
| `--name notes`        | the preset name  | The collection's name — what `voxx new --collection` and `getPosts({ collection })` use |
| `--dir content/notes` | `content/<name>` | The new collection's content folder                                                     |
| `--base /notes`       | `/<name>`        | Mount path for the new collection's routes                                              |
| `--app src/app`       | auto-detected    | The Next.js app directory                                                               |

It rewrites `voxx.json` (migrating a single-collection `content` config to a
`collections` array — resolved behavior is preserved exactly), then scaffolds
only the new collection's content samples and routes. Site-wide files
(`sitemap.ts`, `robots.ts`, the `llms.txt` routes) are left alone if present
and created only when missing.

`--add` never overwrites: it requires an existing `voxx.json`, refuses
`--force`, and fails — writing nothing — if the new collection's name, `dir`,
or `basePath` collides with an existing one. Pass `--name`, `--dir`, or
`--base` to resolve a collision.

Note that feature defaults (`rss`, `toc`, …) follow the _first_ collection's
type — review `features` in `voxx.json` after adding a collection of a
different type.

## `voxx new "Title"`

Creates a content file, shaped by the collection type in `voxx.json`:

| Type      | `voxx new "X"` creates     | Useful flags                                       |
| --------- | -------------------------- | -------------------------------------------------- |
| blog      | `2026-06-11-x.md`          | `--date`, `--slug`, `--flat` (no date prefix)      |
| docs      | `x.md`                     | `--section guides`, `--order 3` → `guides/03-x.md` |
| changelog | `X.md` with `version:` set | — (the title _is_ the version)                     |

On a multi-collection site, `--collection <name>` picks which collection the
file lands in — `voxx new "Install" --collection docs` writes a docs page even
when the blog is listed first. Without the flag, the first collection in
`voxx.json` wins. An unknown name fails and lists the defined collections.

If the slug is taken, `voxx new` proposes a free one (`x-2`) — interactively
when it can, automatically when it can't. It never overwrites.

## `voxx build`

Renders every collection to static HTML in `./dist` — pages, styles,
images and other content assets, and the outputs your
[feature flags](/docs/reference/configuration#features) ask for
(`rss.xml`, `sitemap.xml`, `robots.txt`, `llms.txt`, `llms-full.txt`).

| Flag           | Default | What it does                                                                          |
| -------------- | ------- | ------------------------------------------------------------------------------------- |
| `--out public` | `dist`  | Output directory                                                                      |
| `--drafts`     | off     | Include `draft: true` pages (a collection's `drafts: true` in `voxx.json` also works) |

See [Static sites](/docs/getting-started/static-sites) for what each
content type produces.

## `voxx dev`

A local preview server for static sites: builds to a temp directory,
watches `voxx.json` and your content folders, rebuilds on change, and
serves the result. Drafts are included by default — `voxx dev` is the
draft-preview story.

| Flag          | Default | What it does      |
| ------------- | ------- | ----------------- |
| `--port 8080` | `4321`  | Port to listen on |

## `voxx telemetry [status|enable|disable]`

Manages anonymous usage telemetry. Voxx reports a single anonymous event per
command — the command name, whether it succeeded, its duration, and the
package, Node, and OS versions. It **never** collects arguments, file paths,
names, or content, and the CLI prints a one-time notice on first run.

| Subcommand | What it does                                   |
| ---------- | ---------------------------------------------- |
| `status`   | Prints the resolved state and any env override |
| `disable`  | Opts out (persisted)                           |
| `enable`   | Opts back in (persisted)                       |

Per-invocation opt-out is also honored via the `VOXX_TELEMETRY_DISABLED=1`,
`DO_NOT_TRACK=1`, or `CI=1` environment variables — telemetry is off
automatically in CI. The persistent setting lives in
`${XDG_STATE_HOME:-~/.local/state}/voxx/telemetry.json`.

The same engine powers [`@prudentbird/voxx-core`](/docs/reference/core-api),
which reports one anonymous `core_used` event per process plus anonymous
per-call core API events when used directly without the CLI; the opt-out
variables above apply there too.

---

# Core API

Source: https://voxx.prudentbird.com/docs/reference/core-api
Date: 1970-01-01T00:00:00.000Z

`@prudentbird/voxx-core` is the engine everything else is built on: the Next.js
scaffolding, the static builder, and this site. The public API is plain
async functions — Voxx is built with [Effect](https://effect.website)
internally, but you never have to touch it.

```ts
import {
  listPosts,
  getPost,
  buildNavTree,
  buildSeo,
} from "@prudentbird/voxx-core";

const { posts, total } = await listPosts({ limit: 10 }); // metadata, no rendering
const post = await getPost("getting-started/blog"); // renders just this post
const nav = buildNavTree(posts); // docs sidebar tree
const seo = buildSeo(post, await loadConfig()); // head-ready payload
```

## Content

Rendering Markdown — Shiki highlighting especially — is the expensive step, so
the engine keeps it off the listing path. `PostMeta` is everything derivable
from frontmatter and a quick scan (title, date, tags, excerpt, reading time…);
a `Post` is a `PostMeta` plus the rendered `html`, `toc`, and raw `content`.
List with metadata, render only what you show.

### `listPosts(options?)`

Returns `{ posts: PostMeta[]; total }` for a collection — docs in depth-first
tree order, blogs and changelogs newest-first — **without rendering any
Markdown**. `total` is the match count before pagination, for building page
controls. This is the scalable primitive for indexes, navigation, sitemaps,
and feeds: a collection of a million posts costs a frontmatter scan, not a
million renders. Options:

- `collection` — a [collection](/docs/reference/collections) name; defaults
  to the first
- `tag` — keep only posts whose `tags` include this value
- `category` — keep only posts whose `category` equals this value
- `offset` / `limit` — paginate the sorted, filtered set
- `includeDrafts` — override the config's draft behavior
- `cwd` / `path` — where to find `voxx.json`
- `config` — skip loading and pass a `VoxxConfig` directly

### `getPosts(options?)`

Like `listPosts`, but returns fully rendered `Post[]` (no `total`). Filtering
and pagination are applied to metadata first, so only the posts it returns are
rendered. Reach for it when you need the rendered bodies of many posts at once
— RSS, `llms-full.txt`, a single-page changelog. Accepts every `listPosts`
option.

### `getPost(slug, options?)`

One rendered post by slug — for docs, the slash-joined path
(`"getting-started/blog"`); an empty string fetches a root `index.md`. It
scans the collection for the match and renders only that post. Drafts follow
the same visibility rules as `listPosts` (pass `includeDrafts: true` to preview
them); rejects with `PostNotFound` when nothing matches.

### `getPostOrNull(slug, options?)`

Like `getPost`, but resolves to `null` when no slug matches instead of
rejecting — ideal for a route that renders one post and `notFound()`s when it
is missing. Render and config failures still reject, so a genuine 404 stays
distinct from a broken post.

### `findPost(posts, slug)`

The pure lookup over a loaded list (`PostMeta[]` or `Post[]`), exported so a
data layer that already has the list can resolve slugs without re-reading
content.

### The `PostMeta` and `Post` objects

Everything is precomputed — no second pass needed. `PostMeta` covers
everything except the body; `Post` adds it:

| Group              | Fields                                                                                                        |
| ------------------ | ------------------------------------------------------------------------------------------------------------- |
| Identity           | `slug`, `path[]`, `url`                                                                                       |
| Frontmatter        | `title`, `description`, `date`, `updated`, `tags`, `category`, `order`, `version`, `draft`, `image`, `author` |
| Derived            | `excerpt`, `readingTimeMinutes`                                                                               |
| Body (`Post` only) | `html` (rendered + highlighted), `toc[]`, `content` (raw markdown)                                            |

## Config

`loadConfig(options?)` loads, validates, and resolves `voxx.json` into a
complete `VoxxConfig` — every default applied, every path absolute.
`renderMarkdown(markdown, config?)` runs the rendering pipeline on a string
and returns `{ html, toc }`.

## Site outputs

| Function                                  | Returns                                                                                                               |
| ----------------------------------------- | --------------------------------------------------------------------------------------------------------------------- |
| `buildNavTree(posts)`                     | Nested `NavNode[]` for a docs sidebar                                                                                 |
| `buildSeo(post, config)`                  | Canonical + Open Graph + Twitter + JSON-LD                                                                            |
| `renderRss(posts, config, opts?)`         | RSS 2.0 XML with `content:encoded`; `opts.path` sets the self-link (default `rssPath(config)` = `<basePath>/rss.xml`) |
| `renderSitemap(posts, config, opts?)`     | `sitemap.xml` XML; `opts.indexPaths` lists extra collection indexes                                                   |
| `renderRobotsTxt(config)`                 | A `robots.txt` pointing at the sitemap                                                                                |
| `renderLlmsTxt(posts, config)`            | An `llms.txt` index                                                                                                   |
| `renderLlmsTxtSections(sections, config)` | A multi-collection `llms.txt` (one heading per section)                                                               |
| `renderLlmsFull(posts, config)`           | Every page's full markdown, concatenated                                                                              |

All of them are pure functions over data you already have, so they slot
into any route handler or build script.

## Helpers

The small utilities the engine uses are exported too: `slugify`,
`formatDate`, `absoluteUrl`, `joinPath`, `deriveExcerpt`,
`readingTimeMinutes`, `splitDatePrefix`, `splitOrderPrefix`, `humanize`,
`parseVersion`, and `escapeXml`.

## Telemetry

The Promise API records anonymous package telemetry unless the user has opted
out. Voxx sends one `core_used` event per process and one `core_api_call` event
per public API call. Per-call events include the API name, success/failure,
duration, content type, option flags, feature flags, and result counts where
relevant. Failed API calls and recoverable internal issues include sanitized
error tags, names, or codes.

Telemetry never includes arguments, file paths, slugs, collection names, post
names, titles, error messages, or content. Opt out with `VOXX_TELEMETRY_DISABLED=1`,
`DO_NOT_TRACK=1`, `CI=1`, or `voxx telemetry disable`.

## Dev content watcher

`registerContentWatcher(options?)` powers [live reload](/docs/getting-started/docs#live-reload)
for Next.js. Call it from `instrumentation.ts`; it watches every content
directory and `voxx.json` and bumps the generated `_voxx/content-version.ts`
module on each change, which the cached `data.ts` feeds into its `"use cache"`
key to refresh the page and invalidate the cache. Cache Components mode is what
scaffolds those version modules; the static data layer reads fresh content in
development on its own, so the watcher has nothing to bump there. It is a no-op
outside the Node.js runtime and outside development. Options:

- `versionModules` — explicit paths to bump; by default it finds every
  `_voxx/content-version.ts` under the project
- `cwd` — where to find `voxx.json` (defaults to `process.cwd()`)
- `debounceMs` — coalesce rapid edits (default `80`)

## The Effect entry point

If you _do_ speak Effect, `@prudentbird/voxx-core/effect` exposes the raw programs —
`listPostsEffect`, `getPostsEffect`, `getPostEffect`, `loadConfigEffect`,
`renderMarkdownEffect`, `parseFrontmatter` — alongside the `ConfigInput` and `Frontmatter` schemas
and the tagged errors (`ConfigError`, `InvalidFrontmatter`, `PostNotFound`,
`ContentDirMissing`, `RenderError`). Compose them into your own pipelines
and handle failures by tag instead of by message.

---

# Layouts

Source: https://voxx.prudentbird.com/docs/reference/layouts
Date: 1970-01-01T00:00:00.000Z

Every preset ships a self-contained shell instead of nesting under your site's
navbar and footer. Docs get a sidebar that owns the whole viewport; blog and
changelog get a slim top bar. Either way the chrome is part of the scaffold, so
the surface looks finished the moment you run `voxx init`.

Everything on this page except the shells' anatomy is **Next.js-specific** —
layout nesting and root layouts are App Router concepts. Static builds
(`voxx build`) have no layout system to fight; skip to
[Static builds](#static-builds).

## The docs shell

Docs scaffold a sidebar layout and the client pieces that drive it:

```
app/docs/layout.tsx        # the shell: sidebar + content grid
app/docs/_voxx/
  sidebar-nav.tsx          # the page tree
  mobile-nav.tsx           # drawer behind the ☰ button on small screens
  theme-toggle.tsx         # light/dark, persisted to localStorage
```

The layout renders one grid — sidebar on the left, your page on the right:

```tsx
<div className="voxx voxx-docs">
  <aside className="voxx-docs__nav">
    <div className="voxx-docs__nav-inner">
      <div className="voxx-docs__nav-header">
        {" "}
        {/* logo / site title */}
        <MobileNav items={tree} title={config.site.title} />
        <Link href="/docs" className="voxx-docs__title">
          …
        </Link>
      </div>
      <SidebarNav items={tree} /> {/* the page tree */}
      <div className="voxx-docs__nav-footer">
        {" "}
        {/* pinned to the bottom */}
        <ThemeToggle />
      </div>
    </div>
  </aside>
  {children}
</div>
```

The slots are plain class names from the Voxx stylesheet, so you can put
anything in the header and footer — a logo component, a version picker, a
GitHub link. On screens under 768px the sidebar collapses into a sticky top
bar: the ☰ button opens the page tree in a drawer, and the footer contents
sit on the right.

## The blog and changelog shell

Blog and changelog don't need a page tree, so they scaffold a slimmer shell —
a sticky top bar over the content:

```
app/blog/layout.tsx              # the shell: title, RSS link, theme toggle
app/blog/_voxx/theme-toggle.tsx  # light/dark, persisted to localStorage
```

```tsx
<div className="voxx">
  <header className="voxx-header">
    <Link href="/blog" className="voxx-header__title">
      …
    </Link>
    <div className="voxx-header__actions">
      {" "}
      {/* right-aligned controls */}
      {/* RSS link, shown when features.rss is on */}
      <ThemeToggle />
    </div>
  </header>
  {children}
</div>
```

Same idea as the docs shell at a smaller scale: the title on the left links
back to the index, and `.voxx-header__actions` holds the right-aligned
controls — the RSS link (rendered when `features.rss` is on) and the theme
toggle. The slots are plain class names, so swap in whatever your site needs.
Changelog uses the identical bar; only the feed label differs.

## Your Next.js root layout wraps the shell

A Next.js segment layout always renders inside every layout above it. If
`app/layout.tsx` has a navbar and footer, they wrap `/docs` (or `/blog`, or
`/changelog`) too — there is no opt-out, and the surface ends up with two
competing chromes. This bites docs hardest, since the sidebar expects the full
viewport, but it applies to every preset.

Two ways to arrange this:

1. **Keep the root layout bare.** Put `<html>`, `<body>`, fonts, and
   providers in `app/layout.tsx` and nothing else; move your navbar and
   footer into a route group layout for the rest of the site:

   ```
   app/
   ├── layout.tsx           # html/body only — no chrome
   ├── (site)/
   │   ├── layout.tsx       # navbar + footer live here
   │   └── page.tsx         # /
   └── docs/
       └── layout.tsx       # the Voxx shell
   ```

   This works, but it's a convention — a navbar added to the root layout
   later leaks into the surface again.

2. **Multiple root layouts.** Delete the top-level `app/layout.tsx`
   entirely. Any layout without one above it becomes a root layout, so give
   each branch its own `<html>` and `<body>`:

   ```
   app/
   ├── (site)/
   │   ├── layout.tsx       # root layout #1: html/body + your chrome
   │   └── page.tsx         # /
   └── docs/
       └── layout.tsx       # root layout #2: html/body + the Voxx shell
   ```

   Now leakage is structurally impossible — the content branch has no shared
   ancestor with the rest of your app. The trade-off: navigating between
   `/` and `/docs` is a full page load instead of a client-side transition,
   and each root layout declares its own fonts and providers. Top-level
   files that aren't pages (`sitemap.ts`, `robots.ts`, route handlers) stay
   where they are; they don't need a layout.

This is how [voxx](https://voxx.prudentbird.com) itself is arranged — the
marketing page and these docs are separate root layouts.

## Static builds

`voxx build` ships the same shells with zero JavaScript. Docs render the
sidebar with your `site.title` in the header, a `<details>` dropdown for
navigation on the mobile bar, and dark mode that follows
`prefers-color-scheme`. Blog and changelog render the same top bar — title
link plus RSS — as part of the HTML. There's nothing to wire up; the chrome is
baked into the rendered output.