# Vellum

> Markdown documentation sites that ship with your Laravel app.

================================================================================
Title: Vellum
URL: https://vellum.jimmyverburgt.com/docs
================================================================================

---
title: Vellum
description: Markdown documentation sites that ship with your Laravel app.
---

Vellum serves a folder of Markdown as a documentation site from the Laravel app you already deploy. It includes a sidebar, search, light and dark themes, and an optional static export.

You write pages in Markdown. The built-in callouts, tabs, steps and cards use `:::` directives, and `<x-…>` tags add your own Blade components and the allowlisted `env`, `config` and `route` value tags. Blade syntax such as `{{ }}`, `@if` and `@php` is not compiled in Markdown files.

:::note
`config/vellum.php` keys and page frontmatter have been frozen since 0.5. Breaking changes wait for 1.0.
:::

:::steps
## Require the package
`composer require jimmyverburgt/vellum`

## Publish stubs
`php artisan vellum:install`

## Open the site
Visit `/docs` and edit `resources/docs/`.
:::

:::cards describe="pages"
::card[What is Vellum](/docs/why)
::card[Installation](/docs/getting-started/installation)
::card[Writing Markdown](/docs/writing/markdown)
::card[Components](/docs/components)
::card[Navigation](/docs/writing/navigation)
::card[Extending](/docs/extending)
:::

================================================================================
Title: What is Vellum
URL: https://vellum.jimmyverburgt.com/docs/why
================================================================================

---
title: What is Vellum
description: A Laravel package that serves a folder of Markdown as a documentation site from your app, or exports it as a static site.
---

Vellum is a Laravel package that turns a folder of Markdown into a documentation site. The Markdown lives in your application's repository, `php artisan vellum:build` compiles it during deploy, and your app serves it at `/docs`. The same files can also be exported as a static site for a host that does not run PHP.

## What you get

- A sidebar built from your folders, ordered with `meta.json` or frontmatter
- In-browser search filtered for each reader, or Laravel Scout
- Light and dark mode, three colour presets and an accent colour
- Callouts, tabs, steps and cards as `:::` directives, and your own Blade components
- Code highlighted on the server, with titles, line numbers and highlighted lines
- Version folders and a changelog page with an Atom feed
- Access control per page or folder, for signed-in readers or through a Laravel gate
- Value tags that print allowlisted `env`, `config` and route values
- Raw Markdown for every page, a copy button, and links that open the page in ChatGPT or Claude
- A sitemap, canonical links and Open Graph tags
- Link, image and heading checks at build time

## How it works

`vellum:build` compiles each page to a PHP file and writes the navigation and search index. Laravel serves the pages from a route like any other, so requests do not parse Markdown. The CSS and JavaScript ship precompiled with the package, so you install Vellum with Composer alone.

`vellum:export` writes the same site as static HTML, with its assets and a search index. The export differs from the served site in two ways: value tags keep the values they had at export time, and gated pages are left out because a static host has no session to check access against.

## What it does not do

- **Edit in the browser.** Pages are Markdown files in your repository, changed through pull requests.
- **Analytics or AI chat.** There is no hosted service behind Vellum.
- **Design a custom front end for you.** The site's layout is a fixed docs theme, though you can override any of its Blade views. To render the docs in a front end of your own, use [core on its own](/docs/core).
- **Run outside Laravel.** It needs a Laravel app to build in, even when you only use the static export.

## Stability

The current release is 0.8. Config keys, frontmatter and the authoring syntax have been frozen since 0.5. Later releases add to them without renaming anything, and breaking changes wait for 1.0. [Upgrade](/docs/getting-started/upgrade) lists what changed between releases.

[Installation](/docs/getting-started/installation) takes about five minutes. [Comparisons](/docs/comparisons) covers how Vellum differs from LaRecipe.

================================================================================
Title: Comparisons
URL: https://vellum.jimmyverburgt.com/docs/comparisons
================================================================================

---
title: Comparisons
description: How Vellum differs from LaRecipe, the other package that serves Markdown documentation from inside a Laravel app.
---

## LaRecipe

[LaRecipe](https://github.com/saleem-hadad/larecipe) is the closest alternative to Vellum. It is also a Laravel package that serves Markdown from `resources/docs` at `/docs`. It dates from 2018 and is still maintained. The table compares both packages as of September 2026.

| | Vellum | LaRecipe |
| --- | --- | --- |
| Rendering | Compiled once by `vellum:build` | Parsed on each request, with an optional cache |
| Markdown | CommonMark and GitHub Flavored Markdown | Parsedown Extra |
| Sidebar | Your folder structure, ordered by `meta.json` or frontmatter | A hand-written `index.md` per version |
| Access control | Per page or folder: signed-in readers or a named gate, hidden pages return 404 | The whole site, behind a guard or your own middleware |
| Search | Built in, in the browser, filtered per reader. Laravel Scout optional | Algolia, or a built-in index of `h2` and `h3` headings |
| Static export | Yes | No |
| Front end | Alpine.js, compiled assets included | Vue |
| Dark mode | Built in | A separate package |
| Components | `:::` directives and Blade components | Blade, and Vue components through asset packages |
| Requirements | PHP 8.4, Laravel 11 to 13 | PHP 7.1 or later, Laravel 5.4 to 13 |

Choose LaRecipe if you are on an older PHP or Laravel version, or if you want one of its add-on packages for Swagger, right-to-left layouts, reader feedback or Disqus comments.

Choose Vellum if some pages should only be visible to certain readers, if you also want a static copy of the docs, or if you want broken links caught before a deploy.

## Outside Laravel

If your product is not a Laravel app, use a documentation framework built for its stack, such as [Fumadocs](https://fumadocs.dev) for Next.js or [VitePress](https://vitepress.dev) for a standalone static site. Vellum's layout is based on Fumadocs, and the [credits](/docs/credits) list what it borrows.

================================================================================
Title: Installation
URL: https://vellum.jimmyverburgt.com/docs/getting-started/installation
================================================================================

---
title: Installation
description: Requirements, installing the package, and the build step for production.
---

## Requirements

- PHP 8.4+
- Laravel 11, 12, or 13

## Install

:::steps
## Require the package

```bash
composer require jimmyverburgt/vellum
```

This installs the docs site and `jimmyverburgt/vellum-core`, the engine it runs on. To render the docs in your own front end instead, see [Core on its own](/docs/core).

## Publish config, stubs, and assets

```bash
php artisan vellum:install
```

`vellum:install` publishes `config/vellum.php`, copies starter Markdown into `resources/docs` and copies the compiled CSS and JavaScript to `public/vendor/vellum`.

## Open the site

Visit `/docs`, then edit the files in `resources/docs/`.
:::

## Production

Compile the Markdown once per deploy:

```bash
php artisan vellum:build
```

In the `local` environment pages recompile on request as you edit them, so you only need this
command in your deploy. See [Commands](/docs/commands).

## Next

- [Markdown](/docs/writing/markdown) for the Markdown syntax Vellum renders
- [Navigation](/docs/writing/navigation) to arrange the sidebar
- [Configuration](/docs/getting-started/configuration) for every config key and frontmatter field
- [Commands](/docs/commands) for what to run in a deploy
- [Upgrade](/docs/getting-started/upgrade) if you are upgrading from an earlier version
- [Troubleshooting](/docs/troubleshooting) when a page does not render

================================================================================
Title: Configuration
URL: https://vellum.jimmyverburgt.com/docs/getting-started/configuration
================================================================================

---
title: Configuration
description: Every config key and frontmatter field, all frozen since 0.5.
---

`vellum:install` publishes the config to `config/vellum.php`. The key names have been frozen since 0.5. Later releases can add keys, but none will be renamed before 1.0.

## Site and routing

| Key | Default | Purpose |
| --- | --- | --- |
| `name` | `env('APP_NAME', 'Docs')` | Site name, shown in the header and page titles |
| `path` | `env('VELLUM_PATH', resource_path('docs'))` | Root folder of the Markdown files. A relative path is read from the app root |
| `route.prefix` | `docs` | URL prefix |
| `route.middleware` | `['web']` | Route middleware |
| `route.domain` | `null` | Optional domain for the docs routes. Canonical links and the sitemap use it as their host, with the scheme from `app.url` |
| `repo` | `null` | Base URL for the "Edit on GitHub" link |
| `logo` | `null` | Path to an SVG file, or a Blade view name, for the site logo |
| `links` | `[]` | Extra links, each with `label`, `href` and an optional `icon: github`. Shown in the sidebar footer, or in the header when `layout.search` is `header` |
| `layout.search` | `env('VELLUM_LAYOUT_SEARCH', 'sidebar')` | Where the search field sits: `sidebar` or `header`. See [Theming](/docs/theming#where-search-sits) |
| `layout.toc` | `env('VELLUM_LAYOUT_TOC', 'window')` | How the table of contents marks what is on screen: `window` or `line`. See [Theming](/docs/theming#table-of-contents) |
| `fonts` | `null` | HTML added to the layout's head, such as a font stylesheet link |
| `checks.references` | `true` | Warn during `vellum:build` about links and images that point at nothing |
| `checks.strict` | `false` | Fail the build when there are reference warnings |
| `checks.search` | `true` | Ask the questions in `questions.yml`, if the docs have one, during `vellum:build`. See [Search](/docs/search#checking-search-in-ci) |
| `checks.search_min` | `env('VELLUM_SEARCH_MIN', 0.0)` | The share of those questions that must find their answer for the build to pass. `0` reports without failing |
| `agents.llms_txt` | `true` | Serve `llms.txt` and `llms-full.txt` under the docs prefix. See [Page actions](/docs/page-actions#for-agents) |
| `agents.llms_txt_root` | `true` | Also serve both at `/llms.txt` and `/llms-full.txt`, unless the app already routes those paths |
| `agents.content_negotiation` | `true` | Serve a page's raw Markdown when the request's `Accept` header prefers `text/markdown` |
| `agents.search` | `true` | Serve `{prefix}/_vellum/search?q=`, which returns search results as JSON. See [Search](/docs/search#the-search-endpoint) |
| `cache.path` | `storage_path('framework/vellum')` | Directory for compiled pages |
| `export.out` | `public_path('docs-static')` | Output directory for `vellum:export` |
| `export.base_url` | `/` | URL prefix used inside the export |

## Theme

See [Theming](/docs/theming) for the presets, the accent colour and the contrast target.

```php
'theme' => [
    'preset' => 'neutral',
    'primary' => null,
    'accent' => null,
    'radius' => '0.5rem',
    'default' => 'system',
],
```

## Versions

See [Versions](/docs/versions).

```php
'versions' => [
    'enabled' => false,
    'latest' => 'v2',
    'list' => ['v2', 'v1'],
    'labels' => [],
],
```

## Search

See [Search](/docs/search).

```php
'search' => [
    'enabled' => true,
    'hotkey' => 'k',
    'driver' => env('VELLUM_SEARCH_DRIVER', 'builtin'),
    'scout' => [
        'index' => 'vellum',
    ],
],
```

## Components

See [Value tags](/docs/value-tags) and [Extending](/docs/extending).

```php
'components' => [
    'namespaces' => ['vellum'],
    'allowlist' => [
        'env' => [],
        'config' => [],
        'route' => [],
    ],
],
```

## Changelog

See [Release notes](/docs/releases).

```php
'changelog' => [
    'path' => env('VELLUM_CHANGELOG', base_path('CHANGELOG.md')),
    'unreleased' => false,
],
```

## Frontmatter

Pages accept these frontmatter keys, which are also frozen:

| Key | Purpose |
| --- | --- |
| `title` | Page title. Falls back to the first heading, then the file name |
| `description` | Meta description, also shown on the next-page card and on cards that ask for it |
| `slug` | Overrides the URL slug |
| `order` | Position among sibling pages when `meta.json` does not list them |
| `full` | Hides the table of contents column |
| `access` | `guest`, `auth`, or a gate name. See [Gating](/docs/gating). |
| `updated` | Last-updated date, `2026-09-17` or ISO 8601 (`2026-09-17T10:00:00+02:00`), shown under the page title. Without it, the file's last git commit date is used, when the docs are in a full git clone. File modification times are never used |
| `questions` | Questions the page answers, as a list. Search matches a reader's question against them, alongside the ones Vellum derives from headings, commands and config keys |
| `aliases` | Other names readers use for the page's subject, as a list. A search containing one also matches the page title and the other aliases |

A folder's `meta.json` accepts `title`, `defaultOpen`, `pages` and `access`. A `_meta.md` file can set the folder's `access` or title in frontmatter instead. See [Navigation](/docs/writing/navigation).

Unknown keys are stored but ignored. Do not treat that behaviour as an API.

================================================================================
Title: Upgrade
URL: https://vellum.jimmyverburgt.com/docs/getting-started/upgrade
================================================================================

---
title: Upgrade
description: Upgrading from 0.8 to 0.9, from 0.7 to 0.8, from 0.6 to 0.7, within 0.6, from 0.5 to 0.6, and from 0.2 to the 0.5 freeze.
---

0.5 froze the keys in `config/vellum.php` and the page frontmatter names. Later releases add keys without renaming any, and no key will be removed before 1.0.

The requirements have been PHP 8.4+ and Laravel 11, 12, or 13 since 0.2.

## 0.8 to 0.9

No changes to your content or config are required. Update the package and rebuild:

```bash
composer update jimmyverburgt/vellum
php artisan vellum:build
```

0.9 adds the [API reference](/docs/api-reference). It is off until you set `openapi.enabled`, and a site that leaves it off is served as before.

Two fixes change what existing pages look like after the rebuild:

- A code block inside a tab, a callout or a step keeps an indent of one to three spaces, which was dropped before. YAML or JSON indented by two now shows as written.
- A line of `:::` inside a fenced code block is a line of code. It used to close the directive around the block.

### If you turn the reference on

A config file published before 0.9 has no `openapi` array. The package's defaults apply until you add one, so `VELLUM_OPENAPI=true` in `.env` is enough to start.

The reference adds a switch between the docs and the reference to the sidebar. If you have published the `sidebar`, `mobile-sidebar`, `header` or `shell` component, or the `doc`, `changelog` or `404` page, your copy does not pass it along and the two sidebars have no way from one to the other. Copy those views again from 0.9, or set `openapi.sidebar` to `docs` to list the reference as a folder of the docs' sidebar instead.

## 0.7 to 0.8

No changes to your content are required. Update the package and rebuild:

```bash
composer update jimmyverburgt/vellum
php artisan vellum:build
```

The update also installs `jimmyverburgt/vellum-core`, which now holds the engine Vellum runs on. Nothing changes in how you install or use the full package. See [Core on its own](/docs/core) for what core is.

Run `vellum:build` even outside a deploy. Compiled pages keep the HTML they were built with, and most components have new markup. On pages compiled by 0.7, the heading buttons stop copying links, the code buttons lose their check mark, and callouts, tabs and cards do not match the new stylesheet until the pages are rebuilt.

### What readers will notice

0.8 redesigns the details of every page, with no change to how you write them. The ones most likely to surprise:

- A shell block without a title is shown as a terminal with a `$` before each command. If you typed `$` yourself, it now shows twice, so remove yours. See [Terminal commands](/docs/writing/code-blocks#terminal-commands).
- Callouts are no longer boxes, and each names its type on its first line.
- The table of contents has a new default style, `window`. See [Table of contents](/docs/theming#table-of-contents) to keep `line`.
- With versions on, the switcher shows the latest version by its slug with a "Latest" tag, where it used to say "Latest" alone. Give the version a name in `versions.labels` if the slug is not what readers should see. Pages of any other version start with a notice. See [Versions](/docs/versions).
- Corners that ignored `theme.radius` now follow it, so a radius you changed also changes code blocks, tables, tabs and images.

### Config

`layout.toc` is new. A config file published before 0.8 has a `layout` array without it, and a published array replaces the package's whole, so `VELLUM_LAYOUT_TOC` is ignored until the key is in your file. Add it, or republish the config:

```php
'layout' => [
    'search' => env('VELLUM_LAYOUT_SEARCH', 'sidebar'),
    'toc' => env('VELLUM_LAYOUT_TOC', 'window'),
],
```

`vellum:build` no longer warns about a colour preset removed in 0.5. The site still falls back to `neutral`.

### Views you overrode

A view you copied from 0.7 into `resources/views/vendor/vellum/` and changed needs attention:

- The sidebar, the layout and every `ui` view named a class that has moved, so a 0.7 copy fails with "Class not found". Change the namespace in your copy, or copy the 0.8 view again. `Vellum\Support\Theme`, `Color`, `Assets`, `Cn` and `NavTree` are now in `Vellum\View`.
- A copy of the `callout`, `card`, `step` or `tabs` view has the old markup and will not match the new stylesheet. Copy it again from 0.8.
- A component view you published to `resources/views/vendor/vellum/components/` now also applies to the `:::` form of that component, not only the `<x-vellum::…>` tag. See [Change a built-in's markup](/docs/extending#change-a-built-ins-markup).
- The page actions moved into the line under the title. An override of `components/docs/page-actions.blade.php` still works, and `components/docs/page-meta.blade.php` is the view for the whole line.

### CSS and scripts that target Vellum's markup

- **Callouts:** the glyph is inside `.vellum-callout-title`, which is now always present. The border and background are gone, apart from a tint on warnings and dangers.
- **Tabs:** every group is a bordered card. The label row has a `.vellum-tabs-underline` element, and the group a `data-vellum-tabs-sliding` attribute once its script runs.
- **Code blocks:** a block without a title, other than a shell block, has no `.vellum-code-header`. Its language is in `.vellum-code-actions > .vellum-code-lang`. Select a kind with `data-vellum-code-kind`, which is `file`, `terminal` or `snippet`.
- **Copy buttons:** they are marked `data-vellum-copy-code` and `data-vellum-heading-copy`, without Alpine attributes.
- **Cards:** a card is a grid, with a `.vellum-card-arrow` and, when it has one, a `.vellum-card-description`.
- **Tables:** cells carry `data-label`. Below 40rem the table, its rows and its cells are `display: block`, and the header row is visually hidden.
- **Images:** an image on a line of its own has `data-vellum-image-block`, and its paragraph or figure is a padded, bordered mat.
- **Steps:** a step title under a section heading is one level below it, so a step under `## Setup` is an `h3`. The step's number is an `<a>`.
- **Previous and next:** the classes are `.vellum-pagination`, `-prev`, `-next`, `-label`, `-title` and `-description`. Previous has no box and no description.
- **Last updated:** the `<time>` moved from the breadcrumb row into `[data-vellum-page-meta]`.

### PHP that uses Vellum's classes

- `Vellum\Support\Theme`, `Color`, `Assets`, `Cn` and `NavTree` are now in `Vellum\View`, and `Vellum\Support\LlmsTxt`, `Vellum\Support\Sitemap` and `Vellum\Changelog\ChangelogFeed` are in `Vellum\Http`.
- `VersionLabel::for()` returns the slug for the latest version, not "Latest". `VersionLabel::kind()` says whether a version is the latest, older or unreleased.
- Errors in the docs, such as an unknown directive, implement `Vellum\Exceptions\ContentError`.

## 0.6 to 0.7

No changes to your config or content are required. Update the package, run `vellum:build`, and republish the config if you want the new keys in your file:

```bash
composer update jimmyverburgt/vellum
php artisan vellum:build
```

Search now returns sections instead of whole pages and no longer uses MiniSearch. The default `search.driver` is `builtin`; a config that still says `minisearch` keeps working. The built-in driver no longer serves `{prefix}/_vellum/search.json`, which only matters if something outside Vellum fetched that file. The Scout driver is unchanged. See [Search](/docs/search).

0.7 also adds `llms.txt`, content negotiation and a JSON search endpoint for agents, all on by default under the new `agents` keys. See [Page actions](/docs/page-actions#for-agents) to turn any of them off.

## Within 0.6

Patch releases need no changes to your config or content. After updating to 0.6.3 or later, run `vellum:build` once so the cached sidebar picks up the corrected access rules and compiled pages move to their new folder. Outside `local`, the site now serves only the pages the last build compiled, so a page added without a build returns a 404 until the next one.

If you export into the same directory each time, delete it once before your first export with 0.6.3 or later. From then on, each export removes the files the previous one wrote and this one did not.

Since 0.6.4, a folder's `title` can be set in `_meta.md` as well as `meta.json`.

## 0.5 to 0.6

No changes to your config or content are required. Update the package and republish the config to pick up the new keys:

```bash
composer update jimmyverburgt/vellum
php artisan vendor:publish --tag=vellum-config
```

`vendor:publish` skips a `config/vellum.php` that already exists. Add `--force` to overwrite it, then restore your own values from version control.

`vellum:build` now checks internal links, images and heading levels. It warns about links to pages or headings that do not exist, missing images, and headings that skip a level. On a docs set that has been edited for a while, the first run can print a page of warnings about problems that existed before the upgrade.

The warnings do not fail the build. They are controlled by the new `checks` keys, shown here with their defaults. Set `strict` to `true` to make them fail the build, which is useful in CI:

```php
'checks' => [
    'references' => true,
    'strict' => false,
],
```

`vellum:build --strict` does the same for a single run. Warnings about skipped heading levels never fail the build, even in strict mode.

A sitemap listing every public page is now served at `{prefix}/sitemap.xml`. Add it to `robots.txt`, and disallow the raw Markdown routes, which serve a second copy of every page:

```
Sitemap: https://example.com/docs/sitemap.xml
Disallow: /docs/_vellum/
```

`vellum:export` also writes a `sitemap.xml` at the root of the export. See [Search engines](/docs/seo).

The table of contents now highlights every heading whose section is on screen, where it used to highlight only the last heading scrolled past. This needs no action.

## 0.2 to 0.5

### Update the package

```bash
composer update jimmyverburgt/vellum
php artisan vendor:publish --tag=vellum-config
```

`vendor:publish` skips a `config/vellum.php` that already exists, so add `--force`, then diff the new file against your committed version. Keep your values and take the new keys.

### Keys added after 0.2

| Key | Default | Why |
| --- | --- | --- |
| `search.driver` | `minisearch` | `minisearch` or `scout`. The live MiniSearch index is served by a route that filters it for each reader. |
| `search.scout.index` | `vellum` | Scout index name, used with the `scout` driver. |
| `components.namespaces` | `['vellum']` | Blade prefixes allowed as `<x-…>` in Markdown. |
| `components.allowlist` | empty | Keys that the `env`, `config` and `route` tags may read. An empty list allows none. |
| `changelog.path` | `CHANGELOG.md` | A Keep a Changelog file. `null` turns off the changelog page and feed. |
| `changelog.unreleased` | `false` | Shows `[Unreleased]` on the HTML page. The feed never includes it. |
| `versions.labels` | `[]` | Switcher text per slug, such as `1.x (LTS)` or `Next`. The folder and URL still use the slug. |
| `theme.accent` | `null` | A brand colour applied to any preset, as one value or a light and dark pair. |

Already in 0.2 and still valid: `layout.search` (`sidebar` or `header`), `theme.preset`, `theme.primary`, `theme.radius`, `theme.default`.

### Colour presets

0.5 has three presets: `neutral`, `ocean` and `laravel`. These nine were removed: `black`, `vitepress`, `dusk`, `catppuccin`, `purple`, `solar`, `emerald`, `ruby`, `aspen`.

If you used one, the site falls back to `neutral`. Most of the removed presets only changed the accent colour, which `theme.accent` now sets on any preset:

```php
'theme' => [
    'preset' => 'neutral',
    'accent' => '#7c3aed',
],
```

The remaining presets were retuned to meet WCAG AA (4.5:1) for body text, secondary text, links and button labels in light and dark mode. See [Theming](/docs/theming).

### Version URLs

When `versions.enabled` is true, the latest version is now served at `/docs/...` with no version segment, and `/docs/{latest}/...` redirects there with a 301. Older versions stay at `/docs/v1/...`. Since 0.8 the switcher shows the latest version by its slug, or its `versions.labels` label, with a "Latest" tag. Before that it was labelled "Latest" alone.

Update inbound links to use the unprefixed URLs. The changelog stays at `/docs/changelog`.

### Frontmatter

The new `access` key takes `guest` (the default, matching 0.2), `auth`, or a gate name. Access set in a folder's `meta.json` or `_meta.md` applies to everything below it. See [Gating](/docs/gating).

`title`, `description`, `slug`, `order` and `full` are unchanged.

### Search

The default is still in-browser MiniSearch. Set `VELLUM_SEARCH_DRIVER=scout` only if you already run Laravel Scout. `vellum:export` always writes MiniSearch JSON.

### Markdown plus components

0.3 added `<x-…>` islands, `:::` directives and value tags. Use `:::` directives for callouts, tabs, steps and cards where you can. See [Components](/docs/components) and [Extending](/docs/extending).

### Commands

`vellum:index` rebuilds the search index, and the Scout index when that driver is on. `vellum:build` still compiles the Markdown.

================================================================================
Title: Markdown
URL: https://vellum.jimmyverburgt.com/docs/writing/markdown
================================================================================

---
title: Markdown
description: The Markdown flavour Vellum renders and where it departs from GitHub.
---

Vellum renders **CommonMark plus GitHub Flavored Markdown**, with a few additions. Anything
that works in a GitHub README works here.

## What you get

| Feature | Notes |
| --- | --- |
| Headings | `##` to `######` get anchors. See below. |
| Emphasis, lists, blockquotes | Standard CommonMark. |
| Tables | GFM pipe tables. See [Tables](#tables). |
| Task lists | `- [x] done` renders a styled checkbox. |
| Strikethrough | `~~gone~~`. |
| Autolinks | Bare URLs become links. |
| Footnotes | `Text[^1]` with `[^1]: The note` renders a numbered footnote with a back-reference. |
| Code | Fenced blocks are highlighted, and so is inline code tagged with a language. See [Code blocks](/docs/writing/code-blocks). |
| Images | See [Images](/docs/writing/images). |

Vellum also adds `:::` directives for [callouts, tabs, steps and
cards](/docs/components), `<x-…>` tags for [your own
components](/docs/extending), and allowlisted [value tags](/docs/value-tags).

## Tables

A table is written as a GFM pipe table and needs no options:

- Code in the first column, such as a config key, is never broken across lines.
- The header row of a table that fits the page stays at the top of the window while the
  reader scrolls through it.
- A table too wide for the page scrolls sideways inside its own frame instead, without a
  pinned header, and the page keeps its width.
- On a phone each row becomes a block: the first cell in bold, then every other value under
  its column's heading. Nothing scrolls sideways.

## Headings and anchors

Every heading from `##` down gets an `id` and a copy-link button that appears on hover.
The id is generated from the heading text. If two headings on a page produce the same id,
the later ones get a suffix so every link still resolves.

`#` is reserved for the page title. Set `title` in frontmatter and the layout renders the
`h1` for you. If a page has no frontmatter title and opens with a `# Heading`, that
heading becomes the title and is removed from the body, so the page does not end up with
two `h1`s. If the page has both a frontmatter title and a `# Heading`, the heading stays
and `vellum:build` warns about it.

The table of contents is built from these headings. A page without any keeps the empty
column, so the text width stays the same from page to page.

Give each heading one topic, ideally one thing a reader would ask about. Search returns
sections, one heading and the text under it at a time, so a section that covers several
unrelated settings is a weak match for each of them. When a section starts collecting
leftovers, split it.

## Links

Internal links are ordinary Markdown: `[Gating](/docs/gating)`.

A link to a host other than the one in `app.url` gets `target="_blank"`, `rel="noopener"`
and a small outward arrow, so readers can tell it leaves the site before they click.

Links with `javascript:` and other unsafe schemes are stripped.

## Raw HTML is removed

Markdown is parsed with `html_input: strip`, so a `<details>`, `<div>` or `<img>` written
straight into a page is removed without a warning. Inside a paragraph only the tags go and
the text between them stays: `Before <details>x</details> after` renders as
`Before x after`. HTML that starts on its own line forms an HTML block, and the whole block
is dropped, text included.

This keeps docs files from injecting arbitrary markup into the layout. When Markdown cannot
express what you need, write a Blade component. See [Extending](/docs/extending).

## No Blade

`{{ }}`, `@if` and `@php` are never compiled in a docs file. They render as the literal
characters you typed, in prose, in code and inside component attributes.

To show a real application value, use an allowlisted [value tag](/docs/value-tags).

## Frontmatter

YAML between `---` fences at the very top of the file:

```md
---
title: Billing
description: How invoices are generated.
---
```

[Configuration](/docs/getting-started/configuration#frontmatter) lists every key. Unknown
keys are kept and ignored.

:::note[Save the file as UTF-8 without a BOM]
A byte order mark sits in front of the opening `---`. Vellum strips a leading BOM so the
frontmatter still parses, but other tools that read your Markdown may not.
:::

================================================================================
Title: Code blocks
URL: https://vellum.jimmyverburgt.com/docs/writing/code-blocks
================================================================================

---
title: Code blocks
description: Titles, line numbers, highlighted lines, and inline code with a language.
---

Code is highlighted on the server by [Tempest
Highlight](https://github.com/tempestphp/highlight). No highlighter is sent to the browser, so
the number of code blocks on a page does not change how much JavaScript it loads.

The colours are GitHub Light and GitHub Dark. Every token meets WCAG AA contrast against
the code background in all three [presets](/docs/theming).

## A fence

````md
```php
Route::get('/invoices', InvoiceController::class);
```
````

```php
Route::get('/invoices', InvoiceController::class);
```

The first word of the info string is the language. Without one, the block is treated as
plain text.

A block without a title has no header. Its language and a copy button sit in the top
corner, and the label makes way for the button when the pointer is over the block. A block
with no language shows only the button.

Two kinds of block do have a header: a block with a [title](#title), whose header names the
file, and a shell block without a title, which is shown as a
[terminal](#terminal-commands) under a header reading "Terminal".

The languages below are recognised for the label and the file glyph in a titled block's
header, and an alias is labelled with the main name. `php` and `blade` use the general
code-file glyph; the others have one of their own.

| Language | Also accepted as |
| --- | --- |
| `php` | `php8` |
| `blade` | `laravel` |
| `js` | `javascript`, `mjs`, `cjs` |
| `ts` | `typescript`, `mts` |
| `jsx`, `tsx`, `vue` | |
| `html` | `htm` |
| `css` | `scss` |
| `json` | `jsonc` |
| `yaml` | `yml` |
| `bash` | `sh`, `shell`, `zsh`, `console` |
| `python` | `py` |
| `rust` | `rs` |
| `cpp` | `c++`, `cxx`, `cc` |
| `md` | `markdown` |
| `sql`, `c` | |

Any other language gets the general code-file glyph. Highlighting depends on what Tempest
supports, so a language it does not know (Rust, C and C++ among them) renders as plain
text with its glyph and label intact.

## Title

Name the file the snippet comes from:

````md
```php title="routes/web.php"
Route::get('/invoices', InvoiceController::class);
```
````

```php title="routes/web.php"
Route::get('/invoices', InvoiceController::class);
```

A titled block gets a header with the file's glyph and name, drawn as an editor tab. Single
or double quotes both work.

## Terminal commands

A shell block without a title is shown as a terminal: a header reading "Terminal", and a `$` before each command:

````md
```bash
# Install the package
composer require jimmyverburgt/vellum \
    --no-interaction
```
````

```bash
# Install the package
composer require jimmyverburgt/vellum \
    --no-interaction
```

A line gets a `$` unless it is blank, a `#` comment, or the continuation of a line ending in
`\`. The `$` cannot be selected and the copy button leaves it out, so what the reader copies
runs as it is. Do not write the `$` yourself.

A shell block with a title is shown as a file, a script to save rather than commands to
run, so it gets no `$`. With `showLineNumbers`, the line numbers take the place of the `$`.

## Line numbers

Add `showLineNumbers`:

````md
```php showLineNumbers
$invoice = Invoice::query()
    ->where('team_id', $team->id)
    ->latest()
    ->firstOrFail();
```
````

```php showLineNumbers
$invoice = Invoice::query()
    ->where('team_id', $team->id)
    ->latest()
    ->firstOrFail();
```

The numbers cannot be selected, so copying the code by hand leaves them out.

## Highlighted lines

Put the line numbers in braces, as single lines, ranges or a mix, separated by commas. They get a bar and a tint in the theme's primary colour:

````md
```php showLineNumbers {1,3-4}
$invoice = Invoice::query()
    ->where('team_id', $team->id)
    ->latest()
    ->firstOrFail();
```
````

```php showLineNumbers {1,3-4}
$invoice = Invoice::query()
    ->where('team_id', $team->id)
    ->latest()
    ->firstOrFail();
```

Lines are counted from one within the block, whatever their position in the original
file. The braces can go before or after `title` and `showLineNumbers`:

````md
```php title="app/Models/Invoice.php" showLineNumbers {3}
```
````

## Inline code with a language

Add `{:language}` immediately after the closing backtick:

```md
Call `Invoice::query()`{:php} inside the controller.
```

Call `Invoice::query()`{:php} inside the controller.

Without the suffix, inline code renders as plain monospace text. The suffix is useful for
class and method names in prose. File paths and commands read fine without it.

## Grouping blocks as tabs

When every panel of a `:::tabs` group is a single fenced block, Vellum renders the group
as code tabs, which share one frame and one copy button. Add `persist` and the reader's
choice carries over to other groups. See [Tabs](/docs/components/tabs).

## Showing directive syntax

To show `:::` or a fence as literal text, wrap it in a longer fence. A four-backtick
fence can contain a three-backtick one:

`````md
````md
```php
echo 'nested';
```
````
`````

================================================================================
Title: Images
URL: https://vellum.jimmyverburgt.com/docs/writing/images
================================================================================

---
title: Images
description: Where image files live, how they are served, and the attributes Vellum adds.
---

Put image files in the docs directory alongside your Markdown and reference them with
ordinary Markdown image syntax.

```
resources/docs/
├── index.md
├── assets/
│   └── architecture.svg
└── billing/
    └── invoices.md
```

```md
![The request lifecycle](assets/architecture.svg)
```

## Paths resolve from the docs root

A relative path is resolved from the top of the docs directory. The location of the page
makes no difference: `assets/architecture.svg` points to the same file from `index.md`
and from `billing/invoices.md`.

With [versions](/docs/versions) enabled, the root is the version folder, so
`assets/architecture.svg` in `v2/billing/invoices.md` resolves to `v2/assets/architecture.svg`.
Each version has its own copy of its assets.

Absolute URLs, `data:` URIs and `#` fragments are left as written.

## How they are served

When the file exists on disk, its path is rewritten to a route under the docs prefix:

```
assets/architecture.svg  →  /docs/_vellum/files/assets/architecture.svg
```

A path that matches no file on disk is left unchanged, in case it points at something
the app serves itself.

`vellum:export` copies the same files into `_vellum/files/` in the export, so images also
work in the static snapshot.

## What Vellum adds

**Dimensions.** Vellum reads the width and height from the file, sets them on the `img`
and adds a matching `aspect-ratio`. The browser reserves the space before the image loads,
so the text does not shift. For an SVG, the values come from its `width` and `height`
attributes.

For a file Vellum cannot read, such as one on a CDN, put the dimensions in the URL as a
path segment of their own:

```md
![Chart](https://cdn.example.com/900x300.png)
```

The segment must be exactly `{width}x{height}`, plus the file extension if it is the file
name. `assets/800x600.png` works and `assets/chart-800x600.png` does not.

**Lazy loading.** Every image gets `loading="lazy"`.

**Alt text.** The Markdown alt text is used as written, so always provide it.

**A frame and a larger view.** An image on a line of its own sits on a mat with a border, so
a screenshot with the same background as the page still has an edge, and a tall image is
held to a readable height. When an image is shown smaller than it is, the reader can open
it at full size with a click, or with Enter when it has focus, and close it with Escape. An
image inside a line of text is left as it is, and an image that is a link keeps its link and does not zoom.

## Captions

An image with a title is wrapped in a `<figure>`, and the title becomes its
`<figcaption>`, shown under the image inside its frame:

```md
![Request lifecycle](assets/architecture.svg "How a docs request is resolved")
```

The alt text describes the image for readers who cannot see it, while the caption is
read by everyone, so the two usually say different things.

## Formats the route will serve

The asset route serves images, fonts, video, audio, `vtt` captions, `pdf`, `txt`, `csv`
and `zip` files. It does not serve Markdown, `meta.json`, `_meta.md`, or any file or folder
whose name starts with a dot, so page sources and folder metadata cannot be downloaded
through it.

:::warning[Assets are not gated]
[Gating](/docs/gating) applies to pages only. The asset route serves a file to anyone who
has the URL, even when it sits next to a gated page. Keep anything secret out of the docs
directory.
:::

================================================================================
Title: Navigation
URL: https://vellum.jimmyverburgt.com/docs/writing/navigation
================================================================================

---
title: Navigation
description: How the sidebar is built from folders, meta.json, and frontmatter.
---

The sidebar mirrors your folder structure, so there is no separate navigation file or
route list to maintain.

```
resources/docs/
├── index.md              → /docs
├── why.md                → /docs/why
└── billing/
    ├── meta.json
    ├── index.md          → /docs/billing
    └── invoices.md       → /docs/billing/invoices
```

Each folder becomes a collapsible group, and the `index.md` inside it is the group's own
page. A page's sidebar label is its `title`. Without one, Vellum uses the first `#`
heading, then the file name.

## Ordering

By default, pages in the same folder are sorted by their frontmatter `order`, and pages
without one follow alphabetically by file name:

```md
---
title: Invoices
order: 1
---
```

`order` gets hard to manage once a folder has more than a handful of pages. For larger
folders, list the pages in `meta.json` instead.

## meta.json

Add a `meta.json` to a folder to configure its group:

```json
{
    "title": "Billing",
    "defaultOpen": true,
    "pages": ["index", "invoices", "refunds"]
}
```

| Key | Purpose |
| --- | --- |
| `title` | Group label in the sidebar. Defaults to the folder name, title-cased. |
| `defaultOpen` | Open the group on first load. A group containing the current page always opens. |
| `pages` | Explicit order. Entries are file names without `.md`, relative to this folder. |
| `access` | Gate the whole folder. See [Gating](/docs/gating). |

Names in `pages` are relative to the folder that holds `meta.json`. In `billing/`, write
`"invoices"` and not `"billing/invoices"`.

`pages` sets the order only. Pages you leave out are still shown, in alphabetical order
after the listed ones. To remove a page from the sidebar, gate it with
[`access`](/docs/gating).

### Keep the rest

`"..."` stands for every page not listed by name and sets where those pages appear.
Without it they go at the end:

```json
{
    "pages": ["index", "...", "changelog"]
}
```

Here `index` comes first, `changelog` last, and the rest in alphabetical order between
them.

### Section headings

An entry wrapped in triple dashes becomes a label that is not a link. Use it to split a
long list into sections:

```json
{
    "pages": [
        "index",
        "---Billing---",
        "invoices",
        "refunds",
        "---Reference---",
        "webhooks"
    ]
}
```

Consecutive and trailing separators are removed, so a section whose pages are all
hidden by [gating](/docs/gating) does not leave an empty heading behind.

### External and custom entries

An object entry adds a link to something other than a file in this folder:

```json
{
    "pages": [
        "index",
        { "title": "Changelog", "slug": "changelog" },
        { "title": "API reference", "href": "https://api.example.com" }
    ]
}
```

`slug` is turned into a docs URL. `href` is used as written.

A link inherits its folder's `access` in the same way a page does, and an `access` key on
the link overrides it. A link to a gated page is only shown to readers who can open that
page.

## _meta.md

`_meta.md` sets a folder's `title` and `access` in frontmatter, for when that is all you
need and you would rather not add JSON:

```md
---
title: Billing
access: auth
---
```

`_meta.md` is never rendered as a page. When a folder has both files and they set the same
key, the value in `_meta.md` is used.

## Gating and the sidebar

Pages a reader cannot open are left out of the sidebar entirely, and a group with no
visible pages left is removed too. See [Gating](/docs/gating).

## In the browser

The sidebar keeps its scroll position as a reader moves between pages, and scrolls the current page into view when it would otherwise be hidden. The highlight on the current page slides over from the page the reader came from, and fills as the reader moves down the page. A lighter highlight follows the pointer, and each folder has a guide line, drawn in the primary colour for the folder holding the current page.

A dot marks a page that changed since the reader last opened it, based on its `updated` date or last git commit. What each reader has opened is stored in their own browser, so nothing is sent to the server, and a reader who has never opened a page sees no dot on it. The page itself says so as well, in the line under its title.

## Previous and next

Each page ends with links to the pages before and after it in sidebar order. Next is a card
with the page's title and description, since a reader who reached the end is most likely
going on, and Previous is a plain link beside it. When the neighbouring page is in another
folder, its label names that folder, as in "Next · Components", so leaving a section is not
a surprise. Links from `meta.json` to somewhere outside the docs are skipped.

## Two files, one URL

`billing.md` and `billing/index.md` both resolve to `/docs/billing`, and so do two pages
with the same frontmatter `slug`. When that happens, `vellum:build` fails with an error
that names both files.

================================================================================
Title: Components
URL: https://vellum.jimmyverburgt.com/docs/components
================================================================================

---
title: Components
description: The built-in directives and value tags.
---

Vellum ships with callouts, tabs, steps and cards. You write them as `:::` directives, a syntax that has been frozen since 0.5.

Each one is a Blade view under `vellum::components`, so `:::note` and `<x-vellum::callout type="note">` produce identical markup, and you can [replace a view](/docs/extending#change-a-built-ins-markup) to change it. Use `:::` for the built-in components and `<x-…>` tags for components you add yourself. See [Extending](/docs/extending).

:::cards describe="pages"
::card[Callouts](/docs/components/callouts)
::card[Tabs](/docs/components/tabs)
::card[Steps](/docs/components/steps)
::card[Cards](/docs/components/cards)
::card[Value tags](/docs/value-tags)
::card[Code blocks](/docs/writing/code-blocks)
::card[Troubleshooting](/docs/troubleshooting)
:::

================================================================================
Title: Callouts
URL: https://vellum.jimmyverburgt.com/docs/components/callouts
================================================================================

---
title: Callouts
description: Notes, tips, warnings, and related asides.
---

A callout sets one point apart from the surrounding text. Use them sparingly, because
callouts lose their emphasis when a page has too many of them.

A callout is not a box: a bar in its type's colour runs down its left edge, and its first
line names the type, such as "Note" or "Warning", with the type's glyph. Warnings and
dangers are also tinted, so they never read as quietly as a note.

```md
:::note
Use callouts for notes, tips, warnings, danger, and info.
:::

:::warning[Careful]
Optional titles go in brackets after the directive name.
:::
```

:::note
Use callouts for notes, tips, warnings, danger, and info.
:::

:::warning[Careful]
Optional titles go in brackets after the directive name.
:::

## The five types

| Directive | Use it for |
| --- | --- |
| `:::note` | Useful information that does not change what the reader does. |
| `:::tip` | A shortcut, or a better way to do what the reader is already doing. |
| `:::info` | Background that is neither a warning nor advice. |
| `:::warning` | Something likely to cause problems, such as a limitation, a common mistake or a migration step. |
| `:::danger` | Data loss, irreversible actions and security risks. |

:::tip
Tips map to the same style as `success`.
:::

:::info
Extra context that is not a warning.
:::

:::danger
Destructive or irreversible actions.
:::

`success` is an alias of `tip`, and `idea` is an alias of `note`. An alias is labelled with
the word you wrote, "Success" or "Idea", and that word is kept in the `data-vellum-callout`
attribute, so you can select an alias separately in CSS
or JavaScript even though it looks the same as the type it maps to.

## Titles

Put the title in square brackets directly after the directive name:

```md
:::warning[Run this before deploying]
`vellum:build` has to run after the Markdown changes, not before.
:::
```

:::warning[Run this before deploying]
`vellum:build` has to run after the Markdown changes, not before.
:::

The title takes the place of the type's name on the first line. Screen readers still hear
the type before it, as "Warning: Run this before deploying".

:::warning[title= is not the bracket form]
`:::note title="Custom"` parses without an error, but the title is ignored. Only the
bracket form sets a title. This is a known limitation.
:::

## Contents

The body is ordinary Markdown and can hold lists, links, code, tables and other
directives.

:::note[A callout with a block in it]
A callout has no background of its own, so a code block inside it looks the same as one in
the text around it:

```bash
php artisan vellum:build
```
:::

## Island form

The same Blade view is available as a tag for use inside a component:

```html
<x-vellum::callout type="tip" title="Same view">
Body here.
</x-vellum::callout>
```

| Attribute | Purpose |
| --- | --- |
| `type` | One of the five types, or an alias. Anything unrecognised falls back to `note`. |
| `title` | Optional title. |
| `name` | Overrides the value in `data-vellum-callout`. Defaults to `type`. |

Use `:::` in docs pages. Use `<x-vellum::callout>` when a component of your own needs a
callout inside it.

================================================================================
Title: Tabs
URL: https://vellum.jimmyverburgt.com/docs/components/tabs
================================================================================

---
title: Tabs
description: Switchable panels, including code tabs.
---

Use tabs for alternatives, such as two ways to install the same package or one call
written in two languages. Tabs hide all but one panel, so keep content that readers should
go through in sequence on the page itself.

Every tab group is one card, with an underlined row of labels over the panel. The underline
slides to the label the reader picks.

```md
:::tabs
::tab[Composer]
Run the command.
::tab[composer.json]
Edit the file.
:::
```

:::tabs
::tab[Composer]
Run the command.
::tab[composer.json]
Edit the file.
:::

Each `::tab[Label]` starts a panel that continues until the next `::tab` or the closing
`:::`. Labels are plain text, and Markdown inside the brackets is not rendered.

## Code tabs

When every panel holds exactly one fenced code block and nothing else, Vellum renders the
group as code tabs: the same card, with the code block in place of the panel.

:::tabs persist="install"
::tab[Composer]
```bash
composer require jimmyverburgt/vellum
```
::tab[composer.json]
```json
{
    "require": {
        "jimmyverburgt/vellum": "^0.8"
    }
}
```
:::

If any panel contains prose as well, even a single sentence, the group renders as
ordinary tabs.

## Remembering the choice

`persist="key"` stores the active tab in `localStorage` under `vellum-tabs-{key}`.

Give groups that offer the same choice the same key. A reader who picks Composer in one
group sees Composer selected at once in every other group with that key on the page, and on
the pages they open next. The group they clicked stays where it is on screen, even when the
groups above it change height. For unrelated groups, use a different key or leave `persist`
off.

This group shares the `install` key with the code tabs above:

:::tabs persist="install"
::tab[Composer]
Run `composer require` in your app's root directory.
::tab[composer.json]
Add the package to `require`, then run `composer update`.
:::

## Other directives inside a panel

:::tabs
::tab[Note]
:::note
A callout inside a tab.
:::
::tab[Prose]
Ordinary Markdown in the second panel.
:::

## Rules worth knowing

Headings inside a panel still appear in the table of contents. Clicking one while a
different panel is showing does not scroll anywhere, so avoid `##` inside tabs.

Panel ids are generated from the label: it is lowercased and each run of characters other
than letters and digits becomes a dash, so `::tab[composer.json]` becomes `composer-json`.

Every panel is included in the page HTML, and the inactive ones are hidden in the browser.
Search and crawlers index the content of all panels.

## Island form

```html
<x-vellum::tabs persist="install">
<x-vellum::tab label="Composer">
Panel body.
</x-vellum::tab>
<x-vellum::tab label="composer.json">
Second panel.
</x-vellum::tab>
</x-vellum::tabs>
```

| Attribute | On | Purpose |
| --- | --- | --- |
| `persist` | `tabs` | localStorage key, as described above. |
| `code` | `tabs` | Set to `"true"` to render the group as code tabs. |
| `label` | `tab` | Panel label. `title` works as an alias. |
| `id` | `tab` | Replaces the generated panel id. |

================================================================================
Title: Steps
URL: https://vellum.jimmyverburgt.com/docs/components/steps
================================================================================

---
title: Steps
description: Numbered procedures from headings.
---

Use steps for a procedure the reader follows in order. If the order does not matter, use
a list.

Each `##` heading inside `:::steps` starts a numbered step, and everything up to the next
`##` belongs to that step.

```md
:::steps
## Install the package
Require Vellum with Composer.

## Publish starter docs
Run `php artisan vellum:install`.
:::
```

:::steps
## Install the package
Require Vellum with Composer.

## Publish starter docs
Run `php artisan vellum:install`.
:::

## Blocks inside a step

A step can contain any Markdown, including code, callouts, tables and nested lists. The
connecting line runs the full height of each step, so a long step still reads as one
unit.

:::steps
## Require the package

```bash
composer require jimmyverburgt/vellum
```

## Publish config, stubs and assets

```bash
php artisan vellum:install
```

:::note
`vellum:install` will not overwrite files you have already edited.
:::

## Open the site

Visit `/docs`.
:::

## In the browser

The line between the numbers fills as the reader moves through the steps, and each number fills once its step is reached. The same numbers in the table of contents fill with them, so both show how far through the procedure the reader is.

While a long step is read, its number stays in view at the top of the window. Clicking it scrolls back to the start of that step. Without JavaScript the numbers still link to their steps, and nothing fills.

## Rules worth knowing

Only `##` starts a step. `###` and lower headings stay ordinary headings inside the
current step, which makes them useful for dividing a long step into parts.

Content before the first `##` is rendered as it is, outside any step. A sentence of setup
can go there, although it usually reads better above the directive.

Step numbers are generated by counting the `##` headings in the block, starting at one.
Do not number the headings yourself: `## 1. Install` produces step 1 with the title
"1. Install".

A steps block belongs to the section it sits in. Its step titles are rendered one heading
level below that section's heading, so they nest under it in the table of contents and in
the page outline screen readers use, and headings inside a step move down with them. A
steps block before any `##` heading keeps its step titles at `h2`. You still start each
step with `##`.

================================================================================
Title: Cards
URL: https://vellum.jimmyverburgt.com/docs/components/cards
================================================================================

---
title: Cards
description: Link cards in a two-up grid.
---

Cards link to other pages, for example the next steps at the end of an overview or the
entry points on a section index. They are not meant as a general layout tool.

```md
:::cards
::card[Installation](/docs/getting-started/installation) Requirements, the package and the build step.
::card[Laravel](https://laravel.com)
:::
```

:::cards
::card[Installation](/docs/getting-started/installation) Requirements, the package and the build step.
::card[Laravel](https://laravel.com)
:::

Cards in a row are as tall as the tallest of them, so a row stays even when only some cards
have a description.

## Syntax

Each card is a single line:

```
::card[Title](href) Description
```

The title and the description are plain text, and the description is optional. A long
description is cut off after three lines. The href can be a docs path, an app path or an
external URL. Unlike an external link in prose, a card with an external URL opens in the
same tab, with the same arrow as every other card.

A card needs both a title and an href. `::card[Title]` without an href is not turned into
a card. It appears on the page as the literal text you typed, which shows that the line
needs fixing.

Cards are laid out two per row on wide screens and in a single column on narrow ones, so
an even number of cards fills the grid best.

## Descriptions from the pages

`describe="pages"` gives each card without a description of its own the description of the
page it links to, from that page's frontmatter:

```md
:::cards describe="pages"
::card[Callouts](/docs/components/callouts)
::card[Tabs](/docs/components/tabs)
:::
```

:::cards describe="pages"
::card[Callouts](/docs/components/callouts)
::card[Tabs](/docs/components/tabs)
:::

The description is filled in when the page is shown, from the navigation, so a card follows
its page after the next `vellum:build` without you editing the card. A card for a page the
reader cannot open shows no description, so a gated page's summary is never shown to
someone it is hidden from. A card linking outside the docs shows the site's domain, and a
card with its own description keeps it.

## Only cards belong inside

`:::cards` should contain only `::card` lines. A paragraph between them becomes a grid
cell of its own, so put any introductory text above the directive:

```md
Pick up where you left off:

:::cards
::card[Configuration](/docs/getting-started/configuration)
::card[Navigation](/docs/writing/navigation)
:::
```

## A section index

The typical use is an overview page that ends with links to the pages in its section,
described by the pages themselves:

```md
:::cards describe="pages"
::card[Callouts](/docs/components/callouts)
::card[Tabs](/docs/components/tabs)
::card[Steps](/docs/components/steps)
::card[Cards](/docs/components/cards)
:::
```

================================================================================
Title: Value tags
URL: https://vellum.jimmyverburgt.com/docs/value-tags
================================================================================

---
title: Value tags
description: Allowlisted env, config, and route lookups that resolve against the live app.
---

Value tags are components that print a value from the running app. Docs files do not compile Blade echoes, so use these tags instead. A tag only resolves when its key is listed in `vellum.components.allowlist`, and an empty list, the default, refuses every key.

```php
'components' => [
    'allowlist' => [
        'env' => ['APP_NAME'],
        'config' => ['vellum.name'],
        'route' => ['vellum.docs.index'],
    ],
],
```

```html
<x-vellum::env key="APP_NAME" />
<x-vellum::config key="vellum.name" />
<x-vellum::route key="vellum.docs.index" />
```

Attributes are plain strings. Bound attributes such as `:key` are not supported.

`env` reads the process environment, as `getenv()` does. After `php artisan config:cache`, Laravel no longer loads `.env`, so a value defined only there renders empty in production. When a config key already holds the value, as `app.name` holds `APP_NAME`, use the `config` tag.

On a live docs site, top-level value tags resolve at request time and are cached with the page fragment. `vellum:export` writes the resolved values into the static HTML, so the snapshot shows the values as they were at export time.

A key missing from the allowlist throws an exception locally and during `vellum:build`. In production the page fails and the exception is logged.

Use value tags when the docs should show a real app value, such as the site name, a named route or an allowlisted environment flag. An allowlisted value appears in the page HTML and in the static export, so allowlist a secret only if you accept that.

================================================================================
Title: Versions
URL: https://vellum.jimmyverburgt.com/docs/versions
================================================================================

---
title: Versions
description: Version folders, unprefixed URLs for the latest version, and the version switcher.
---

Versioning is off by default. When you enable it, your Markdown lives in one folder per version (`docs/v2/`, `docs/v1/`).

```php
'versions' => [
    'enabled' => true,
    'latest' => 'v1',
    'list' => ['next', 'v1'],
    'labels' => [
        'v1' => '1.x (LTS)',
        'next' => 'Next',
    ],
],
```

The `latest` folder is served at `/docs/...` with no version in the URL. Other versions are served under their slug, such as `/docs/v1/...` or `/docs/next/...`. A request for `/docs/{latest}/...` gets a 301 redirect to the unprefixed URL.

`list` runs from newest to oldest, and its order is the order of the switcher. `labels` only changes the switcher text: folders and URLs always use the slug from `list`. A version without a label is shown by its slug.

Where a version sits in `list` also tells Vellum what it is. The one named in `latest` is tagged "Latest" in the switcher. Any version listed before it is newer than the latest, so it is tagged "Unreleased". Any listed after it is an older version.

The changelog stays at `/docs/changelog` for every version. Versions come from `list` in the config, and Vellum does not read git tags.

Each version is a separate Markdown tree, so a page that exists in one version returns a 404 in any version whose folder does not contain it.

## The switcher

With `layout.search` set to `sidebar`, the switcher sits above the search field, at the same size. With `header`, it is a compact button beside the site name, without the tag. Either way its menu lists every version with its tag.

When the page being read does not exist in a version, that version's entry says so, and choosing it opens that version's start page instead.

The switcher is keyboard accessible with the arrow keys, Home, End and Escape. Its trigger's accessible label names the version being read, as in `Documentation version: v2`.

## Reading a version that is not the latest

A page of any version but the latest starts with a notice, so a reader who arrives from a search engine knows which docs they are in:

- On an older version: "You are reading the docs for 1.x (LTS), an older version."
- On an unreleased one: "These are the docs for Next, which is not released yet."

The notice links to the same page in the latest version, or to the latest version's start page when that page does not exist there. Pages of the latest version have no notice.

================================================================================
Title: Gating
URL: https://vellum.jimmyverburgt.com/docs/gating
================================================================================

---
title: Gating
description: Hide pages from guests, require auth, or require a Laravel gate.
---

```yaml
---
title: Billing
access: auth
---
```

Set `access` to `guest` (the default), `auth`, or the name of a Laravel gate. Each page's access is resolved once, into the same visibility set that search uses, and applied to the sidebar, the page route, raw Markdown and search.

`guest` and `auth` are case-insensitive, so `access: Auth` works. Any other value is passed to `Gate::allows()` exactly as written, so it must match the gate's registered name, including case.

Access set on a folder applies to everything below it. Set it in the folder's `meta.json` or `_meta.md`; a page's own `access` overrides it. Links listed in `meta.json` inherit the folder's access too, and a link to a gated page is only shown to readers who can open that page.

```json
{
  "title": "Billing",
  "access": "auth"
}
```

```yaml
---
access: auth
---
```

Guests and users who fail the gate get a 404, so a gated page looks the same as one that does not exist.

`vellum:export` runs as a guest. It leaves out gated pages and prints a warning for each one: `Dropped gated page: {slug} (access: ...)`.

:::warning[Images and other assets are not gated]
Gating applies to pages: the page route, the sidebar, raw Markdown and search. Files under `/{prefix}/_vellum/files/` are assets, and that route serves them to anyone who has the URL. It never serves Markdown, `meta.json`, `_meta.md` or dotfiles, so a gated page's source cannot be read through it, but a diagram stored next to that page can. Keep anything secret out of the docs directory.
:::

================================================================================
Title: Search
URL: https://vellum.jimmyverburgt.com/docs/search
================================================================================

---
title: Search
description: Built-in search in the browser by default, with Laravel Scout as an option.
---

```php
'search' => [
    'enabled' => true,
    'hotkey' => 'k',
    'driver' => env('VELLUM_SEARCH_DRIVER', 'builtin'),
    'scout' => [
        'index' => 'vellum',
    ],
],
```

## In the browser

The default driver is `builtin`. It needs no extra services and works on every host, including sites built with `vellum:export`. `minisearch` is still accepted as its old name.

The browser loads its index from `/docs/_vellum/answers.json`, which holds every section of every page the reader can open. It is filtered for the current user and cached per visibility set (guest, authenticated, and each combination of gates). Responses carry an ETag and are sent with `must-revalidate`, so a browser that already has the current index gets a 304.

`Ctrl+K` or `⌘K` opens search. The arrow keys move through the results, Enter opens one and Escape closes the dialog. A footer in the dialog shows these keys. The dialog's accessible label is "Search documentation".

Results are grouped by page: each page is named once, with its matching sections under it, in the order of the page's best match. The reader's words are marked in each passage.

Before anything is typed, the dialog lists the last five results the reader opened, under "Recent", so they can return to them in two keystrokes. That list is kept in the reader's own browser and never sent to the server.

## How results are ranked

Search works on sections: each heading and the text under it is one result, shown with its page and heading, so a match takes the reader to the right part of a long page. At most two sections of one page are ranked ahead of sections from other pages, and the dialog then shows each page's sections together.

Sections are ranked with BM25 over their title, heading and text, with the title weighted highest. Words are also matched by their stem, so "gate", "gated" and "gating" find each other, and a word matches the start of longer words at a lower weight, so results appear while the reader is still typing. A section whose heading, page title or alias the query names in full is ranked above one that only mentions those words.

Each section is also indexed with questions derived from its content when the docs are built:

| From | Example |
| --- | --- |
| Its heading | "what is meta.json" |
| A shell command in it | "how do i build", "what does vellum:build do" |
| A config key it documents | "what does checks.strict do" |
| A warning or danger callout | "why does assets are not gated fail" |
| A `questions:` list in the page's frontmatter | The questions you write |

A reader's words are expanded with a short built-in list of synonyms (for example "night mode" also searches for "dark mode") and with the `aliases:` a page declares in its frontmatter:

```yaml
---
title: Billing
aliases:
  - invoices
  - payments
---
```

## Checking search in CI

A renamed heading or a rewritten page can move an answer out of reach without breaking a link. To catch that, add a `questions.yml` next to your Markdown with the questions readers actually ask and where each is answered:

```yaml
- q: What does vellum:install publish?
  page: commands
  section: velluminstall
- q: What should a deploy run?
  page: commands
  section: a-deploy
  also:
    - page: getting-started/installation
      section: production
```

`q` is the question as a reader would type it, `page` is the page slug and `section` is the heading id that answers it. Without `section`, any section of the page counts. `also` lists other places that answer the question equally well.

`vellum:build` asks every question against the index it just wrote and reports how many find their answer in the top five results:

```
search check: 42 of 62 questions answered in the top 5 (68%)
  missed: How do I rebuild the search index without recompiling pages? (wanted commands#vellumindex)
```

Set `checks.search_min` (or `VELLUM_SEARCH_MIN`) to the share that must be answered, and the build fails below it. A good starting point is a little under the rate you get today, so a rewrite that makes search worse is caught.

A question whose target no longer exists is reported as a broken question and left out of the count. `--strict` and `checks.strict` fail the build on one. The check uses the index a guest gets, runs whenever the docs have a `questions.yml`, and can be turned off with `checks.search`; `vellum:build --check-search` runs it for one build even when it is off.

```yaml
- run: php artisan vellum:build --check-search --strict
  env:
    VELLUM_SEARCH_MIN: '0.6'
```

## The search endpoint

`{prefix}/_vellum/search?q=` runs the same search on the server and returns JSON, for clients such as agents and scripts that cannot use the browser's index:

```
GET /docs/_vellum/search?q=what+does+vellum:clear+remove
```

```json
{
  "query": "what does vellum:clear remove",
  "results": [
    {
      "url": "/docs/commands#vellumclear",
      "title": "Commands",
      "heading": "vellum:clear",
      "passage": "Removes the compiled pages, the navigation tree, the search index and the rendered component fragments.",
      "updated": "2026-09-20T23:01:13+02:00",
      "score": 2
    }
  ]
}
```

It returns up to five sections, each with its URL, page title, heading, passage and last-updated date. Add `version=` when versions are enabled. An empty `q` returns a 400 response. Results only include pages the caller can open. Set `agents.search` to `false` to turn the endpoint off. A static export has no endpoint, since it has no server.

## Scout

Use Scout if you already run Meilisearch or Typesense and want heading-level relevance on a large docs site.

```bash
composer require laravel/scout
```

Set `VELLUM_SEARCH_DRIVER=scout`. The same visibility filter is applied at query time, and `vellum:build` and `vellum:index` sync the Scout index while that driver is active. Scout searches whole pages on the server, so its results are pages rather than sections.

Each sync replaces the whole index, including every version, so pages you delete, rename or gate do not leave old records behind. Because of this, the index should hold Vellum's records only. `search.scout.index` sets its name and defaults to `vellum`.

When versions are enabled, searches filter on `version`, and the engine has to allow filtering on that attribute. For Meilisearch, add it to the index settings in `config/scout.php` and run `php artisan scout:sync-index-settings`:

```php
'meilisearch' => [
    'index-settings' => [
        'vellum' => ['filterableAttributes' => ['version']],
    ],
],
```

For Typesense, define a collection schema for `Vellum\Search\SearchableDocument` in `model-settings`. It needs `id`, `title`, `content`, `url`, `description`, `access` and `version` as string fields, with `version` marked optional and faceted.

## Export

`vellum:export` always writes the built-in index, whatever `driver` is set to. A static host has no session, so the exported index holds public pages only.

Use `layout.search` to place the search trigger in the sidebar (the default) or in the header.

================================================================================
Title: API reference
URL: https://vellum.jimmyverburgt.com/docs/api-reference
================================================================================

---
title: API reference
description: Reference pages generated from an OpenAPI spec, from a file or from Scramble.
---

Vellum can turn an OpenAPI 3.0, 3.1 or 3.2 spec into reference pages. Each operation gets a page of its own with its parameters, request body, responses and request samples, and the reference has an overview page that lists them all.

```php
'openapi' => [
    'enabled' => env('VELLUM_OPENAPI', false),
    'spec' => env('VELLUM_OPENAPI_SPEC'),
],
```

The pages live under `/docs/api`. They are ordinary pages to the rest of Vellum: search finds them, `vellum:export` writes them, and they are listed in `llms.txt` and the sitemap. Their [raw Markdown](/docs/page-actions#raw-markdown) is written for them, with fields as tables and samples as fenced code.

## What a page looks like

An operation's page opens with its request line, the method and the path. Under it, each part of the operation is a panel: authorization, the parameters by where they go, the request body and one panel per response. A nested object opens in place.

Beside the documentation are the request samples and an example of each response, as [code tabs](/docs/components/tabs#code-tabs). On a wide screen they stay in view while the reader scrolls and take the place of the table of contents. On a narrower one they follow the documentation.

The page's description is the opening paragraph of the operation's `description` in the spec. The rest of the description follows the request line.

Every field has an address made of the names that lead to it, such as `#body-captain-name` or `#response-200-data-id`. Its name is the link: copy it to point someone at one field.

## Where the spec comes from

### A file

Point `spec` at a JSON or YAML file:

```php
'spec' => base_path('openapi.yaml'),
```

In local development the reference follows the file: save it and reload the page. In production the pages are the ones `vellum:build` wrote, as for every page.

### Scramble, in the same app

With [`dedoc/scramble`](https://scramble.dedoc.co) installed and `spec` left as `null`, Vellum asks Scramble for the spec. Nothing else is needed:

```php
'openapi' => [
    'enabled' => true,
],
```

In local development the reference is built again when a PHP file under `app/` or `routes/` changes, so it follows your controllers and form requests. Set `watch` if the code Scramble reads lives somewhere else:

```php
'watch' => [base_path('app'), base_path('routes'), base_path('modules')],
```

Set `scramble` to `false` to never ask Scramble, even when it is installed.

Scramble has a viewer of its own at `/docs/api`, which is also where the reference lives when Vellum is served under `/docs`. Vellum's pages answer there. To keep Scramble's viewer as well, give it another address in a service provider:

```php
use Dedoc\Scramble\Scramble;

Scramble::registerUiRoute('scramble');
Scramble::registerJsonSpecificationRoute('scramble.json');
```

The servers in the spec come from `APP_URL`, so the playground and the samples send requests to the address set there.

### Scramble, in another project

When the docs are a project of their own, export the spec where the API lives and bring the file over. In the API's project:

```bash
php artisan scramble:export --path=openapi.json
```

Copy `openapi.json` into the docs project and point `spec` at it:

```php
'spec' => base_path('openapi.json'),
```

The docs project does not need Scramble. To keep the two in step, run the export in the API's CI and commit the file to the docs project, or download it there before `vellum:build`.

The same works for a spec from any other tool.

## The sidebar

By default the reference has a sidebar to itself. A switch at the top of the sidebar leads from the docs to the reference and back, and the previous and next links stay inside the one the reader is in.

To list the reference as one more folder at the end of the docs' sidebar instead:

```php
'sidebar' => 'docs',
```

Either way the operations are grouped in a folder per tag, in the order of the spec's `tags` list, with the method beside each title. Set `group_by` to `path` to group by the first segment of the path instead. Operations with no tag go in a folder named by `untagged_label`.

A tag can sit inside another, and its folder then sits inside the other's, on the overview page as well as in the sidebar:

```yaml
tags:
  - name: fleet
    summary: Fleet
  - name: ships
    summary: Ships
    parent: fleet
```

- `summary` is the name a reader sees. Without it the tag's `name` is used.
- `parent` names the tag it sits in. A parent with no operations of its own is listed when a tag inside it has some.
- A tag whose `kind` is anything but `nav`, such as `badge`, says something about an operation but is not where it is listed. The operation goes in its first tag that is for navigation.

`summary`, `parent` and `kind` are OpenAPI 3.2. A spec written for Redoc gets the same from `x-displayName` and `x-tagGroups`.

## Request samples

Every operation has a request sample per language in `samples`. `curl`, `php` (the Laravel HTTP client), `javascript` (fetch) and `python` (requests) are built in. The samples use the spec's first server, or `base_url` when you set it.

Samples the spec writes itself, under `x-codeSamples` as Redoc reads them, come first:

```yaml
x-codeSamples:
  - lang: curl
    label: cURL
    source: curl https://api.example.com/ships --json @ship.json
  - lang: Go
    source: client.Ships.Register(ctx, ship)
```

A written sample in a language Vellum also generates, such as `curl`, `php`, `javascript` or `python`, takes the place of the generated one. Any other language is added as a tab of its own.

## Webhooks and callbacks

Each of the spec's `webhooks` gets a page in a **Webhooks** folder, after the operations. A webhook is a request the API sends to an address the reader gives it, so its page shows what arrives: the headers, the payload with an example beside it, and what to answer with. It has no request samples and no playground, and the spec's top-level `security` does not apply to it.

An operation's `callbacks` are listed on its own page, under **Callbacks**: the address the API calls, what it sends and the statuses to answer with.

## The playground

Every operation's page has a **Try it** button on its request line. It opens a drawer beside the page, so the operation stays in view while a reader fills in the request, sends it and reads the response.

- The parameters and the body are a form made from the spec. A JSON body can be written field by field or as JSON, and what is written carries over when the reader switches. An object inside the body has a field for each of its own, named with the path to it, such as `author.name`. A list of objects is written as JSON.
- The command the request makes is shown as curl and follows what is typed.
- Bearer tokens, basic credentials and API keys are supported. For OAuth 2 and OpenID Connect the reader pastes a token. Credentials are kept for the browser tab and are gone when it closes.
- The response is shown as text, with its status, time, size and headers. It is never rendered as a page.

The request goes from the reader's own browser, which decides two things:

- When the API is on the same origin as the docs, which is the usual case for docs served by the app they describe, it goes as the reader. A reader who is signed in to the app is signed in to the request, and Laravel's CSRF token is sent with it.
- When the API is on another origin, nothing of the reader's is sent, and the API has to allow the docs' origin to read its answers ([CORS](https://developer.mozilla.org/en-US/docs/Web/HTTP/CORS)). Otherwise the browser shows no response and the playground says so.

### An API on another origin

When the API does not allow the docs' origin, turn on the forwarding route, and the playground sends such requests through your app instead:

```php
'proxy' => env('VELLUM_OPENAPI_PROXY', false),
```

It is off by default, because it makes your app send requests on a reader's behalf. With it on:

- Only the servers the spec names can be reached, and `base_url` when you set it. A server written as a path, such as `/api`, is your own origin and needs no forwarding.
- A server is reached only at a public address. One on this machine or a private network, such as `localhost`, `10.0.0.5` or a cloud's metadata service, is refused, whether the spec gives the address or a name that leads to it. The request goes to the address that was checked.
- A redirect is shown as the answer and is not followed.
- Nothing of the reader's session with your app is forwarded. No cookies go along, and the only headers that do are `Accept`, `Content-Type`, `Authorization` and those the spec declares as a header parameter or an API key. A header that says where a request came from, such as `X-Forwarded-For`, is never forwarded. The reader's credentials for the API do pass through your server on the way.
- It answers only a reader who may open the reference, behind the docs' [middleware](/docs/getting-started/configuration), and one reader can send 60 requests a minute.
- A file upload is not forwarded. A response is kept up to 2 MB and is given 30 seconds to arrive.

To forward to an API on a private network, as in local development against `http://localhost:8000`, allow it:

```php
'proxy_private' => env('VELLUM_OPENAPI_PROXY_PRIVATE', false),
```

Leave it off in production unless the API really is internal. With it on, anything the spec names on your network is reachable by every reader who may open the reference.

A static export has no app to forward through, so there the playground reaches only an API that allows its origin.

:::warning
A request from the playground is a real request. On a production API, **Try it** on a delete operation deletes.
:::

To leave the playground out:

```php
'playground' => false,
```

## Who may read it

`access` gates the whole reference, with the same values as a page's [`access` frontmatter](/docs/gating):

```php
'access' => 'auth',
```

A reader who may not open the reference is not shown the way to it.

## What a spec can and cannot do

- A description in the spec is Markdown, and Vellum's own directives work in it, a [callout](/docs/components/callouts) for one. Blade components do not: a spec is often someone else's text.
- A `$ref` to another file or a URL is not followed. `vellum:build` warns about each one.
- An operation with the `QUERY` method, or one of the API's own under `additionalOperations`, gets a page like any other. A query string described as one `querystring` parameter is listed as the query parameters it is made of when it is form-encoded.
- The playground cannot read a streamed response, such as server-sent events.
- With [versions](/docs/versions) on, the reference belongs to the latest version only. A spec describes the API as it is.
- A page you wrote yourself under `api/` is still served. A spec whose page would take the same address as one of yours stops the build.

## Configuration

| Key | Default | Purpose |
| --- | --- | --- |
| `openapi.enabled` | `false` | Turns the reference on. |
| `openapi.spec` | `null` | Path to a JSON or YAML spec. `null` asks Scramble. |
| `openapi.scramble` | `true` | Whether to ask Scramble when no spec is set. |
| `openapi.watch` | `null` | Directories whose PHP files Scramble reads. `null` watches `app/` and `routes/`. |
| `openapi.prefix` | `api` | The path segment the reference lives under. |
| `openapi.sidebar` | `separate` | `separate` for a sidebar of its own, `docs` for a folder in the docs' sidebar. |
| `openapi.title` | `API reference` | The reference's name in the sidebar and on its overview. |
| `openapi.group_by` | `tag` | `tag` or `path`. |
| `openapi.untagged_label` | `Other` | The folder for operations without a tag. |
| `openapi.samples` | `curl`, `php`, `javascript`, `python` | Languages of the request samples, in tab order. |
| `openapi.base_url` | `null` | Used in the samples in place of the spec's first server. |
| `openapi.playground` | `true` | Whether a reader can send a request from an operation's page. |
| `openapi.proxy` | `false` | Sends playground requests to another origin through your app. |
| `openapi.proxy_private` | `false` | Lets the forwarding route reach a server on this machine or a private network. |
| `openapi.access` | `guest` | Who may read the reference. |

================================================================================
Title: Release notes
URL: https://vellum.jimmyverburgt.com/docs/releases
================================================================================

---
title: Release notes
description: Keep a Changelog page and Atom feed.
---

Vellum can render a Keep a Changelog file as `/docs/changelog` with an Atom feed at `/docs/changelog.atom`.

```php
'changelog' => [
    'path' => env('VELLUM_CHANGELOG', base_path('CHANGELOG.md')),
    'unreleased' => false,
],
```

Set `path` to `null` to disable the page and feed.

You can keep an `[Unreleased]` section in the file while you work. The feed never includes it, and the HTML page shows it only when `unreleased` is `true`.

The changelog also has a raw Markdown copy at `/docs/_vellum/raw/changelog.md`, like every page (see [Page actions](/docs/page-actions#raw-markdown)). It follows the same rule: with `unreleased` off, the `[Unreleased]` section is removed from it as well. With `unreleased` on, it is the file as written.

Release headings can be written as `## [1.2.0] - 2026-09-13` or `## 1.2.0`.

The changelog is not versioned. It stays at `/docs/changelog` when version folders are enabled.

Vellum's own [changelog](/docs/changelog) is rendered this way.

================================================================================
Title: Export
URL: https://vellum.jimmyverburgt.com/docs/export
================================================================================

---
title: Export
description: Write a static HTML site for GitHub Pages, Cloudflare Workers, or any static host.
---

```bash
php artisan vellum:export
```

The command writes the HTML pages, assets, the search index and a `sitemap.xml` to `public/docs-static`. Change the directory with `export.out`, or pass `--out=` for a single run.

```php
'export' => [
    'out' => public_path('docs-static'),
    'base_url' => '/',
],
```

The export always uses the built-in search, even when `search.driver` is `scout`. Gated pages are left out, and the command logs each one it drops.

When you export into the same directory again, files from the previous export that this run did not write are removed, such as a page you have since deleted or gated. The list of written files is kept in `.vellum-export.json` at the export root. Anything else in the directory, like a `CNAME` file, is left alone.

Value tags are resolved at export time, so the exported pages contain the values the app had when you ran the command.

The sitemap is written to the export root. It uses `base_url` when that is an origin and falls back to `app.url`. If neither is an origin, the sitemap is skipped with a warning, because sitemap URLs have to be absolute. See [Search engines](/docs/seo).

Use the export when the docs need to live on a host that cannot run PHP. If the app is already deployed, it is simpler to serve the docs from it, and value tags, gating and search then resolve against the live application.

================================================================================
Title: Search engines
URL: https://vellum.jimmyverburgt.com/docs/seo
================================================================================

---
title: Search engines
description: The metadata Vellum outputs for crawlers, the sitemap route, and what to put in robots.txt.
---

Every docs page includes the metadata a crawler needs, and a sitemap lists all of them.

## Per page

Each page outputs its own `<title>`, a `<meta name="description">` taken from its frontmatter, a `<link rel="canonical">`, and Open Graph and Twitter card tags. The 404 page is marked `noindex`.

The canonical link is only written when `app.url` is an absolute `http://` or `https://` URL. Otherwise the tag is left out.

:::note
A page without a `description` in its frontmatter gets no meta description. Of all the frontmatter keys, this is the one to fill in on every page.
:::

## Sitemap

```
/docs/sitemap.xml
```

The sitemap is built from the same navigation as the sidebar, so it stays up to date as you add pages. It lists every version when versions are enabled. Gated pages are always left out, even for a signed-in reader, because every visitor gets the same sitemap file.

A page gets a `<lastmod>` when it has a last-updated date: its `updated` frontmatter, or its last git commit when the docs are in a full git clone. Pages without one get no `<lastmod>`. File modification times are not used, because a deploy resets them.

It lives under the docs prefix because the package does not own the site root. A sitemap can list any URL at or below its own path, so this one covers the whole docs tree.

Like the canonical link, the sitemap needs `app.url` to be an absolute URL. Without one the route returns a 404, because sitemap URLs must be absolute.

## robots.txt

Laravel does not ship a `robots.txt` that references a sitemap, so add one:

```
User-agent: *
Allow: /

# Package internals: the search index and embedded files.
Disallow: /docs/_vellum/
# Raw Markdown declares its HTML page canonical, and llms.txt links to it.
Allow: /docs/_vellum/raw/

Sitemap: https://example.com/docs/sitemap.xml
```

Every raw Markdown response sends `Link: <page URL>; rel="canonical"`, naming the HTML page it is a copy of. A crawler that fetches the `.md` file credits the page and does not index the copy as a duplicate. The raw files are also what [`llms.txt`](/docs/page-actions#for-agents) links to, so a `Disallow` for them would stop agents that follow `robots.txt` from reading them.

The rest of `/docs/_vellum/` holds the search index and files that pages embed, which do not need crawling on their own. The longer `Allow` rule takes precedence over the shorter `Disallow`, so only the raw files are crawled.

Like the canonical `<link>`, the header is absolute when `app.url` is an origin. Without one it is root-relative, and a client resolves it against the URL it requested.

## Static export

A static host cannot generate a sitemap, so `vellum:export` writes `sitemap.xml` to the export root. It uses `export.base_url` when that is an origin and falls back to `app.url` otherwise. See [Export](/docs/export).

================================================================================
Title: Commands
URL: https://vellum.jimmyverburgt.com/docs/commands
================================================================================

---
title: Commands
description: The five Artisan commands Vellum adds, and when to run each one.
---

| Command | When you run it |
| --- | --- |
| `vellum:install` | Once, after requiring the package. |
| `vellum:build` | Every deploy. |
| `vellum:index` | When only the search index needs rebuilding. |
| `vellum:clear` | To delete the compiled cache. |
| `vellum:export` | To produce a static site. |

`vellum:install` and `vellum:export` come with the full package. `vellum:build`, `vellum:index` and `vellum:clear` are part of core, so they also work when you use [core on its own](/docs/core).

## vellum:install

```bash
php artisan vellum:install [--force]
```

Publishes `config/vellum.php`, copies starter Markdown into `vellum.path`
(`resources/docs` by default), and copies the compiled CSS and JavaScript into
`public/vendor/vellum`.

Config and Markdown files that already exist are skipped, so running the command again does
not overwrite your work. The CSS and JavaScript are always overwritten.

`--force` overwrites the published config and any starter Markdown files with the same
names. Use it after a package upgrade to get the new stubs, and review the diff before
you commit.

## vellum:build

```bash
php artisan vellum:build [--docs-version=v1] [--strict] [--check-search]
```

Compiles every Markdown file into the cache at `vellum.cache.path`, then rebuilds the
navigation tree and the search index. Run it in your deploy, alongside `config:cache`
and `route:cache`.

In `local`, a page recompiles on the next request after its file changes, so you do not
need to run this while writing. In every other environment the site serves what the last
build compiled. A page added since then returns a 404 until the next build, and the next
build removes pages whose files were deleted or renamed.

The command fails when two files resolve to the same URL, when a `:::` directive name is
not a shipped directive, or when a component or value tag cannot be resolved. It prints a
warning, and still succeeds, when a page has the same URL as the changelog route and is
hidden by it.

It also warns about internal links, images and heading anchors that point at nothing, and
about headings that skip a level. `--strict` makes the link and image warnings fail the
build for that run, the same as setting `checks.strict` to `true`. Heading-level warnings
never fail a build.

`--docs-version` limits the run to a single version folder.

`--strict` turns the warnings about links and images that point at nothing into a failed
build, and `checks.strict` does the same for a deploy script you cannot pass flags to.

`--check-search` asks the questions in `questions.yml`, if your docs have one, even when
`checks.search` is off. See [Search](/docs/search#checking-search-in-ci).

## vellum:index

```bash
php artisan vellum:index [--docs-version=v1]
```

Rebuilds the search index. To do that it compiles every page and the navigation tree the
same way `vellum:build` does, but it skips the build's link, image and heading checks.
`vellum:build` also rebuilds the index, so you only need `vellum:index` on its own when
the index is the only thing out of date.

When `search.driver` is `scout`, it also sends the records to Scout. If that driver is set
but `laravel/scout` is not installed, the command fails with an error saying so. See
[Search](/docs/search).

## vellum:clear

```bash
php artisan vellum:clear
```

Removes the compiled pages, the navigation tree, the search index and the rendered
component fragments. The next request rebuilds what it needs.

It also runs as part of `optimize:clear`, so a normal Laravel cache clear removes Vellum's
caches too.

## vellum:export

```bash
php artisan vellum:export [--out=path/to/dir]
```

Writes a complete static site: HTML for every page, the assets, the raw Markdown, the
search index, a changelog feed if a changelog is configured, and a `404.html` at the
root.

Gated pages are left out, and the command prints a warning for each one it drops. Value
tags are resolved when the export runs. See [Export](/docs/export).

## A deploy

```bash
composer install --no-dev --optimize-autoloader
php artisan config:cache
php artisan route:cache
php artisan vellum:build
```

`vellum:build` writes plain PHP files that OPcache can hold, so serving a page does not
read the Markdown again. Set `vellum.cache.path` to a writable directory that persists
between requests. The default is `storage/framework/vellum`.

================================================================================
Title: Troubleshooting
URL: https://vellum.jimmyverburgt.com/docs/troubleshooting
================================================================================

---
title: Troubleshooting
description: The errors Vellum raises, what each one means, and the failures that raise no error.
---

## Errors you will see

### Invalid frontmatter in [file]: ...

The YAML between the opening and closing `---` did not parse, or the closing `---` is
missing. The message names the file and includes the YAML parser's reason.

The usual causes are an unquoted value that contains a colon (`title: Vellum: docs` needs
quotes) and inconsistent indentation.

### Unknown docs directive [:::name] in [file]

A `:::` block uses a name that is not one of the shipped directives, usually because of a
typo. The shipped directives are `note`, `tip`, `info`, `warning`, `danger`, `success`,
`idea`, `tabs`, `steps` and `cards`.

### Unknown docs component [x-name]

A `<x-…>` tag has no matching Blade view. Check that the view exists and that the tag name
matches its path: `<x-docs::figure>` needs `resources/views/…/docs/figure.blade.php` under
a registered `docs` namespace.

### Component [x-name] is not in vellum.components.namespaces

The view may exist, but its prefix is not allowed in Markdown. Add the prefix to
`components.namespaces`, using `''` or `'app'` for unprefixed host components. See
[Extending](/docs/extending).

### Value tag [x-vellum::env] key [APP_KEY] is not in vellum.components.allowlist

Value tags allow no keys by default, so a docs page cannot print arbitrary config values
or environment variables. Add the key to the matching list under `components.allowlist`.
See [Value tags](/docs/value-tags).

### Unclosed docs component [x-name]

An opening `<x-name>` has no `</x-name>`. A self-closing tag needs the slash:
`<x-vellum::env key="APP_NAME" />`.

### Docs component [x-name] attributes must be quoted strings

An attribute uses a Blade expression, such as `:type="$foo"`. Attributes in Markdown are
literal strings and have no expression syntax. Pass dynamic values through a
[value tag](/docs/value-tags), or compute them inside the component.

### Two docs files resolve to [/slug]

Two files map to the same URL. Either `billing.md` and `billing/index.md` both claim
`/docs/billing`, or two pages set the same frontmatter `slug`. The message names both
files. Rename one of them.

### vellum.search.driver is scout but laravel/scout is not installed

Run `composer require laravel/scout`, or set the driver back to `builtin`. See
[Search](/docs/search).

## Where errors appear

`vellum:build` stops with the messages above.

On the site, a page that raises one of these errors returns a Vellum error page with a 500
status. When `APP_DEBUG` is on, as it usually is in `local`, the page shows the message and
the file. When it is off, the page says only that it could not be rendered, and the details
go to your log. Run `vellum:build` in your deploy before the app goes live so these errors
stop the deploy instead of reaching readers. See [Commands](/docs/commands).

## Failures that are quiet

These raise no error, so you have to spot them yourself.

| Symptom | Cause |
| --- | --- |
| A page shows its frontmatter as body text | The file does not start with `---` on the first line. A block that opens but never closes raises an error instead. |
| An image 404s | Image paths resolve from the docs root, not from the page's folder. See [Images](/docs/writing/images). |
| A `<details>` or `<div>` has disappeared | Raw HTML is stripped. Use a component instead. See [Markdown](/docs/writing/markdown). |
| `:::note title="x"` has no title | Only the bracket form sets a title: `:::note[x]`. |
| `::card[Title]` renders as literal text | A card needs a link: `::card[Title](/path)`. |
| A page is missing from the sidebar but loads by URL | The page or one of its parent folders is gated. See [Gating](/docs/gating). |
| A page you left out of `meta.json` still appears in the sidebar | `pages` sets the order of the sidebar but does not remove anything from it. See [Navigation](/docs/writing/navigation). |
| A table of contents entry does not scroll anywhere | The heading is inside a `:::tabs` panel that is not showing. See [Tabs](/docs/components/tabs). |

## Editing changes nothing

In `local`, a page recompiles when its file changes. In every other environment Vellum
serves the compiled cache until you rebuild:

```bash
php artisan vellum:build
```

If a page is still out of date after that, clear the cache and rebuild:

```bash
php artisan vellum:clear
php artisan vellum:build
```

The same applies to adding, deleting and renaming pages. Outside `local`, a new page is
served once `vellum:build` has compiled it, and a deleted or renamed page stops being served
after the next `vellum:build`.

## The site has no styling

Vellum registers routes under `/vendor/vellum/`, including `/vendor/vellum/vellum.css`
and `/vendor/vellum/vellum.js`, that serve the compiled assets directly from the package.
Styling therefore works on a server where `vellum:install` has never run, and you do not
need to publish or commit the assets.

`vellum:install` also copies the files into `public/vendor/vellum`. When they are there,
the web server serves them as static files and the routes are never called, which saves a
PHP request per asset. Either setup works.

If pages are unstyled, the routes cannot be reached. Check that the package is discovered
(`php artisan route:list | grep vellum.assets`) and that nothing in your app intercepts
`/vendor/*`.

## Search returns nothing

Check that `search.enabled` is `true`, then rebuild the index with `vellum:build` or
`vellum:index`. Gated pages are left out of the results for readers who cannot open them;
that is intended.

## Still stuck

Open an issue with the page's Markdown, the relevant part of `config/vellum.php`, and the
output of `php artisan vellum:build`.

================================================================================
Title: Theming
URL: https://vellum.jimmyverburgt.com/docs/theming
================================================================================

---
title: Theming
description: Three contrast-tested presets, a brand accent, corner radius, and a light, dark or system default.
---

```php
'theme' => [
    'preset' => 'neutral',
    'primary' => null,
    'accent' => null,
    'radius' => '0.5rem',
    'default' => 'system',
],
```

## Presets

| Preset | Notes |
| --- | --- |
| `neutral` | The default grey. `primary` (an oklch hue) only applies to this preset. |
| `ocean` | Cool blue page and a deep navy accent, with a near-black navy dark mode. |
| `laravel` | The laravel.com colours: warm sand neutrals and the Laravel red. |

An unknown preset name falls back to `neutral`.

Every preset defines the same set of tokens and is contrast-tested in light and dark mode.
See [Surfaces](#surfaces) and [Contrast](#contrast).

:::note
0.5 removed nine presets: `black`, `vitepress`, `dusk`, `catppuccin`, `purple`, `solar`,
`emerald`, `ruby` and `aspen`. A config that still names one falls back to `neutral`. Most of these presets only changed the
accent colour, which you can now set on any preset with `accent`.
:::

## Surfaces

Every preset uses the same three surface layers in both modes:

| Token | Used for | Position |
| --- | --- | --- |
| `--background` | prose | the canvas, at the light or dark extreme |
| `--card` | sidebar, tab groups, the next-page card, popovers | one step toward mid-grey |
| `--muted` | code blocks, table headers, image mats, step markers | a second step |

Each layer steps away from the canvas in one direction: darker in light mode and lighter
in dark mode. The reading surface stays the cleanest part of the page, and nested elements
go one step deeper, so a code block inside a tab group sits below the group. The contrast
test checks both the direction and the order.

## Accent

`accent` recolours links, buttons and the focus ring on any preset. Set one colour for
both modes, or one per mode:

```php
'accent' => '#7c3aed',
```

```php
'accent' => [
    'light' => '#1d4ed8',
    'dark' => '#bfdbfe',
],
```

Hex, `hsl()` and `oklch()` values are accepted. The button label colour is derived from
the accent: a light accent gets dark text and a dark accent gets white text. A value that
cannot be parsed is ignored and the page renders with the preset's own colours.

`primary` is the older option and still works, but it only sets an oklch hue on
`neutral`. Use `accent` instead.

## Contrast

Every shipped preset meets WCAG AA (4.5:1) in both modes for:

- body text on the page background
- secondary text (sidebar items, breadcrumbs, table of contents, page meta)
- link and accent text
- button labels on a filled button

Syntax highlighting uses one palette for light mode and one for dark, shared by every
preset. Each token colour clears 4.5:1 on every preset's code surface, so a preset changes
the code block background and leaves the token colours alone.

`tests/View/PresetContrastTest.php` reads the shipped stylesheets and fails if a palette
change drops below these ratios. A custom `accent` is not covered by that test, so choose
one that clears 4.5:1 against your page background.

## Default mode

`default` sets the mode a first-time reader gets: `light`, `dark` or `system`, which
follows the operating system. Readers can change it from the theme menu. Their choice is
stored in `localStorage` and takes precedence over this setting from then on.

## Radius

`radius` sets the `--radius` CSS variable on the document. The rounded corners of the
layout are derived from it, so cards, buttons, code blocks and the search dialog change
together. Only a few small inline details, such as inline code and task checkboxes, keep a
fixed radius. Any CSS length works.

Surfaces such as code blocks, tab groups, cards, tables and the search dialog are rounded
4px past `radius`. Anything set inside a surface, like the panel of a tab group, follows the
surface's curve: its radius is the surface's less the gap between them, so the two corners
nest evenly at any `radius`.

```php
'radius' => '0.25rem',
```

## Fonts

`fonts` is a top-level config key, separate from `theme`. Its value is added to the layout
head as raw HTML, so you can load a web font without publishing the layout:

```php
'fonts' => '<link rel="stylesheet" href="https://example.com/inter.css">',
```

Loading the font does not apply it. Set the family in a stylesheet the layout already
loads, or add a `<style>` block to the same value:

```php
'fonts' => '<link rel="stylesheet" href="https://example.com/inter.css">'
    .'<style>body { font-family: Inter, sans-serif }</style>',
```

## Where search sits

`layout.search` is either `sidebar` (the default, which also removes the top header) or
`header`.

With `sidebar`, the site name, the version switcher, search and the button that collapses the
sidebar are all in the sidebar. With `header`, they move to a bar across the top, and the
sidebar holds only the navigation.

## Table of contents

The table of contents beside each page comes in two styles. Choose one with
`layout.toc`, or set `VELLUM_LAYOUT_TOC`:

```php
'layout' => [
    'toc' => 'window', // or 'line'
],
```

`window` is the default. One highlight sits behind every entry whose section is on screen,
so it shows how much of the page you are looking at. As you scroll, its edges hold on to
whole entries and spring to the next one when a section leaves the screen or a new one
comes onto it. Nested entries hang from a guide line.

![The window style: one highlight behind the sections on screen](images/toc-window.png)

`line` draws a line beside the entries and lights the part next to the sections on
screen, bending in and out with nested entries.

![The line style: a line lit beside the sections on screen](images/toc-line.png)

In both styles, a step from a [steps](/docs/components/steps) block shows its number, filled
while the step is on screen. In the line style the numbers sit on the line.

================================================================================
Title: Page actions
URL: https://vellum.jimmyverburgt.com/docs/page-actions
================================================================================

---
title: Page actions
description: Copy Markdown, raw source URLs, llms.txt, Edit on GitHub, and opening a page in ChatGPT or Claude.
---

Every page has a line under its title and description. On the left it says when the page
last changed, from its `updated` frontmatter or its last git commit, and how long it takes to
read when that is three minutes or more. A change in the last month reads as "Updated 3 days
ago", with the date in its tooltip. If the page changed since the reader last opened it, the
line also says "Changed since your last visit", with the dot the sidebar puts on that page.

On the right are the page's actions. They let a reader copy the page's source, edit it on
GitHub, or open it in an AI chat tool.

## Copy Markdown

Copies the page's Markdown source to the clipboard, including the frontmatter. You can
paste it straight into a chat with a model, which then has the page without fetching
anything.

## Raw Markdown

Every page is also served as plain Markdown:

```
/docs/writing/markdown        the page
/docs/_vellum/raw/writing/markdown.md   its source
```

The raw route returns `text/markdown` and follows [gating](/docs/gating) with no extra
configuration: a page the reader cannot see returns a 404 here as well.

`vellum:export` writes the same files to `_vellum/raw/`, so the raw links also work on a
static site.

Each raw response names its HTML page in a `Link: <...>; rel="canonical"` header, so
search engines treat the HTML page as the original. When
versions are enabled, raw responses also carry an `X-Vellum-Docs-Version` header naming
the version. A page with a last-updated date, from its `updated` frontmatter or its last
git commit, gets a `Last-Modified` header; a page without one gets none. The body stays
the file as written.

The changelog has a raw copy too, at `/docs/_vellum/raw/changelog.md`, served from
`changelog.path`. It leaves out `[Unreleased]` whenever the HTML page does. See
[Release notes](/docs/releases).

## For agents

The raw Markdown is also useful to tools that read docs on their own, such as coding
agents. Vellum points them to it in four ways and offers a search endpoint as well.

**llms.txt.** `/docs/llms.txt` is an index of the docs in the
[llms.txt](https://llmstxt.org) format: the site name, the index page's description, then
the sidebar as `##` sections in sidebar order, with a line per page linking to its raw
Markdown.

```
# Acme

> Everything about Acme.

## Docs

- [Home](https://example.com/docs/_vellum/raw/index.md): Everything about Acme.

## Getting started

- [Installation](https://example.com/docs/_vellum/raw/getting-started/installation.md)
```

Each top-level folder is a section, with anything nested in it flattened in. A run of
top-level pages is a section too, headed by the titled separator above it, or by the root
`meta.json` title (`Docs` without one) before any separator. When a run picks up again
after a folder, its heading repeats with "(continued)", so no two sections share a name.
The page description follows the link when the page has one.

The changelog is listed too, linking to its raw Markdown. It sits where the sidebar puts
it, or, when the sidebar does not list it, last under `## Optional`, the heading llms.txt
reserves for links an agent can skip when it is short on room.

**llms-full.txt.** `/docs/llms-full.txt` is every page's Markdown source in one file, in
sidebar order. Each page starts with a header block between two lines of 80 `=`
characters:

```
================================================================================
Title: Installation
URL: https://example.com/docs/getting-started/installation
Version: v2
Updated: 2026-09-17
================================================================================
```

`Version` only appears when versions are enabled, and `Updated` only when the page has a
last-updated date. The changelog belongs to no one version, so its block has no `Version`,
and its source leaves out `[Unreleased]` whenever the HTML page does.

Both files are built from the same navigation as the sidebar and the
[sitemap](/docs/seo#sitemap), with the same rules: gated pages are left out even for a
signed-in reader, since each is one public file. They cover the latest version only.
Links are absolute when `app.url` is an origin and root-relative otherwise.
`vellum:export` writes both at the export root. Set `agents.llms_txt` to `false` to turn
them off.

Agents look for `llms.txt` at the site root, so both files are also served at `/llms.txt`
and `/llms-full.txt`, on `route.domain` when that is set. Vellum only adds these routes
when your app has no route for the same path, and a route your app defines takes
precedence. Set `agents.llms_txt_root` to `false` to keep them
under the docs prefix only.

The links in `llms.txt` point under `/docs/_vellum/raw/`, so keep that path open in
`robots.txt`. [Search engines](/docs/seo#robotstxt) has the rules to use.

**An alternate link.** Every page's head has
`<link rel="alternate" type="text/markdown">` pointing at its raw Markdown, and the
response sends the same URL in a `Link` header.

**Content negotiation.** Request a page with `Accept: text/markdown` and the response is
the raw Markdown instead of HTML, the same body the raw route returns. This applies when
`Accept` lists `text/markdown` with a higher preference than `text/html`, so browsers
still get HTML. Gating applies as it does on the raw route. Page responses send `Vary: Accept` so a
cache keeps the two apart. Set `agents.content_negotiation` to `false` to turn it off.

**A search endpoint.** `/docs/_vellum/search?q=` runs the same search as the browser and
returns the top sections as JSON, for clients that cannot use the browser's index. See
[Search](/docs/search#the-search-endpoint).

## Open in ChatGPT / Open in Claude

Both open the chat tool with a prompt that points to the page's raw Markdown URL.

The model has to fetch that URL, so this only works for docs on the public internet. For
docs on localhost or behind a login, use Copy Markdown and paste the source instead.

:::note[Why the raw Markdown URL]
The raw file contains only the page content. A model reading the rendered page also
has to process the navigation, sidebar and other layout, which uses more tokens and gives
less accurate answers.
:::

## Edit on GitHub

Set `repo` to the base URL of your docs directory in source control:

```php
'repo' => 'https://github.com/acme/app/edit/main/resources/docs',
```

Vellum appends the page's path relative to `vellum.path`, so
`resources/docs/billing/invoices.md` becomes
`https://github.com/acme/app/edit/main/resources/docs/billing/invoices.md`.

The link only appears when `repo` is set. Use an `/edit/` URL to open GitHub's editor,
or a `/blob/` URL to open the file view.

No link is shown for a file whose real path is outside `vellum.path`, so a symlinked page
cannot expose a path from elsewhere on disk.

## Changing them

The actions have no config option. To change them, override the view. Vellum registers its
views under the `vellum` namespace, so a file at the matching path in your app takes
precedence:

```
resources/views/vendor/vellum/components/docs/page-actions.blade.php
```

Creating that file replaces the shipped view, and an empty file removes the actions and
leaves the date beside them. To change or remove the whole line, override
`components/docs/page-meta.blade.php` the same way. You do not need to publish anything
first. The same works for every other Vellum view.

:::warning
Views are not frozen the way config keys and frontmatter are. An override is a copy and
does not receive fixes or markup changes from later releases, so keep it as small as you
can.
:::

================================================================================
Title: Extending with your own components
URL: https://vellum.jimmyverburgt.com/docs/extending
================================================================================

---
title: Extending with your own components
description: Register Blade components for use in Markdown.
---

Docs pages are written in Markdown and can include Blade components. Vellum does not compile `{{ }}`, `@if` or `@php` in docs files, and fenced or inline code containing them is shown as text. Component attributes are quoted strings that reach the component as data, so a `{{ … }}` inside an attribute is rendered as literal text and never executed.

:::note[Raw HTML is stripped]
Vellum parses Markdown with `html_input: strip`, so a `<details>`, `<img>` or `<div>` written straight into a page is removed without a warning. For anything Markdown cannot express, write a Blade component.
:::

## Namespaces

`vellum.components.namespaces` defaults to `['vellum']`, which allows `<x-vellum::…>` tags and rejects unprefixed ones such as `<x-alert>`.

Add `''` or `'app'` to allow unprefixed host components:

```php
'components' => [
    'namespaces' => ['vellum', 'app'],
],
```

A view at `resources/views/components/alert.blade.php` can then be used as `<x-alert type="ok">…</x-alert>` in Markdown.

To use a named prefix, register a view namespace in your service provider and add the prefix to the list. For example, `<x-docs::figure>` needs `'docs'` in `namespaces`.

Vellum caches the rendered HTML of pages that use only its own components. A page that uses one of yours is rendered on every request, so your component can read the signed-in user, the session or the request and show each reader their own output.

## Slots

The body of a paired tag is Markdown and can contain nested components. Vellum extracts each balanced `<x-…>` tag as an island, converts the rest of the document to HTML, converts each slot, and then renders the islands with Blade, innermost first.

```html
<x-alert type="ok">
Hello **docs**
</x-alert>
```

A self-closing tag such as `<x-vellum::env key="APP_NAME" />` has no slot.

Attributes must be quoted strings. Bound attributes such as `:type="$foo"` are rejected.

## Built-ins share Blade views

`:::note` and `<x-vellum::callout type="note">` both render the `vellum::components.callout` view. Use `:::` for the built-in callouts, tabs, steps and cards, and `<x-…>` for components you add.

<x-vellum::callout type="tip" title="Same view">
This callout is written as an `<x-vellum::callout>` tag and renders the same markup as `:::tip`.
</x-vellum::callout>

## Change a built-in's markup

To change what a built-in renders, put your own copy of its view in `resources/views/vendor/vellum/components/`, named after the component: `callout`, `card`, `cards`, `step`, `steps`, `tab` or `tabs`. Yours is used for both the `:::` and the `<x-vellum::…>` form.

Start from Vellum's copy, which receives the same data. Most are in `vendor/jimmyverburgt/vellum/packages/core/resources/views/components/`. The site's `tabs.blade.php`, with the script that switches tabs, is in `vendor/jimmyverburgt/vellum/resources/views/components/`.

Compiled pages keep the HTML they were built with, so run `php artisan vellum:clear` after adding or changing a view.

## Missing components

An unknown tag, a namespace that is not allowed, or a value-tag key missing from the allowlist throws an exception in the local environment and during `vellum:build`. In production that page fails and the exception is logged, so the component is never silently left out.

================================================================================
Title: Core on its own
URL: https://vellum.jimmyverburgt.com/docs/core
================================================================================

---
title: Core on its own
description: Use Vellum's content engine without its routes and layout.
---

Vellum is two Composer packages, released together under one version:

- `jimmyverburgt/vellum` is the docs site: routes, layout, theme, search dialog, and the `vellum:install` and `vellum:export` commands.
- `jimmyverburgt/vellum-core` is the engine under it. It reads the docs folder and handles frontmatter, navigation, versions, gating, Markdown, the compiled cache, search and the changelog.

Installing `jimmyverburgt/vellum` includes core, and that is what most apps want. Require core on its own when you render the docs yourself, for example in an Inertia or Livewire front end, or when a package of yours reads the docs:

```bash
composer require jimmyverburgt/vellum-core
```

## What core provides

- `config/vellum.php`, published with `php artisan vendor:publish --tag=vellum-config`. Core reads `path`, `versions`, `route`, `components`, `search`, `checks`, `changelog` and `cache`, the last for where compiled pages go. `route.prefix` is the start of every link core builds. The other keys, such as `layout`, `theme` and `export`, belong to the site and do nothing without it.
- `vellum:build`, `vellum:index` and `vellum:clear`, which work as described in [Commands](/docs/commands).
- No routes, controllers, layout, styles or scripts.

## Pages

`ContentRepository` is the entry point. It finds pages by slug, compiles them when they changed, and checks them against the reader's access:

```php
use Vellum\Content\ContentRepository;

$docs = ContentRepository::fromConfig();
$page = $docs->find('getting-started/installation');

if ($page === null || ! $docs->allows($page)) {
    abort(404);
}

$page->title;               // frontmatter, the first heading, or the file name
$page->description;
$page->headings;            // for a table of contents
$docs->render($page);       // the page's HTML, components included
$docs->navigation();        // the sidebar tree this reader may see
$docs->adjacent($page->slug); // previous and next pages, each with its section when that differs
```

Use `render()` rather than `$page->html`. The stored HTML holds a placeholder for each Blade component in the page, and `render()` puts the rendered components in their place.

## Markup

The HTML uses `vellum-*` classes and `data-vellum-*` attributes and carries no styles. Style it with your own CSS, or start from the site's `resources/css/vellum.css`.

A few parts need a script to work:

- Code blocks have a copy button marked `data-vellum-copy-code`, inside the block's `data-vellum-code` element. Its `data-vellum-code-kind` is `file`, `terminal` or `snippet`, and in a terminal each command line has the class `vellum-code-command`, for a prompt drawn with CSS.
- Headings have a copy-link button marked `data-vellum-heading-copy`.
- Table cells carry their column's heading in `data-label`, for laying rows out as blocks on a narrow screen, and an image alone in its paragraph is marked `data-vellum-image-block`.
- Tabs follow the WAI-ARIA tabs pattern, with the first panel open and the others `hidden`.

To change the markup of a component, see [Change a built-in's markup](/docs/extending#change-a-built-ins-markup).

## Search

`vellum:build` writes a search index for each version. To query it for the current reader:

```php
use Vellum\Answers\AnswersQuery;
use Vellum\Answers\Ranker;

$query = new AnswersQuery;
$index = $query->index($docs, version: null);
$visible = $index->forAccess($query->allowed($index));

$results = (new Ranker($visible))->search('deploy', 10);
```

Each result's `record` has the page, heading, URL and a passage of text. This is the same ranking the site's search endpoint uses. See [Search](/docs/search).

================================================================================
Title: Credits
URL: https://vellum.jimmyverburgt.com/docs/credits
================================================================================

---
title: Credits
description: The open source Vellum is built on, and the work it takes its cues from.
---

Vellum is built on other people's open source work. This page lists the projects it uses and the ones it borrows ideas from.

## Inspiration

Vellum's design follows [Fumadocs](https://fumadocs.dev). The sidebar and
table-of-contents layout, the `:::` directive syntax, code tabs with a shared chrome, and
the approach of treating a docs framework as a design system all come from Fumadocs.
Fumadocs is a React and Next.js project. Vellum provides the same kind of docs site for a
Laravel app, without adding a second codebase. If you are building on Next.js, use
Fumadocs.

The syntax highlighting palette is GitHub Light and GitHub Dark, the Shiki themes Fumadocs
uses by default, so code looks the way it does on GitHub and in most editors.

## Rendering

| Package | What it does |
| --- | --- |
| [league/commonmark](https://commonmark.thephpleague.com) | CommonMark and GitHub Flavored Markdown. Vellum's directives, callouts, tabs, steps and cards are extensions on top of it. |
| [tempest/highlight](https://github.com/tempestphp/highlight) | Server-side syntax highlighting, so no highlighter ships to the browser. |
| [league/config](https://config.thephpleague.com) | The options schema CommonMark's extensions, including Vellum's, are configured through. |
| [symfony/yaml](https://symfony.com/doc/current/components/yaml.html) | Page frontmatter. |
| [symfony/process](https://symfony.com/doc/current/components/process.html) | Runs git to find when each page last changed. |
| [tales-from-a-dev/tailwind-merge-php](https://github.com/tales-from-a-dev/tailwind-merge-php) | Resolves conflicting Tailwind classes when a component's classes are overridden. |

## Interface

| Package | What it does |
| --- | --- |
| [Phosphor Icons](https://phosphoricons.com) | Every icon in the chrome, the callout glyphs and the code-block language marks. Regular weight for chrome, fill for glyphs. MIT. |
| [Tailwind CSS](https://tailwindcss.com) | The stylesheet, built to a single file at release time. |
| [Alpine.js](https://alpinejs.dev) | The theme toggle, tabs, dialogs, sidebar and table-of-contents behaviour, with the anchor, collapse and focus plugins. |
| [Vite](https://vite.dev) | Builds the CSS and JS bundles. |

## Foundations

Vellum relies on [Laravel](https://laravel.com) for routing, Blade, caching, gates and
config, which is what lets the docs run inside the app you already deploy.

Testing and quality tooling: [Pest](https://pestphp.com),
[Orchestra Testbench](https://packages.tools/testbench),
[PHPStan](https://phpstan.org) with [Larastan](https://github.com/larastan/larastan), and
[Laravel Pint](https://laravel.com/docs/pint).

## Search

Search ranks sections with BM25, using the scoring constants of [MiniSearch](https://github.com/lucaong/minisearch), which Vellum used for search before 0.7.

## Licences

Vellum is MIT licensed. Every package above is MIT or BSD licensed. Run
`composer licenses` in your app to see the exact terms for the versions you have installed.

================================================================================
Title: Changelog
URL: https://vellum.jimmyverburgt.com/docs/changelog
================================================================================

# Changelog

All notable changes to this project are documented in this file.

The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).

## [0.9.2] - 2026-10-16

### Added

- Webhooks: each of the spec's `webhooks` gets a page in a **Webhooks** folder, with the headers and payload it arrives with, an example payload beside them, and what to answer with. It has no samples or playground, and the spec's top-level security does not apply to it
- Callbacks: an operation's page lists the requests the API sends back, with the address, the payload and the statuses to answer with
- Samples a spec writes itself under `x-codeSamples` (or `x-code-samples`) come first among the request samples, and take the place of a generated one in the same language
- A Python sample, with requests, is generated alongside curl, PHP and JavaScript. `openapi.samples` lists `python` by default; a published config keeps its own list
- Every field in a parameter list or schema has an address made of the names that lead to it, such as `#body-captain-name`, and its name links to it

### Changed

- The build's link check lets a `#fragment` land on anything on the page with that id, not only a heading, so links to a field of the reference or to a footnote pass

## [0.9.1] - 2026-10-15

### Added

- OpenAPI 3.2 specs are read. A tag's `summary` names its folder, `parent` puts it inside another tag's on the overview and in the sidebar, and a tag whose `kind` is not `nav` no longer becomes a folder. A Redoc spec gets the same from `x-displayName` and `x-tagGroups`
- An operation with the `QUERY` method, or one of the API's own under `additionalOperations`, gets a page, a colour of its own for QUERY, samples and the playground. The PHP sample sends such a method with `send()`
- A form-encoded `querystring` parameter is listed, sampled and filled in as the query parameters it is made of
- A server's `name` is shown on the overview, and a security scheme marked `deprecated` says so where it is listed
- An example given as `dataValue` is used, and a parameter's named `examples` now give its value in samples and the playground

### Fixed

- On an operation's page, the examples beside the documentation showed a scrollbar laid over the edge of their panels on a screen too short for both. The samples are now sized to the screen so the request and the response fit together, and the column has no bar of its own
- On a page with no date and no reading time, **Copy Markdown** and **Open** had a row to themselves under the description. They sit beside the title, and under the description on a narrow screen
- **Try it** sat further from the right end of the request line than the method from its left end. Both ends match

## [0.9.0] - 2026-10-13

### Added

- An API reference generated from an OpenAPI 3.0 or 3.1 spec, turned on with `openapi.enabled`. Each operation is a page of its own in a sidebar folder per tag, with the method beside its title, and the reference has an overview page. The pages are ordinary pages to the rest of Vellum: they are searched, exported, listed in `llms.txt` and the sitemap, and gated with `openapi.access`. Their raw Markdown is written for them, with fields as tables and samples as fenced blocks. Request samples are generated for curl, the Laravel HTTP client and fetch. With `dedoc/scramble` installed and no `openapi.spec` set, the spec comes from Scramble, and in local development the reference follows the app's code without a build
- An operation's page opens with its request line, tinted with its method's colour, and sets each section in a panel: authorization, parameters, the request body and each response. Request samples and response examples are code tabs beside the documentation on a wide screen, where they stay in view and take the place of the table of contents
- A playground on every operation's page: **Try it** opens a drawer beside the page with a form made from the spec, the curl command it makes, and in a tab beside that the response with its status, time, size and headers. Requests go from the reader's browser, as the reader on the docs' own origin and with nothing of theirs on any other. A response is shown as text and never rendered. `openapi.playground` set to `false` leaves it out. Its script is fetched when a reader first opens it. An object inside a body has a field for each of its own, such as `author.name`
- `openapi.proxy` sends a playground request to another origin through the app, for an API that does not let a browser on the docs' origin read its answers. It is off by default, reaches only the servers the spec names and only at a public address unless `openapi.proxy_private` allows a private one, follows no redirect, forwards no cookie of the reader's and no header the spec does not declare, and is limited to 60 requests a minute for one reader
- The reference has a sidebar of its own, with a switch between it and the docs at the top of both. `openapi.sidebar` set to `docs` lists it as a folder of the docs' sidebar instead. `ContentRepository::sidebar()` returns the tree for one page and `sections()` the sidebars a reader can switch between

### Fixed

- A terminal code block showed a prompt before every line of a quoted argument that ran over several lines, such as a JSON body passed to curl. It shows one, before the command
- A code block inside a directive, such as a tab or a callout, lost an indent of one to three spaces from each of its lines, so YAML or JSON indented by two came out flat. The indent is kept
- A line of `:::` inside a fenced code block closed the directive the block was in. It is a line of code

### Security

- `league/commonmark` 2.10.2 or later is required. Earlier versions let a table take a very long time to parse and let a disallowed HTML tag through in one case

## [0.8.2] - 2026-10-06

### Changed

- On a wide screen the page sits in the middle of the space beside the sidebar, with the table of contents to its right, where it used to sit against the sidebar. The gap to the table of contents widens from 1536px up. On a narrower screen nothing moves

## [0.8.1] - 2026-10-06

### Fixed

- The two table of contents images on the Theming page were left out of the installed package, so a strict build of the bundled docs failed with two broken images

## [0.8.0] - 2026-10-06

### Added

- `jimmyverburgt/vellum-core`, the content engine as a package of its own: pages, navigation, versions, gating, Markdown, the compiled cache, search and the changelog, with no routes, layout or assets. `jimmyverburgt/vellum` includes it, so installing Vellum is unchanged. See Core on its own in the docs
- `ContentRepository::render()`, which returns a page's HTML with its components rendered
- An app can replace the markup of a built-in component, for both the `:::` and the `<x-vellum::…>` form, by publishing its view to `resources/views/vendor/vellum/components/`. Before, `:::` blocks ignored a published copy
- The sidebar remembers its scroll position between pages and scrolls the current page into view when it is hidden
- A dot in the sidebar on pages that changed since the reader last opened them. What a reader has opened is kept in their browser
- The highlight on the current page slides over from the page the reader came from, and fills as they read down the page. Moving the pointer over the sidebar moves a lighter highlight with it. Both sit under the text and respect reduced-motion settings
- Folders in the sidebar have a guide line, shown in the primary colour for the folder holding the current page
- A new table of contents style, `window`, now the default: one highlight behind every entry whose section is on screen, whose edges hold on to whole entries and spring to the next one as sections come and go. Nested entries hang from a guide line, and a lighter highlight follows the pointer. The new `layout.toc` key (or `VELLUM_LAYOUT_TOC`) set to `line` keeps the line style
- Steps from a `:::steps` block show their number in the table of contents, filled while the step is on screen. In the line style the numbers sit on the line
- A line under each page's title says when the page last changed, as "3 days ago" for the last month, and how long it takes to read for pages of three minutes or more. When the page changed since the reader last opened it, the line says so, with the sidebar's dot. The page's actions sit on the same line
- Steps follow the reader: the line between the numbers fills as they read, each number fills once its step is reached, and the table of contents keeps those numbers filled too. The number of the step being read stays in view, and clicking it goes back to the start of the step
- A shell block without a title is shown as a terminal, with a `$` before each command. Blank lines, `#` comments and continuations of a line ending in `\` get none, and the `$` is never selected or copied. `console` is accepted as a shell language
- Copying a code block sweeps a light wash down the code that was copied
- Every callout names its type, "Note", "Warning" and so on, on its first line, or says it to screen readers before an author's title. Before, the type was shown only by colour and a glyph screen readers skip
- Tab groups that share a `persist` key follow each other at once on the page, not only on the next page load, and the group the reader clicked stays where it is on screen while the others change height
- Cards can have a description: any text after the link on a `::card` line. `:::cards describe="pages"` gives cards without one the linked page's own frontmatter description, filled in from the navigation when the page is shown, so it never goes stale and a gated page's description is only shown to readers who may open it. A card linking outside the docs shows the site's domain
- The header row of a table that fits the page stays at the top of the window while the reader scrolls it, and on a phone each row becomes a block with every value under its column's heading instead of a table that scrolls sideways
- An image shown smaller than it is can be opened at full size with a click or Enter, and closed with Escape
- The search dialog groups results by page, with each page named once and its sections under it, and lists the last five results the reader opened before they type. The recent list stays in the reader's browser. A footer shows the keys, and the arrow keys scroll the active result into view
- The previous and next links are labelled, and name the neighbouring page's folder when it differs from the current page's, as in "Next · Components". `adjacent()` returns that folder as `section`
- A page of any version but the latest starts with a notice saying it is an older or an unreleased version, with a link to the same page in the latest. A version listed before `latest` in `versions.list` counts as unreleased, and `VersionLabel::kind()` says which a version is
- The version switcher tags the latest and unreleased versions, and says when the page being read is not in a version, where choosing it opens that version's start page

### Changed

- Classes that only the site uses moved namespace: `Vellum\Support\Theme`, `Color`, `Assets`, `Cn` and `NavTree` are now in `Vellum\View`, and `Vellum\Support\LlmsTxt`, `Vellum\Support\Sitemap` and `Vellum\Changelog\ChangelogFeed` are in `Vellum\Http`. This affects code that used these classes, and views copied from 0.7 into `resources/views/vendor/vellum/`: the sidebar, the layout and the `ui` views name them. The upgrade guide lists what to change
- Errors in the docs, such as an unknown directive, implement `Vellum\Exceptions\ContentError`. The site renders these as its error page; with core alone, Laravel handles them like any other exception
- The copy buttons on code blocks and headings are marked with `data-vellum-copy-code` and `data-vellum-heading-copy`, and one script handles every button, instead of an Alpine component on each. Rendered Markdown no longer contains Alpine attributes, apart from tabs
- Every rounded corner now follows `theme.radius`, as the theming docs promised: code blocks, tab groups, tables, images and the floated sidebar were fixed at their own values. Surfaces are rounded 4px past `radius`, and anything inset in one, such as a tab panel, is rounded to nest evenly inside it
- The table of contents marks the active entry with colour instead of a heavier weight, which made entries shift sideways, and the line style no longer has a dot
- The last-updated date moved from the breadcrumb row to the line under the title, now labelled "Updated" and with a valid `datetime`, which was empty. The rule under the page actions is gone
- Step titles in a `:::steps` block are rendered one heading level below the section the block sits in, and headings inside a step move with them. Steps under a `## Setup` heading are now `h3`, so they nest under that section in the table of contents and the page outline. A steps block before any section heading is unchanged. Authors still start each step with `##`; only CSS that targets step headings by tag, rather than by Vellum's classes, is affected
- A code block without a title no longer has a header, unless it is a shell block: its language and copy button sit in its corner. A titled block's header is drawn as an editor tab. Highlighted lines have a solid bar in the primary colour, and their line numbers are no longer faded. Code blocks carry `data-vellum-code-kind` (`file`, `terminal` or `snippet`)
- Callouts are no longer boxes: a bar in the type's colour runs down the left edge and the glyph sits on the first line, inside the text column. Warnings and dangers keep a light tint so they stand out from notes and tips
- Every tab group now looks like code tabs: one card with an underlined row of labels, the underline sliding to the selected label, and the panel inset in the card
- Cards have an arrow that moves on hover, and the hover highlight glides from card to card like the sidebar's. Cards in a row are as tall as the tallest
- Code in a table's first column, such as a config key, is no longer broken across lines; a table too wide for the page scrolls sideways. Table cells align to the top, column heads are smaller, and the row under the pointer is highlighted
- An image on a line of its own sits on a bordered mat and is held to a readable height, with its caption inside the frame
- The reader's words in a search result are marked with a bold underline in the primary colour instead of a yellow fill, and the browser's own clear button no longer shows in the search field. The results scroll with the sidebar's thin scrollbar
- At the foot of a page, Next is a wide card with the page's description on up to two lines, and Previous is a plain link beside it without one. Before, both were equal boxes with one cut-off line
- The version switcher sits above the search field in the sidebar, at the same size, instead of beside the site name. The latest version is shown by its slug or label with a "Latest" tag, not as "Latest" alone, and `VersionLabel::for()` returns the slug for it
- With `layout.search` set to `header`, the button that collapses the sidebar is in the header beside the site name, and reopens it too. The sidebar no longer keeps an empty row for it

### Removed

- The `vellum:build` warning about a colour preset removed in 0.5. The site still falls back to `neutral`

### Fixed

- Inline Markdown in a tab panel written straight under its `::tab[Label]` line, such as `code`, **bold** or a link, was rendered as plain text, and bold text disappeared

## [0.7.0] - 2026-09-26

### Added

- Search results are sections: a heading and the text under it, shown with the page title and heading, and linking to that heading. At most two sections of one page are listed before other pages' sections
- Each section is indexed with questions derived from its content at build time: from its heading, the Artisan and Composer commands in it, the config keys it documents and its warning callouts. A page can add its own with a `questions:` list in frontmatter
- Page aliases. A page's `aliases:` frontmatter adds terms it can be found by, and a query that names a section's heading, page title or alias ranks that section first
- A short built-in list of synonyms for common docs terms, such as "night mode" for "dark mode"
- English stemming in search, so "gate", "gated" and "gating" match each other and "configured" matches "configure"
- A search check for CI. List the questions readers ask in a `questions.yml` next to your Markdown, with the page and heading that answer each one, and `vellum:build` reports how many are found in the top five results. `checks.search_min` or `VELLUM_SEARCH_MIN` fails the build below a given share, and a question whose target no longer exists is reported as broken. `checks.search` turns the check off, and `vellum:build --check-search` runs it for one build regardless
- `{prefix}/_vellum/search?q=`, a JSON search endpoint for agents and scripts. It uses the same ranking as the browser and only returns pages the caller can open. `agents.search` turns it off
- `{prefix}/llms.txt` and `{prefix}/llms-full.txt`. `llms.txt` lists every public page in sidebar order, grouped under a heading per top-level folder, with a link to each page's raw Markdown and its description. `llms-full.txt` contains the Markdown of every public page, each with its title, URL and version. Both cover the latest version and leave gated pages out. `agents.llms_txt` turns them off
- The same two files at `/llms.txt` and `/llms-full.txt`, unless the app already routes those paths. They follow `route.domain`, and `agents.llms_txt_root` turns them off
- `vellum:export` writes `llms.txt` and `llms-full.txt` at the export root
- Content negotiation. A docs page requested with an `Accept` header that prefers `text/markdown` returns the page's raw Markdown. Browsers, whose default `Accept` does not name `text/markdown`, still get HTML, and page responses send `Vary: Accept`. `agents.content_negotiation` turns it off
- Every page links to its raw Markdown with `<link rel="alternate" type="text/markdown">` and a matching `Link` response header
- Raw Markdown responses send `Link: <page>; rel="canonical"` for the HTML page, `Last-Modified` when the page has a date, and `X-Vellum-Docs-Version` when versions are enabled
- A last-updated date for each page, from an `updated` frontmatter key or the file's last git commit. It appears under the page title, as `<lastmod>` in the sitemap, as `Last-Modified` on raw Markdown and in `llms-full.txt`. Pages without either have no date. Shallow clones are treated as having no git history
- The changelog has a raw Markdown URL at `{prefix}/_vellum/raw/changelog.md`, supports content negotiation, and is included in `llms.txt`, `llms-full.txt` and the sitemap. With `changelog.unreleased` off, the `[Unreleased]` section is left out of the raw Markdown too
- `checks.search`, `checks.search_min`, `agents.llms_txt`, `agents.llms_txt_root`, `agents.content_negotiation` and `agents.search` in `config/vellum.php`

### Changed

- Search no longer uses MiniSearch. The built-in driver loads a section index from `{prefix}/_vellum/answers.json` and ranks it in the browser, and the search script is 2.2 KB gzipped instead of 6.4 KB. `search.driver` is now `builtin`; `minisearch` still works as the old name
- `vellum:index` rebuilds the section index, and the Scout index when that driver is on
- The sidebar's page tree is rendered once per request and reused in the mobile drawer. On a 390-page site this took the median page time from 15.3 ms to 13.1 ms
- The last-updated date under a page title comes from frontmatter or git. It used to show the file's modification time, which a checkout or `composer install` resets
- `docs/seo.md` now suggests `Allow: /docs/_vellum/raw/` alongside `Disallow: /docs/_vellum/`, since raw Markdown pages declare their HTML page as canonical and `llms.txt` links to them

### Removed

- The MiniSearch index, its `{prefix}/_vellum/search.json` route for the built-in driver, and its builder. The route remains for the Scout driver

### Fixed

- Search on a static export hosted under a path, such as `export.base_url` set to `/handbook/`, loaded its index from the site root and found nothing, and its results linked to the root too. The exported pages now take both from the links the export rewrites

## [0.6.4] - 2026-09-24

### Fixed

- A folder's `title` in `_meta.md` was ignored, although the navigation docs said it could be set there. `_meta.md` frontmatter is now read like `meta.json`, and where both set the same key, `_meta.md` wins, as it already did for `access`
- Several pages described behaviour the code does not have. Card links to external URLs open in the same tab, inline code is only highlighted with a `{:lang}` suffix, a block of raw HTML is dropped along with its text, `vellum:index` recompiles pages as well as the index, and `vtt` files are served as assets. The docs now say so

### Changed

- The documentation, README, contributing guide, issue templates, starter pages and `config/vellum.php` comments have been rewritten to be easier to read. The upgrade guide covers the 0.6 patch releases, and the commands page documents `vellum:build --strict`

## [0.6.3] - 2026-09-24

Run `vellum:build` after upgrading, so the sidebar is rebuilt with the new access rules and compiled pages move into their own folder. If you export into the same directory each time, delete it once before the next export, so pages dropped since the last one are gone. If a page on your docs uses one of your own Blade components that shows something about the signed-in user, readers may have been shown someone else's: check what that component displays.

### Security

- A page using one of your own Blade components could show one reader's output to the next. The rendered page was cached by its content alone, so a component that read the signed-in user, such as one using `@auth`, `@can` or `auth()->user()`, was rendered for the first reader and then served to everyone after them, guests included. A page with a host component is now rendered on every request, and only pages built from Vellum's own components are cached
- A link listed in a gated folder's `meta.json` was shown to guests, and with it the folder's title, since a link defaulted to `guest` whatever folder it sat in. A link now takes its folder's access the way a page does, from `meta.json` or `_meta.md`, unless it sets `access` itself
- A `meta.json` link to a gated page, such as `{ "title": "Plan", "slug": "internal/plan" }` at the top level, was shown to every reader in the sidebar and prev/next, and its URL was listed in `sitemap.xml`. The page itself stayed a 404. A link to a gated page is now shown only to readers who can open that page, and the sitemap leaves it out
- A `---Section---` heading over pages a reader could not see stayed in their sidebar when another heading followed it, and it then sat above the next section's pages instead. With `index, ---Acquisition Plans---, admin, ---Reference---, webhooks` and `admin` gated, a guest saw Acquisition Plans above Webhooks. Of two headings in a row, the second is now the one kept, as the docs already said
- With the Scout driver, `vellum:build` only ever added and updated records, so a page that was deleted, renamed or moved into a gated folder kept its old record, content and `guest` access included. Each sync now empties the index and writes every version's pages, including under `--docs-version`
- A page named `nav.md` or `manifest.md` was compiled to the same file as the sidebar or the build manifest, so visiting `/docs/nav` overwrote the sidebar and every page then failed with a 500 until the next build. Compiled pages now live in a `pages` folder of their own inside `cache.path`
- A page whose file was deleted, or whose `slug` changed, kept being served from the compiled cache after `vellum:build`, and in local too. A page moved behind a gate by giving it a new slug stayed public at its old URL. `vellum:build` now removes compiled pages it did not produce, and local stops serving a page once its file is gone
- `vellum:export` into a directory that held an earlier export left every page it no longer wrote in place, so a page gated or deleted since stayed published even though the command logged it as dropped. An export now keeps a list of what it wrote in `.vellum-export.json` and removes what the last one wrote and this one did not. Nothing it did not write is touched. An export made before 0.6.3 has no list, so delete that directory once before exporting into it again
- A `javascript:` URL was written as it stood into a card's link, from `::card[...](...)` or `<x-vellum::card href="...">`, and into a sidebar link from `meta.json`. Markdown links have always refused them. These now follow the same rule, and an unsafe URL becomes `#`

### Fixed

- The Scout driver did not work. `vellum:build` and `vellum:index` said `laravel/scout` was not installed even when it was, and a search would have looked for its records in a database table that does not exist. Search now reads the engine's own hits, from Meilisearch, Typesense or Algolia. `docs/search.md` covers the `version` filter a versioned site needs the engine to allow
- Compiled pages, the sidebar and the search index were written straight over the old file, so a request reading a page while production compiled it on a cache miss could load half a file and fail. Each is now written to a temporary file and renamed into place, and a compiled PHP file is dropped from OPcache when it changes
- `vellum:export` turned each page's canonical link and `og:url` into relative paths whenever `export.base_url` was `/`, the default, or the same origin as `app.url`, since it stripped `app.url` from the whole page. Search engines were told a different URL than `sitemap.xml` listed. Both now stay absolute
- The redirect stubs `vellum:export` writes at a latest page's version-prefixed URL named the relative redirect target as their canonical. They now give the page's absolute URL, as the sitemap lists it, and leave the canonical out when there is no origin
- With `route.domain` set, canonical links, `og:url` and `sitemap.xml` named the host in `app.url`, where the docs routes do not answer. They now use `route.domain` as the host, keeping the scheme from `app.url`. A domain with a `{parameter}` in it names no single host, so it still falls back to `app.url`
- On the changelog page every release's Added, Changed and Fixed headings shared one id, so a link to a later release's Fixed landed on the first one on the page. Heading ids are now prefixed with their release, such as `0.6.3-fixed`
- `vellum:export` removed `app.url` wherever it appeared in a page, so `https://example.com.au/pricing` became `.au/pricing` when `app.url` was `https://example.com`. It is now only removed where it is the whole origin at the start of a link
- A file named entirely in a non-Latin script, such as `guides/入门.md`, got the folder's own URL, since its name had nothing left once reduced to a-z, and silently replaced `guides/index.md` at `/docs/guides`. Such a name now keeps its letters in the URL, `/docs/guides/入门`. Names that already had a Latin letter or digit keep the URLs they had
- A `meta.json` link without a `slug`, such as one to GitHub, was given the docs home's empty slug. On the home page the sidebar could mark the link as the current page, and prev/next matched the link instead of the page. Such a link now names no page, and prev/next skip it
- The changelog parser split a release at any line starting with `## `, including one inside a fenced code block, which cut the release short and added a bogus entry to the feed. Code blocks are now skipped
- A release marked `[YANKED]`, as Keep a Changelog writes it, lost its date and got an id with the marker in it. The date is read, the marker stays in the heading, and the id is the version alone. Ids are also cleaned of spaces and other characters a URL fragment cannot hold, so `1.0.0 beta` becomes `1.0.0-beta`
- The Atom feed had no `<author>`, which the format requires. It now names `vellum.name`
- A relative path in `vellum.path`, `changelog.path`, `cache.path` or `export.out`, for example `VELLUM_CHANGELOG=CHANGELOG.md`, was read from whatever directory PHP was running in: the project root for Artisan, but `public/` for a web request, so the changelog was a 404 on the site while the build found it. Relative paths are now read from the app root, as Laravel reads its own
- A page opening with an empty frontmatter block, `---` followed straight away by `---`, failed with "closing --- is missing". It is read as no frontmatter
- Before a build had run, the first request compiled every page to build the sidebar, and a single page with a typo in it, such as an unknown directive, turned every page of the site into an error. That page is now logged and left out of the sidebar, the rest are served, and the broken page shows its own error at its own URL
- `docs/value-tags.md` now says that `<x-vellum::env>` reads the process environment, which no longer includes `.env` once `config:cache` has run, and points at the `config` tag for values your config already holds
- A page with both a frontmatter `title` and a `# Heading` in its body rendered two `h1`s without a word. `vellum:build` now reports it next to heading level skips, as a notice that never fails a build
- Every docs page walked the whole docs directory three times per request, in production too, to decide whether the sidebar had changed, and then used the built sidebar whatever the answer. Production now serves the sidebar `vellum:build` wrote without looking, and a request loads it once.
- In local, the sidebar was only rebuilt when a file changed size, so reordering `meta.json` from `"order": 2` to `"order": 3` left the old order in place. A changed modification time now counts too
- HTML, JSON and assets are gzipped at level 6 rather than 9, which is about three times faster for output 1.5% larger
- The changelog was read and rendered from Markdown on every request to its page and its feed, which took longer than serving a docs page. The result is now cached until the file, the settings that shape it, or `vellum:clear` change
- Outside `local`, a request for a page the build had not compiled read the frontmatter of every Markdown file to look for it, so every 404, from a mistyped link or a bot, cost a scan of the whole docs directory. Once `vellum:build` has run, production serves what it compiled and answers anything else with a 404 straight away. A page added since the last build is served once it is built, as the sidebar already worked

## [0.6.2] - 2026-09-20

If you publish a static export, check what is in it before deploying the next one. Anything that sat in your docs directory and was not Markdown or a `meta.json` was copied into the export, including dotfiles. Look for `.env`, editor drafts, notes and anything under a dot-directory, delete them from the published site, and rotate any secret that was exposed.

### Security

- `vellum:export` copied every file in the docs directory that was not Markdown or a `meta.json`, dotfiles and dot-directories included, into `_vellum/files/`. The asset route has always refused those, so a file unreachable on the served site could still be published by an export of the same docs. The export now copies only what that route serves: the listed image, font, media and document extensions, never a dotfile and never anything under a dot-directory. Both share one rule

### Fixed

- An external link in `meta.json` no longer lands in the sitemap as a docs URL (`https://docs.example.com/https://github.com/...`). The sitemap lists pages of these docs only

## [0.6.1] - 2026-09-19

### Changed

- `docs/why.md` is now What is Vellum: what the package is, how it works, and what it does not do, without the case against other tools. The URL stays `/docs/why`
- New `docs/comparisons.md` sets Vellum against LaRecipe, the other package that serves Markdown docs from inside a Laravel app, as a table of facts with where each fits better
- The docs no longer describe 0.5 as the current release. Config keys, frontmatter and syntax are still frozen, as they have been since 0.5

## [0.6.0] - 2026-09-17

### Added

- `{prefix}/sitemap.xml`, built from the same navigation that renders the sidebar. Gated pages are excluded, including for a signed-in reader, since a sitemap is a single public file, and every version is listed when versions are enabled. It returns a 404 rather than publishing relative URLs when `app.url` is not an origin, the same rule the canonical link already followed
- `vellum:export` writes `sitemap.xml` at the export root, using `export.base_url` when it names an origin and falling back to `app.url`. A static host cannot generate one for itself. Skipped with a warning when neither is an origin
- Build-time checking of internal links, images and heading levels. `vellum:build` warns about a link to a page that is not there, a `#fragment` with no matching heading, an image the renderer could not resolve, and a heading that skips a level. Missing images are reported by the renderer itself rather than inferred from the URL it emitted, so the check cannot go quiet if that fallback ever changes. Heading skips are notices and do not fail a strict build. Both failures are silent at runtime: a stale link still renders as a link, and a missing image compiles into a page whose only symptom is a broken image nobody reloaded. `--strict` or `checks.strict` turns the warnings into a failed build, for CI
- `docs/seo.md`, covering the metadata every page emits, the sitemap, and the `robots.txt` worth adding, including disallowing `_vellum/`, since the page actions link to a raw Markdown copy of every page and it would otherwise be crawled and indexed as a near-duplicate

### Changed

- The table of contents now marks every heading whose section is on screen, not only the last one scrolled past. The rail covers the whole run rather than a single entry. It used to watch heading elements, so a long section went dark the moment its title scrolled off the top; it now measures each section from its heading to the next one. The dot on the rail marks reading position, sliding between two headings' anchors by how far you have read between them, so the rail says what is on screen and the dot says where in it you are
- `docs/why.md` grew from a 235-word note into a comparison page. It leads with the two ways Vellum ships the same Markdown, served from the app or exported static, including the limits of the static snapshot, then names the alternatives directly (Fumadocs, Mintlify, VitePress, Docusaurus, a wiki) and says what each is better at. The gating and export claims in it are the ones `GatingTest` and `CommandsTest` already cover

## [0.5.2] - 2026-09-17

### Fixed

- A `versions.latest` left in config while `versions.enabled` is `false` no longer reaches URL building. The changelog page declared a canonical of `/docs/v2/changelog`, a URL the router does not match, so search engines were pointed at a 404 and the page would not have been indexed. The 404 page written by `vellum:export` built its version switcher the same way. `latestVersion()` now returns `null` when versioning is off, which is what every other caller already checked for itself

## [0.5.1] - 2026-09-16

### Fixed

- Prose links now take `--primary`, which is what the documentation has always said. `theming.md` and the README both described `theme.accent` as recolouring links, and `PresetContrastTest` held `--primary` against `--background` at 4.5:1 under the label "link", but links were `--foreground` and `--primary` only reached a highlighted-line background, a border and the code tab underline. Setting an accent had no effect on link colour. Measured on rendered pixels after the change: neutral 18.04:1 light and 18.32:1 dark, ocean 12.31 and 13.90, laravel 4.54 and 5.54. Neutral's `--primary` is all but black, so that preset looks unchanged

### Changed

- Code blocks and table wrappers use the same thin, rounded scrollbar as the sidebar instead of the browser default, 6px rather than the sidebar's 8px since they sit inside content rather than beside it

## [0.5.0] - 2026-09-16

0.5 stability freeze. Config keys and frontmatter names do not change until 1.0.

### Security

- Path traversal in the docs slug. A request like `/docs/..%2FREADME` resolved outside the content root, so any `.md` on disk could be read through the page route and the raw Markdown route, and compiling it wrote a PHP file outside the cache directory. Slugs with empty, `.` or `..` segments are now refused, a resolved path is checked against the content root with `realpath`, and `CompiledStore` refuses to build a path for an unsafe slug
- Blade execution through component attributes. Attribute values were interpolated into the template string, and `e()` escapes quotes but not braces, so `<x-vellum::callout title="{{ php_uname() }}">` ran. Values are now bound and passed as data, so docs attributes stay literal as documented
- Gated content readable through the asset route. `/{prefix}/_vellum/files/` served anything under `vellum.path`, including gated pages, `meta.json`, `_meta.md` and dotfiles. It now serves an allowlist of asset extensions only. Assets themselves are still not gated, which is documented on the gating page

### Added

- Package docs for why Vellum, versions, gating, search drivers, changelog, export, theming, and the 0.2 to 0.5 upgrade path
- `laravel` colour preset, matching laravel.com/docs warm sand neutrals and the Laravel red
- `theme.accent`: a brand colour applied to links, buttons and the focus ring on any preset, as one value or `['light' => ..., 'dark' => ...]`. Hex, `hsl()` and `oklch()` are accepted, the button label colour is derived from it, and an unparseable value is ignored
- `Vellum\Support\Color`: colour parsing, relative luminance and WCAG contrast
- Contrast test over the real stylesheets: every shipped preset clears WCAG AA (4.5:1) for body text, secondary text, links and button labels, in both modes
- `CONTRIBUTING.md`, `SECURITY.md`, GitHub issue and pull request templates
- `versions.labels`: switcher display names (`1.x (LTS)`, `Next`) while folders and URLs stay the list slug
- Docs for the features that shipped without any: Markdown, code blocks, images, navigation, an artisan command reference, page actions, troubleshooting, and credits
- Canonical link, Open Graph and Twitter card tags on every page. Canonical is omitted rather than guessed when `app.url` is not an origin, and a static export prefers `export.base_url` when that names one
- `vellum:export` writes a `404.html` at the export root, with root-relative asset paths so it works for a miss at any depth
- A Vellum error page for content that cannot render, instead of the framework's generic 500. The reason and file appear only when `APP_DEBUG` is on
- `UnknownDirectiveException`: a `:::` typo now names the directive and the file instead of raising `NoMatchingRendererException` for an internal class
- `DuplicateSlugException`: `vellum:build` refuses to build when two files resolve to one URL, and names both
- `.gitattributes` with `export-ignore`, taking the released archive from 1860 KB to 830 KB

### Changed

- Colour presets retuned to clear WCAG AA in light mode. Neutral's secondary text was 4.21:1, Laravel's link and button colours 3.96:1
- Laravel preset uses `#e32c03` for text and fills and keeps `#f53003` for the active wash and the focus ring, the way laravel.com does
- Code blocks take the shared `--muted` surface instead of a hard-coded white and `#191919`, so they match the page in every preset
- The sidebar takes the shared `--card` surface, instead of a tint on some presets and the page background on others
- Surfaces follow one rule in every preset and both modes: `--background` is the canvas at the light or dark extreme, `--card` is one step toward mid-grey for the sidebar, callouts and popovers, and `--muted` is a second step for code blocks, table headers, tab strips and step markers. Surfaces only ever move away from the canvas, darker in light and lighter in dark, so prose sits on the cleanest area and nesting reads correctly
- Light mode canvases are near-white and dark canvases near-black, replacing a mid-grey page with lighter elements sitting on top of it
- Light-mode surfaces are lighter: the code block sat at 1.19:1 from the canvas, roughly twice the step GitHub, VitePress and Fumadocs use, and is now 1.08:1
- Code tabs are tighter: the active underline sits closer to the label, the header is 39px instead of 49px, and the code is inset by 0.25rem instead of 0.5rem
- Code tabs take the same two surfaces as everything else, `--card` for the frame and `--muted` for the code, instead of a hard-coded grey frame around a pure white block
- Syntax highlighting is more colourful. Strings are green, numbers teal, types blue, variables orange, keywords red, and every token clears 4.5:1 on every preset's code surface in both modes
- Neutral's `--muted` was 1.003:1 against the page in light mode, so table headers, tab strips and step markers had no visible surface
- Markdown tabs and UI tabs share `vellumTabs()` for arrow keys, Home/End, and `aria-controls`
- Search dialog labelled for assistive tech (`combobox` + `listbox`); version switcher menu has Home/End and `aria-controls`
- The active code tab label uses `--foreground` and the accent carries the underline. With the accent the docs use as an example it measured 1.42:1 against a documented 4.5:1, and now measures 18.80:1 in light and 15.04:1 in dark
- The asset route sends `max-age=86400, must-revalidate` instead of a year of `immutable`, since those URLs carry no content hash and a replaced image was stale for a year
- `guest` and `auth` are matched without regard to case, so `access: Auth` works. Gate names are still passed to `Gate::allows()` exactly as written

### Fixed

- `access: Auth` hid a page from everyone. A capitalised value fell through to `Gate::allows('Auth')`, false for guests and signed-in readers alike, with no error anywhere
- A UTF-8 BOM before the opening `---` made the whole frontmatter block parse as body text, and the title fall back to the filename
- Images inside a version folder resolved against the global docs root and 404d. Each version now renders through its own pipeline and the emitted URL carries the version segment
- A page whose title fell back to its first heading shipped two `h1`s, since the layout renders one of its own
- `vellum:install --force` never republished the config; the flag was ignored
- An impossible changelog date such as `2026-13-45` passed into the Atom feed, which readers reject. Dates are validated and fall back to the file mtime
- An unquoted numeric frontmatter `title`, which YAML parses as an int, was discarded in favour of the filename
- The checked-checkbox tick had its colour baked into a data URL, which had drifted from `--muted-foreground` in light mode and never matched the `ocean` or `laravel` presets at all
- The last sidebar item sat against the footer bar with no clearance
- The index page title rendered as "Vellum · Vellum" when the page title equalled the site name
- A long URL or identifier in inline backticks had no break opportunity and pushed the page wider than a phone viewport. It wraps now
- `vellum:build` warns when a page is shadowed by the changelog route

### Removed

- Colour presets `black`, `vitepress`, `dusk`, `catppuccin`, `purple`, `solar`, `emerald`, `ruby` and `aspen`. Most changed one accent colour, which `theme.accent` now does on any preset; several could not reach WCAG AA in light mode without losing the character that named them. A removed name falls back to `neutral` and `vellum:build` warns once
- Cloudflare Workers demo (`bin/build-demo`, `wrangler.toml`, committed `demo-dist`). The public site is now a Laravel app that serves `docs/` through the package

## [0.4.0] - 2026-09-13

Versioned docs URLs and search drivers.

### Added

- `php artisan vellum:index` rebuilds the MiniSearch compile cache and, when `search.driver` is `scout`, syncs Laravel Scout
- Page `access` frontmatter (`guest`, `auth`, or a gate name). Folder `meta.json` or `_meta.md` inherits downward; a page overrides. Export logs each dropped gated page

### Changed

- When `vellum.versions.enabled` is true, the latest version is served at `/docs/...`. Older versions stay at `/docs/{version}/...`. `/docs/{latest}/...` redirects to the unprefixed URL with HTTP 301. The version switcher labels the latest folder "Latest".
- Search is a driver (`vellum.search.driver`): MiniSearch by default, Laravel Scout optional. The live MiniSearch index is a package route that filters pages the current user cannot access, cached per visibility set, with an ETag so `must-revalidate` can 304. Static export always writes MiniSearch JSON and drops gated pages.

## [0.3.0] - 2026-09-13

Markdown plus components. Pre-1.0: the API may change.

### Added

- `<x-…>` component islands in Markdown. Slots are Markdown and may nest. Attributes are quoted strings only: no `{{ }}`, Blade directives, or `@php` in docs. Tags inside fenced or inline code stay as text
- Host Blade components via `vellum.components.namespaces` (default `['vellum']` allows `<x-vellum::…>` only; add `''` or `'app'` for `<x-alert>`). Unknown or disallowed tags fail locally and at build
- Built-in `:::callout`, `:::tabs`, `:::steps`, and `:::cards` render the same views as `<x-vellum::callout>`, tabs, steps, and cards. Prefer `:::` for those
- `<x-vellum::env />`, `config`, and `route` value tags, gated by `vellum.components.allowlist` (empty lists refuse every key). They resolve when the page is rendered, including inside `:::tabs`, not when Markdown is compiled
- Request-time fragment cache for those islands, cleared by `vellum:clear` and `optimize:clear`
- Changelog page at `/docs/changelog` and Atom feed at `/docs/changelog.atom` (`vellum.changelog.path`, default `CHANGELOG.md`). Set `path` to `null` to disable. `[Unreleased]` stays in the source file; the page hides it unless `vellum.changelog.unreleased` is true; the feed never includes it
- Package docs in `docs/` (the Cloudflare demo exports that tree). `vellum:install` stubs stay a short getting-started plus one page per built-in

## [0.2.0] - 2026-09-13

Docs chrome and Markdown polish. Pre-1.0: the API may change.

### Added

- Footnotes via CommonMark, with styled list and backlinks
- `vellum.layout.search`: `sidebar` (default) or `header`
- Collapsible desktop sidebar, persisted in `localStorage`, with a floating expand/search pill, width animation, and a rounded left-edge hover peek
- Mobile "On this page" popover: sticky bar, reading-progress circle, overlay rail dropdown (`max-h-[50vh]`)
- Page actions: copy Markdown, Open menu (ChatGPT, Claude, raw Markdown, Edit on GitHub)
- Raw Markdown route `/docs/_vellum/raw/{slug}.md`, included in `vellum:export`
- `success` and `idea` callout aliases (map to tip and note)
- `vellum.theme.preset`: Fumadocs palettes (`neutral`, `black`, `vitepress`, `dusk`, `catppuccin`, `ocean`, `purple`, `solar`, `emerald`, `ruby`, `aspen`)

### Fixed

- Collapsed sidebar peek only opens from the left-edge hotzone after a short cooldown, and hides when the pointer leaves
- Theme menu in the sidebar footer opens upward so it stays on screen
- `bin/build-demo` registers the package through `testbench.yaml` so `vellum:export` is available

### Changed

- Plain inline code uses the same chip as tagged inline code
- Line numbers are CSS counters (`user-select: none`) and are omitted from copied text
- Sidebar item text aligns with the brand; nested items indent from that edge
- Default chrome has no top header; search and theme live in the sidebar
- Copyright footer removed; footer is an empty optional slot
- Previous/next cards use arrows, a bold title, and the page description; they sit after footnotes, half width when both exist, full width for a single direction, stacked on small screens
- Content stays left when there is no table of contents; the TOC column is still reserved
- Last-updated date sits above the H1 next to breadcrumbs
- Tighter content-column padding
- Hotkey chip defaults to `Ctrl` and switches to `⌘` on Apple platforms after hydration
- TOC uses a continuous SVG rail with heading-level jogs, a 420ms active clip, and a path-following thumb
- Heading permalinks are a hover/focus copy-link control (no visible `#`)
- Code copy control is icon-only; title bar uses Phosphor language file marks
- Chrome icons use Phosphor (search, theme, sidebar, carets, GitHub, heading permalinks)
- TOC active and hovered section titles are semibold
- Fenced code uses GitHub Light/Dark token colours on a Fumadocs-like card surface
- Code tabs sit in a lighter grey chrome; the inner fence uses the same surface as standalone code blocks
- Author `---` rules are lighter; theme no longer inserts rules between headings
- `:::cards` render two per row (one on mobile)
- Tempest token classes are styled in the built CSS
- Callouts: rounded card, inset rounded-pill accent rail, Phosphor fill icons aligned to the title/first line, bold title, muted body
- Mobile navigation is a Fumadocs-style right sheet: 85% width, sun/moon header, a heavily blurred page overlay, and the same 280ms sidebar slide
- Mobile "On this page" popover shares one frosted surface with the title bar so the blur matches
- Neutral palette matches Fumadocs (soft gray light, charcoal dark instead of OLED black)
- Copy on embedded/tab code sits on the first line
- Docs images align to the content edge
- Task-list checkboxes use muted-foreground grey so the check stays visible

### Removed

- Default copyright / "Built with Vellum" footer content

## [0.1.0] - 2026-09-11

Initial public release. Pre-1.0: the API may change.

### Added

- Laravel package that serves documentation from Markdown (`resources/docs` by default); supports Laravel 11, 12, and 13
- `vellum:install` to publish config, starter stubs, and public dist assets
- `vellum:build` / `vellum:clear` for an OPcache-friendly compile cache
- Markdown extensions: callouts, tabs, steps, cards, fenced code blocks, inline code highlighting, images, external links, heading anchors
- Docs UI: sidebar navigation, table of contents, breadcrumbs, search (MiniSearch), light/dark/system theme
- Optional version folders with latest redirect and version switcher
- `vellum:export` for static HTML output suitable for GitHub Pages or any static host
- Config surface in `config/vellum.php` (path, routes, versions, theme, search, cache, export)
- GitHub Actions CI (Pest on Laravel 11/12/13, Pint, PHPStan, frontend build / size gate)
- Demo site workflow that exports package stubs for Cloudflare Workers (`bin/build-demo`, `wrangler.toml`)

### Publishing note

Tag `v0.1.0` and push the tag, then submit `https://github.com/VerburgtJimmy/vellum` on Packagist if the package is not listed yet. Do not hardcode `"version"` in `composer.json`.

[Unreleased]: https://github.com/VerburgtJimmy/vellum/compare/v0.4.0...HEAD
[0.4.0]: https://github.com/VerburgtJimmy/vellum/releases/tag/v0.4.0
[0.3.0]: https://github.com/VerburgtJimmy/vellum/releases/tag/v0.3.0
[0.2.0]: https://github.com/VerburgtJimmy/vellum/releases/tag/v0.2.0
[0.1.0]: https://github.com/VerburgtJimmy/vellum/releases/tag/v0.1.0

================================================================================
Title: Overview
URL: https://vellum.jimmyverburgt.com/docs/api
================================================================================

# Example API

An example, to show what Vellum makes of an OpenAPI spec. Harbor manages
ships and berths for a harbor that does not exist.

The API behind it is real enough to answer: open an operation and press
**Try it**. It keeps nothing, so a ship you register is gone by the next
request, and removing one removes nothing.

Its webhook and callback are described the way an API would describe
them, but never sent: nothing here can be told where to send them.

These pages are generated from one YAML file. See
[API reference](/docs/api-reference) for how to turn them on for your own.

Version `2.4.0`

## Servers

- `/harbor/v2`: This site

## Fleet

Everything that floats, and where it ties up.

### Ships

Vessels registered with the harbor.

- [List ships](/docs/api/ships/list-ships) `GET /ships`
- [Register a ship](/docs/api/ships/register-ship) `POST /ships`
- [Get a ship](/docs/api/ships/get-ship) `GET /ships/{shipId}`
- [Remove a ship](/docs/api/ships/remove-ship) `DELETE /ships/{shipId}`

### Berths

Where ships dock.

- [Assign a berth](/docs/api/berths/assign-berth) `PUT /berths/{berthId}/assign`

## Other

- [Health check](/docs/api/other/get-health) `GET /health`

## Webhooks

- [Ship arrived](/docs/api/webhooks/ship-arrived) `POST shipArrived`

================================================================================
Title: List ships
URL: https://vellum.jimmyverburgt.com/docs/api/ships/list-ships
================================================================================

# List ships

`GET /ships`

Returns ships in the order they registered. Use `cursor` to page.

## Authorization

- `bearerAuth`: Any token will do here. Without one the answer is a 401. `Authorization: Bearer <token>`

## Query parameters

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `type` | string | No | Only ships of this type. |
| `limit` | integer | No | How many to return. |
| `cursor` | string | No | Where the last page ended. |

## Responses

### 200

A page of ships.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `data` | array<Ship> | No |  |
| `data[].name` | string | Yes |  |
| `data[].type` | string | Yes | What the ship carries. One of: `cargo`, `tanker`, `ferry`, `tug`. |
| `data[].id` | integer | No |  |
| `data[].tonnage` | number | No | Gross tonnage. |
| `data[].captain` | object | No | Whoever is in command right now. |
| `data[].captain.name` | string | Yes |  |
| `data[].captain.licence` | string | No |  |
| `data[].crew` | array<object> | No |  |
| `data[].crew[].name` | string | No |  |
| `data[].crew[].role` | string | No | One of: `deck`, `engine`, `galley`. |
| `data[].escort` | Ship | No |  |
| `data[].registeredAt` | string | No |  |
| `data[].callbackUrl` | string | No | Where to send the inspection result. See the callback below. |
| `next` | string \| null | No | Cursor for the next page. |

## Request samples

cURL:

```bash
curl -X GET 'https://vellum.jimmyverburgt.com/harbor/v2/ships' \
  -H 'Authorization: Bearer <token>'
```

PHP:

```php
$response = Http::withToken('<token>')->get('https://vellum.jimmyverburgt.com/harbor/v2/ships');
```

JavaScript:

```js
const response = await fetch('https://vellum.jimmyverburgt.com/harbor/v2/ships', {
  method: 'GET',
  headers: {
    'Authorization': 'Bearer <token>',
  }
})
```

Python:

```python
import requests

response = requests.get(
    'https://vellum.jimmyverburgt.com/harbor/v2/ships',
    headers={
        'Authorization': 'Bearer <token>',
    },
)
```

## Example responses

200:

```json
{
    "data": [
        {
            "id": 1,
            "name": "Aurora",
            "type": "cargo",
            "tonnage": 48200,
            "captain": {
                "name": "Ada Vos",
                "licence": "NL204518"
            },
            "crew": [
                {
                    "name": "Tomas Lind",
                    "role": "deck"
                }
            ],
            "registeredAt": "2026-01-31T09:00:00Z",
            "callbackUrl": "https://example.com"
        }
    ],
    "next": "string"
}
```

================================================================================
Title: Register a ship
URL: https://vellum.jimmyverburgt.com/docs/api/ships/register-ship
================================================================================

# Register a ship

`POST /ships`

Adds a ship to the harbor's register.

:::warning
A ship's `type` cannot be changed once it is registered.
:::

## Authorization

- `bearerAuth`: Any token will do here. Without one the answer is a 401. `Authorization: Bearer <token>`

## Header parameters

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `Idempotency-Key` | string | No | Repeat a request safely. |

## Request body

`application/json`

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `name` | string | Yes |  |
| `type` | string | Yes | What the ship carries. One of: `cargo`, `tanker`, `ferry`, `tug`. |
| `id` | integer | No |  |
| `tonnage` | number | No | Gross tonnage. |
| `captain` | object | No | Whoever is in command right now. |
| `captain.name` | string | Yes |  |
| `captain.licence` | string | No |  |
| `crew` | array<object> | No |  |
| `crew[].name` | string | No |  |
| `crew[].role` | string | No | One of: `deck`, `engine`, `galley`. |
| `escort` | Ship | No |  |
| `registeredAt` | string | No |  |
| `callbackUrl` | string | No | Where to send the inspection result. See the callback below. |

## Responses

### 201

The ship as registered.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `name` | string | Yes |  |
| `type` | string | Yes | What the ship carries. One of: `cargo`, `tanker`, `ferry`, `tug`. |
| `id` | integer | No |  |
| `tonnage` | number | No | Gross tonnage. |
| `captain` | object | No | Whoever is in command right now. |
| `captain.name` | string | Yes |  |
| `captain.licence` | string | No |  |
| `crew` | array<object> | No |  |
| `crew[].name` | string | No |  |
| `crew[].role` | string | No | One of: `deck`, `engine`, `galley`. |
| `escort` | Ship | No |  |
| `registeredAt` | string | No |  |
| `callbackUrl` | string | No | Where to send the inspection result. See the callback below. |

### 422

The ship did not pass validation.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `message` | string | Yes |  |
| `errors` | object | No |  |

## Callbacks

### Inspection done

`POST {$request.body#/callbackUrl}`

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `shipId` | integer | Yes |  |
| `passed` | boolean | Yes | Whether the ship may leave the harbor. |
| `notes` | string | No |  |

## Request samples

cURL:

```bash
curl -X POST 'https://vellum.jimmyverburgt.com/harbor/v2/ships' \
  -H 'Authorization: Bearer <token>' \
  -H 'Idempotency-Key: 3fa85f64-5717-4562-b3fc-2c963f66afa6' \
  -H 'Content-Type: application/json' \
  -d '{
    "id": 1,
    "name": "Aurora",
    "type": "cargo",
    "tonnage": 48200,
    "captain": {
        "name": "Ada Vos",
        "licence": "NL204518"
    },
    "crew": [
        {
            "name": "Tomas Lind",
            "role": "deck"
        }
    ],
    "registeredAt": "2026-01-31T09:00:00Z",
    "callbackUrl": "https://example.com"
}'
```

PHP:

```php
$response = Http::withToken('<token>')
    ->withHeaders([
        'Idempotency-Key' => '3fa85f64-5717-4562-b3fc-2c963f66afa6',
    ])
    ->post('https://vellum.jimmyverburgt.com/harbor/v2/ships', [
        'id' => 1,
        'name' => 'Aurora',
        'type' => 'cargo',
        'tonnage' => 48200,
        'captain' => [
            'name' => 'Ada Vos',
            'licence' => 'NL204518',
        ],
        'crew' => [
            [
                'name' => 'Tomas Lind',
                'role' => 'deck',
            ],
        ],
        'registeredAt' => '2026-01-31T09:00:00Z',
        'callbackUrl' => 'https://example.com',
    ]);
```

JavaScript:

```js
const response = await fetch('https://vellum.jimmyverburgt.com/harbor/v2/ships', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer <token>',
    'Idempotency-Key': '3fa85f64-5717-4562-b3fc-2c963f66afa6',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
      "id": 1,
      "name": "Aurora",
      "type": "cargo",
      "tonnage": 48200,
      "captain": {
          "name": "Ada Vos",
          "licence": "NL204518"
      },
      "crew": [
          {
              "name": "Tomas Lind",
              "role": "deck"
          }
      ],
      "registeredAt": "2026-01-31T09:00:00Z",
      "callbackUrl": "https://example.com"
  })
})
```

Python:

```python
import requests

response = requests.post(
    'https://vellum.jimmyverburgt.com/harbor/v2/ships',
    headers={
        'Authorization': 'Bearer <token>',
        'Idempotency-Key': '3fa85f64-5717-4562-b3fc-2c963f66afa6',
    },
    json={
        'id': 1,
        'name': 'Aurora',
        'type': 'cargo',
        'tonnage': 48200,
        'captain': {
            'name': 'Ada Vos',
            'licence': 'NL204518',
        },
        'crew': [
            {
                'name': 'Tomas Lind',
                'role': 'deck',
            },
        ],
        'registeredAt': '2026-01-31T09:00:00Z',
        'callbackUrl': 'https://example.com',
    },
)
```

## Example responses

201:

```json
{
    "id": 1,
    "name": "Aurora",
    "type": "cargo",
    "tonnage": 48200,
    "captain": {
        "name": "Ada Vos",
        "licence": "NL204518"
    },
    "crew": [
        {
            "name": "Tomas Lind",
            "role": "deck"
        }
    ],
    "registeredAt": "2026-01-31T09:00:00Z",
    "callbackUrl": "https://example.com"
}
```

422:

```json
{
    "message": "The name field is required.",
    "errors": []
}
```

================================================================================
Title: Get a ship
URL: https://vellum.jimmyverburgt.com/docs/api/ships/get-ship
================================================================================

# Get a ship

`GET /ships/{shipId}`

## Authorization

- `bearerAuth`: Any token will do here. Without one the answer is a 401. `Authorization: Bearer <token>`

## Path parameters

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `shipId` | integer | Yes | The ship's id. Ships 1, 2 and 3 exist. |

## Responses

### 200

The ship.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `name` | string | Yes |  |
| `type` | string | Yes | What the ship carries. One of: `cargo`, `tanker`, `ferry`, `tug`. |
| `id` | integer | No |  |
| `tonnage` | number | No | Gross tonnage. |
| `captain` | object | No | Whoever is in command right now. |
| `captain.name` | string | Yes |  |
| `captain.licence` | string | No |  |
| `crew` | array<object> | No |  |
| `crew[].name` | string | No |  |
| `crew[].role` | string | No | One of: `deck`, `engine`, `galley`. |
| `escort` | Ship | No |  |
| `registeredAt` | string | No |  |
| `callbackUrl` | string | No | Where to send the inspection result. See the callback below. |

### 404

No such ship.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `message` | string | Yes |  |
| `errors` | object | No |  |

## Request samples

cURL:

```bash
curl -X GET 'https://vellum.jimmyverburgt.com/harbor/v2/ships/{shipId}' \
  -H 'Authorization: Bearer <token>'
```

PHP:

```php
$response = Http::withToken('<token>')->get('https://vellum.jimmyverburgt.com/harbor/v2/ships/{shipId}');
```

JavaScript:

```js
const response = await fetch('https://vellum.jimmyverburgt.com/harbor/v2/ships/{shipId}', {
  method: 'GET',
  headers: {
    'Authorization': 'Bearer <token>',
  }
})
```

Python:

```python
import requests

response = requests.get(
    'https://vellum.jimmyverburgt.com/harbor/v2/ships/{shipId}',
    headers={
        'Authorization': 'Bearer <token>',
    },
)
```

## Example responses

200:

```json
{
    "id": 1,
    "name": "Aurora",
    "type": "cargo",
    "tonnage": 48200,
    "captain": {
        "name": "Ada Vos",
        "licence": "NL204518"
    },
    "crew": [
        {
            "name": "Tomas Lind",
            "role": "deck"
        }
    ],
    "registeredAt": "2026-01-31T09:00:00Z",
    "callbackUrl": "https://example.com"
}
```

404:

```json
{
    "message": "The name field is required.",
    "errors": []
}
```

================================================================================
Title: Remove a ship
URL: https://vellum.jimmyverburgt.com/docs/api/ships/remove-ship
================================================================================

# Remove a ship

**Deprecated.**

`DELETE /ships/{shipId}`

## Authorization

- `bearerAuth`: Any token will do here. Without one the answer is a 401. `Authorization: Bearer <token>`

## Path parameters

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `shipId` | integer | Yes | The ship's id. Ships 1, 2 and 3 exist. |

## Responses

### 204

Removed.

## Request samples

cURL:

```bash
curl -X DELETE 'https://vellum.jimmyverburgt.com/harbor/v2/ships/{shipId}' \
  -H 'Authorization: Bearer <token>'
```

PHP:

```php
$response = Http::withToken('<token>')->delete('https://vellum.jimmyverburgt.com/harbor/v2/ships/{shipId}');
```

JavaScript:

```js
const response = await fetch('https://vellum.jimmyverburgt.com/harbor/v2/ships/{shipId}', {
  method: 'DELETE',
  headers: {
    'Authorization': 'Bearer <token>',
  }
})
```

Python:

```python
import requests

response = requests.delete(
    'https://vellum.jimmyverburgt.com/harbor/v2/ships/{shipId}',
    headers={
        'Authorization': 'Bearer <token>',
    },
)
```

================================================================================
Title: Assign a berth
URL: https://vellum.jimmyverburgt.com/docs/api/berths/assign-berth
================================================================================

# Assign a berth

`PUT /berths/{berthId}/assign`

## Authorization

- `bearerAuth`: Any token will do here. Without one the answer is a 401. `Authorization: Bearer <token>`

## Path parameters

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `berthId` | string | Yes | The berth, as painted on the quay. |

## Request body

`application/json`

`By ship or Reserved`

## Responses

### 200

The berth and what holds it.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `berth` | string | No |  |
| `shipId` | integer \| null | No |  |
| `reason` | string \| null | No |  |
| `until` | string \| null | No |  |

### 422

Neither a ship nor a reason was given.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `message` | string | Yes |  |
| `errors` | object | No |  |

## Request samples

cURL:

```bash
curl -X PUT 'https://vellum.jimmyverburgt.com/harbor/v2/berths/{berthId}/assign' \
  -H 'Authorization: Bearer <token>' \
  -H 'Content-Type: application/json' \
  -d '{
    "shipId": 0,
    "until": "2026-01-31T09:00:00Z"
}'
```

PHP:

```php
$response = Http::withToken('<token>')->put('https://vellum.jimmyverburgt.com/harbor/v2/berths/{berthId}/assign', [
        'shipId' => 0,
        'until' => '2026-01-31T09:00:00Z',
    ]);
```

JavaScript:

```js
const response = await fetch('https://vellum.jimmyverburgt.com/harbor/v2/berths/{berthId}/assign', {
  method: 'PUT',
  headers: {
    'Authorization': 'Bearer <token>',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
      "shipId": 0,
      "until": "2026-01-31T09:00:00Z"
  })
})
```

Python:

```python
import requests

response = requests.put(
    'https://vellum.jimmyverburgt.com/harbor/v2/berths/{berthId}/assign',
    headers={
        'Authorization': 'Bearer <token>',
    },
    json={
        'shipId': 0,
        'until': '2026-01-31T09:00:00Z',
    },
)
```

## Example responses

200:

```json
{
    "berth": "B7",
    "shipId": 1,
    "reason": "string",
    "until": "2026-01-31T09:00:00Z"
}
```

422:

```json
{
    "message": "The name field is required.",
    "errors": []
}
```

================================================================================
Title: Health check
URL: https://vellum.jimmyverburgt.com/docs/api/other/get-health
================================================================================

# Health check

`GET /health`

## Responses

### 200

Up.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `status` | string | No |  |
| `time` | string | No |  |

## Request samples

cURL:

```bash
curl -X GET 'https://vellum.jimmyverburgt.com/harbor/v2/health'
```

PHP:

```php
$response = Http::->get('https://vellum.jimmyverburgt.com/harbor/v2/health');
```

JavaScript:

```js
const response = await fetch('https://vellum.jimmyverburgt.com/harbor/v2/health', {
  method: 'GET'
})
```

Python:

```python
import requests

response = requests.get(
    'https://vellum.jimmyverburgt.com/harbor/v2/health',
)
```

## Example responses

200:

```json
{
    "status": "ok",
    "time": "2026-01-31T09:00:00Z"
}
```

================================================================================
Title: Ship arrived
URL: https://vellum.jimmyverburgt.com/docs/api/webhooks/ship-arrived
================================================================================

# Ship arrived

`POST` webhook `shipArrived`. The API sends this request to an address you give it.

Sent to the webhook address set on your account when a ship ties up at a berth. This example never sends it.

## Header parameters

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `Harbor-Signature` | string | Yes | HMAC-SHA256 of the body with your webhook secret, in hex. Compare it before you trust the body. |

## Payload

`application/json`

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `event` | string | Yes | One of: `ship.arrived`. |
| `shipId` | integer | Yes |  |
| `berth` | string | Yes |  |
| `at` | string | Yes |  |

## Responses

### 200

Received. Any other answer and the harbor tries again, up to five times.