Statamic Documentation Laravel Package

Getting Started

Install and confirm compatibility first. The package is a Statamic addon, so the install is a single Composer require:

composer require jonassiewertsen/statamic-documentation

Before doing anything else, open vendor/jonassiewertsen/statamic-documentation/composer.json and check the require block. This addon has essentially no public adoption, so the single most important question is which Statamic major versions it supports (v3 vs v4/v5) and whether that matches your project. If the constraint is stale, stop here.

Where to look first, in order:

1. src/ServiceProvider.php — see what it registers: CP nav item, routes, permissions, config merge, publishable assets.
2. config/statamic-documentation.php (after publishing) — almost certainly defines where documentation files live on disk. This is the knob you will actually touch.
3. routes/cp.php — tells you the route names you can link to (cp_route('statamic-documentation.index') or similar).
4. resources/views/ — the CP rendering, which tells you what Markdown features are supported.

Publish the config if the provider supports it:

php artisan vendor:publish --provider="Jonassiewertsen\Documentation\ServiceProvider"

Statamic addons are auto-discovered via Laravel package discovery, so there is normally nothing to add to config/app.php. If the package is not auto-discovered, add the provider to config/statamic/editions.php? No — add it to your app's providers array in bootstrap/providers.php (Laravel 11+) or config/app.php (older).

First use case: write internal editorial documentation for the client's content team — "how to publish a page", "image size guidelines", "what the blue banner field does" — and have it appear as a "Documentation" item in the control panel nav, next to Content and Assets. This is the canonical use: not public-facing docs, but a help section for the people who log into the CP.

Clear your caches after install so the nav registers:

php artisan cache:clear && php artisan config:clear && php artisan view:clear

Implementation Patterns

Treat docs as files in the repo, not as database content. The whole value of this addon is that documentation sits as Markdown files in your project, versions with your code, and deploys with it. A typical workflow:

documentation/
  01-getting-started.md
  02-pages/
    01-creating-a-page.md
    02-publishing.md
  03-assets.md

Front matter (title, order, maybe a category) drives the sidebar. Numeric filename prefixes are the low-tech way to control ordering when the addon doesn't support an explicit order field.

Client handover pattern. For agencies, this is the strongest fit: one repo, one deploy, and the handover docs are live in the client's CP the moment the site goes live. Combine with Statamic permissions so editors see the Documentation nav but not Settings, and lock down who can edit docs (or make them read-only from disk).

Authoring workflow:

• Write in Markdown with fenced code blocks; assume CommonMark rendering, not full GitHub-flavored Markdown. Verify tables and task lists render before relying on them.
• Put screenshots in the public assets disk and reference them with asset('docs/foo.png') or an absolute /assets/... path — relative paths from the CP route usually won't resolve.
• Keep each page short. There is typically no built-in search, so depth must be reachable through the sidebar tree.

Integration points worth wiring up:

• A dashboard widget or a Statamic::script-injected link on the Content listing: "Need help? Read the docs."
• A nav shortcut from the collection edit screen to the matching doc page via cp_route(...).
• Custom CSS injected with Statamic::style() to match the CP theme if the addon ships unstyled views.

Migration path if you outgrow it: the addon is a thin Markdown browser. If you need search, versioning, or per-collection contextual docs, the escape hatch is a normal Statamic collection (docs) plus an Antlers template rendered inside the CP via a custom route — same content, more control, no third-party dependency.

Gotchas and Tips

• Ephemeral filesystems will eat your docs. If the addon writes documentation from the CP back to disk, and you deploy to Heroku, Laravel Vapor, or anything with an ephemeral filesystem, edits made in production vanish on the next deploy. Decide up front whether docs are read-only from git or CP-editable; don't mix them.
• File permissions. If CP editing is enabled, the documentation directory must be writable by the web user. On a hardened production host this is often not the case and you get silent save failures — check storage/logs/laravel.log and the directory's group ownership.
• Zero-adoption risk. Zero stars and zero dependents means no community pressure to keep it current and no Stack Overflow answers. Read the provider (~100 lines, probably) before shipping. Pin the version in composer.json and avoid ^ if the author releases breaking changes casually.
• Statamic major upgrades. Addons that hook CP\Nav and register routes frequently break between Statamic 3 → 4 → 5 (route registration, Nav::extend signature, Vite asset publishing). Budget an hour for manual re-verification on every Statamic upgrade; if it breaks and is unmaintained, fork it — the code is small enough that maintaining a fork is cheaper than an alternative.
• Config and view caching. After publishing config or overriding views, php artisan config:clear and php artisan view:clear. A stale config cache pointing at the wrong docs path is the most common "the package is broken" false alarm. Also verify php artisan route:list | grep -i doc actually shows the CP routes.
• Permissions. Check whether the service provider registers a permission group. If it doesn't, every CP user sees the nav item — including roles where you'd rather they didn't. Gate it by extending the nav yourself or hiding the section in a small custom service provider.
• Markdown fidelity. Statamic's Markdown pipeline strips raw HTML by default. If you paste HTML tables or <details> blocks into docs, they may render as escaped text. Use Markdown::parse() settings or stick to pure Markdown.
• Extension points to prefer: publishable views (vendor:publish --tag=statamic-documentation-views) and the config file. Avoid editing vendor/ — patching vendor code is invisible to the next developer and disappears on composer update.
• No front-end route by default. This is CP-only; don't plan to reuse the same docs on a marketing site without writing your own route and controller over the same files.