Documentation

Versioning

Serve multiple documentation versions from sibling folders with a version switcher in the header.

On this page 8

Laradocs supports serving more than one version of your documentation from a single Laravel application. Each version lives in its own sub-directory under docs/, gets its own cache namespace, and is accessible under a version-prefixed URL path (e.g. /docs/v2/getting-started).

Quick start

1. Enable versioning in your config:

php
// config/laradocs.php
'versions' => [
    'enabled' => true,
    'default' => 'v2',         // version shown at /docs/ with no prefix
    'available' => null,       // null = auto-detect from sub-directories
    'selector' => true,
],

Or via your .env file:

code
LARADOCS_VERSIONS=true
LARADOCS_VERSION_DEFAULT=v2

2. Reorganise your docs into version sub-directories:

code
docs/
  v1/
    _index.md
    getting-started.md
    ...
  v2/
    _index.md
    getting-started.md
    ...

That's it. Laradocs scans the docs/ directory, discovers v1 and v2, and begins serving:

  • /docs/ — redirects to the default version home page
  • /docs/v1/ — v1 landing page
  • /docs/v1/getting-started — v1 page
  • /docs/v2/getting-started — v2 page

A version switcher appears in the header automatically when two or more versions are detected.

Version directory detection

By default Laradocs auto-detects versions by scanning every sub-directory of laradocs.docs.path. Any directory found there becomes a version handle — so if you have docs/v1, docs/v2 and docs/archive, all three will be offered.

Custom labels

Add a _version.json file inside any version directory to give it a human-readable label:

json
// docs/v2/_version.json
{ "label": "v2 (latest)" }

Explicit version list

To control which versions appear (and in what order) set versions.available to an explicit array:

php
'versions' => [
    'enabled' => true,
    'available' => [
        'v2' => 'v2 (latest)',
        'v1' => 'v1',
    ],
],

An empty array hides the selector entirely while still enabling version-prefixed routing.

Caching

Cache keys are automatically namespaced per version. When version v1 is active all keys are prefixed laradocs:v1:…; version v2 uses laradocs:v2:…. The two sets never collide, so editing a page in one version does not invalidate the other version's cache.

Run php artisan laradocs:cache and php artisan laradocs:clear as usual — they operate on the version that matches the current laradocs.versions.default setting. To warm or clear a specific version's cache from code, temporarily set laradocs._current_version in config before calling the cache helpers.

Migrating a single-version project

If you are currently serving docs without versioning enabled, here is the recommended migration path:

  1. Create a versioned sub-directory and move your existing content into it:

    bash
    mkdir docs/v1
mv docs/*.md docs/v1/
mv docs/*/  docs/v1/   # move any sub-directories too

  2. Enable versioning and set the default:

    php
    'versions' => [
    'enabled' => true,
    'default' => 'v1',
],

  3. Redirect old URLs (optional). If you already have readers or search-engine links pointing at /docs/page, set up redirects in your web server or routes/web.php:

    php
    Route::redirect('/docs/{path}', '/docs/v1/{path}')
    ->where('path', '(?!v1/).*');

  4. Clear the cache:

    bash
    php artisan laradocs:clear
php artisan laradocs:cache

Your existing single-version docs are now served as v1 with the version switcher visible in the header. Add a v2/ sibling directory whenever you are ready to publish the next version.

URL structure

With versioning enabled, every internal link generated by Laradocs automatically includes the active version prefix. The DocumentUrl helper and all Blade template links are version-aware by default — you do not need to change any existing views or markdown links.

Links to external URLs are never modified.

Disabling the selector

The selector is hidden automatically when fewer than two versions are detected. You can also disable it explicitly:

php
'versions' => [
    'enabled' => true,
    'selector' => false,
],

This is useful when you want version-prefixed URLs (for caching or API-client clarity) but do not want a UI toggle.

Edit this page