Troubleshooting

Errors you will seeCopied

Invalid frontmatter in [file]: ...Copied

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

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

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

A ::: block whose name is not one Vellum ships. Almost always a typo. The shipped set is note, tip, info, warning, danger, success, idea, tabs, steps and cards.

Unknown docs component [x-name]Copied

A <x-…> tag with no matching Blade view. Check the view exists and 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.namespacesCopied

The view may well exist, but its prefix is not allowed in Markdown. Add the prefix to components.namespaces. Use '' or 'app' for unprefixed host components. See Extending.

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

Value tags refuse everything by default. Add the key you want to the matching list. This is deliberate: without it a docs page could print any config value or environment variable. See Value tags.

Unclosed docs component [x-name]Copied

An opening <x-name> with no </x-name>. Self-closing tags need the slash: <x-vellum::env key="APP_NAME" />.

Docs component [x-name] attributes must be quoted stringsCopied

Something like :type="$foo" in Markdown. Docs attributes are literal strings; there is no expression syntax. Pass dynamic values through a value tag, or compute them inside the component.

Two docs files resolve to [/slug]Copied

billing.md and billing/index.md both claim /docs/billing, or two pages share a frontmatter slug. The message names both files. Rename one.

vellum.search.driver is scout but laravel/scout is not installedCopied

Either run composer require laravel/scout or set the driver back to minisearch. See Search.

Where errors appearCopied

In local, and in vellum:build, these throw with the message above.

In production a reader gets a Vellum error page that says the page could not be rendered and nothing else; the reason and the file are in your log. vellum:build is the place to catch them, which is why it belongs in your deploy before the app goes live. See Commands.

Failures that are quietCopied

These do not raise. Check them by eye.

Editing changes nothingCopied

In local, a page recompiles when its file changes. Everywhere else the compiled cache is authoritative until you rebuild.

php artisan vellum:build

If a page is still stale after that, clear and rebuild:

php artisan vellum:clear
php artisan vellum:build

Deleting a Markdown file does not remove its compiled page on its own. vellum:clear does.

The site has no stylingCopied

Vellum registers routes at /vendor/vellum/vellum.css and /vendor/vellum/vellum.js that serve the compiled assets straight from the package, so styling works on a server where vellum:install has never run. You do not need to publish or commit anything.

vellum:install also copies those files into public/vendor/vellum. When they are there the web server answers for them as static files and the routes never run, which is one less PHP process per asset. Both paths work; the copy is an optimisation.

If a page really is unstyled, the routes are not reachable. Check that the package is discovered (php artisan route:list | grep vellum.assets), and that nothing in the app is intercepting /vendor/*.

Search returns nothingCopied

Check search.enabled is true, then rebuild the index with vellum:build or vellum:index. Gated pages are absent for readers who cannot see them, which is working as intended.

Still stuckCopied

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