Laradocs

Maintain beautiful, version-controlled documentation inside your Laravel codebase. Write markdown, commit it next to the code it describes, and Laradocs serves a polished docs site at /docs (or wherever you like).

composer require petebishwhip/laradocs
php artisan laradocs:install

Then open /docs.

Requirements

	Minimum	Notes
PHP	8.3	8.4 and 8.5 fully supported
Laravel	11.14	12 and 13 fully supported
dedoc/scramble	0.13	Optional — only needed for the scramble OpenAPI driver

Features

• 📁 Multi-level file structure — nested folders become nested navigation.
• 🔗 Filename or metadata routing — slug: front-matter overrides paths.
• 📝 Markdown → HTML powered by CommonMark (GFM, tables, footnotes, …).
• 🏷️ Rich per-file metadata — title, description, order, hidden, group, badge, redirect, tags, and more.
• 🎨 Polished default UI — responsive, dark-mode, sidebar, breadcrumbs, on-page table of contents, prev/next — all publishable and overridable.
• ⚡ Smart caching — rendered HTML cached and auto-invalidated on file change.
• 🧩 Variables & macros — interpolate {{ values }} and reuse @docs() blocks, with a service-provider API to register your own.
• 🖼️ Rich content — callouts (> [!NOTE]), syntax-highlighted code with a copy button, lazy images with captions, and local/YouTube/Vimeo video embeds.
• 🔎 Automatic SEO — <title>, meta description, Open Graph & Twitter cards, canonical URLs and JSON-LD for every page, with per-page front-matter overrides.
• 🗺️ Sitemap — an auto-generated sitemap.xml at {prefix}/sitemap.xml, cached and invalidated alongside the rest of the docs cache.
• ✅ Fully tested — Pest + Testbench, 100% coverage gate, PHPStan & Psalm max, Pint.

Quick start

Create a page:

php artisan make:doc guide/getting-started --title="Getting Started" --order=1

---
title: Getting Started
description: Install and configure the app.
order: 1
group: Basics
---

# Getting Started

> [!TIP]
> Folders become sidebar sections; `_index.md` is a section's landing page.

Configuration

Everything is configurable in config/laradocs.php and via environment variables — route prefix/domain, docs path, routing strategy, theme, caching and more. See the Configuration docs.

LARADOCS_ROUTE_PREFIX=docs
LARADOCS_THEME=auto
LARADOCS_ENABLED=true

The Laradocs facade

use Laradocs\Facades\Laradocs;

Laradocs::variables(fn () => ['version' => '1.0.0']);
Laradocs::share('app_name', config('app.name'));
Laradocs::macro('tweet', fn (array $args) => "<a href=\"...\">@{$args['user']}</a>");

Artisan commands

Command	Description
laradocs:install	Publish config and scaffold a starter page
make:doc {name}	Scaffold a new markdown page with front-matter
laradocs:cache	Pre-render and cache every page
laradocs:clear	Clear the documentation cache
laradocs:openapi	Generate an OpenAPI spec from your routes (--driver=auto|native|scramble)

Publishing

php artisan vendor:publish --tag=laradocs-config
php artisan vendor:publish --tag=laradocs-views
php artisan vendor:publish --tag=laradocs-assets
php artisan vendor:publish --tag=laradocs-lang

Testing

composer test

Local development (workbench)

The package ships an orchestra/testbench workbench — a disposable Laravel app used to run Laradocs as a real, browsable site while you work on the package itself, rather than through Pest alone.

composer serve

This builds the workbench (testbench workbench:build) and boots it at /docs. The generated app lives at vendor/orchestra/testbench-core/laravel — it's regenerated on demand and isn't committed to git.

By default the workbench has no docs content, so /docs renders an empty state. Point it at the real docs in this repo (so edits under docs/ show up immediately, thanks to Laradocs' mtime-based cache) by adding to the workbench's .env:

# vendor/orchestra/testbench-core/laravel/.env
LARADOCS_PATH=/absolute/path/to/laradocs/docs

Or seed your own throwaway fixtures directly under the workbench's docs/ and lang/vendor/laradocs/<locale>/ — useful for exercising a specific feature (a locale, a version, a front-matter combination) without touching the real docs. Any config/laradocs.php option can be set via the workbench's own .env, exactly as in a consumer app — e.g. LARADOCS_LOCALE_AVAILABLE={"en":"English","fr":"Français"} to test localisation.

For finer control than composer serve gives you — e.g. driving the app with curl instead of a browser — build and serve it yourself:

composer run build              # just (re)build the workbench, don't serve
cd vendor/orchestra/testbench-core/laravel
php artisan config:clear        # pick up .env changes — Laravel may have cached the old config
php artisan serve               # or: php -S 127.0.0.1:8000 -t public public/index.php

Two gotchas worth knowing:

• composer dump-autoload wipes the workbench. The package's post-autoload-dump hook runs testbench package:purge-skeleton, which deletes the generated app — including any .env changes or fixtures you added. Re-run composer run build (or composer serve) afterwards to regenerate it.
• Config changes need config:clear. After editing the workbench's .env, run php artisan config:clear inside it if the change doesn't seem to take effect.

Documentation

The full docs live at laradocs.dev/docs — and are themselves built with Laradocs. Highlights:

• Getting started
• Configuration
• Routing
• Metadata
• Caching
• SEO
• Sitemap
• CLI reference
• PHP API
• Variables · Macros · Rich content
• Customising the UI · Customising stubs
• Migration guide: 0.x → 1.0

The source for those pages lives in docs/; browse there or serve a local copy with composer serve.

Sponsors

Laradocs is free and open source. If it saves you time, please consider sponsoring its development — it keeps the project actively maintained.

The image above is regenerated daily by the Scheduler workflow via sponsorkit.

Contributing & Security

See CONTRIBUTING.md and SECURITY.md.

License

The MIT License (MIT). See LICENSE.md.

Star History