README

Multi-version documentation support for petebishwhip/laradocs.

This package adds version-aware routing, navigation, and document resolution on top of the base Laradocs documentation system. It allows you to serve multiple versions of your documentation (e.g. V1, V2) from a single Laravel application, with isolated navigation and content per version.

Requirements

Dependency	Version
PHP	^8.3
illuminate/contracts	^13.0
illuminate/support	^13.0
petebishwhip/laradocs	0.1.4
symfony/finder	^7.0 or ^8.0

Installation

composer require arvinajiftechnology/laradocs-versioning

The service provider is auto-discovered by Laravel. No manual registration is needed.

Documentation Directory Structure

Place your versioned documentation in the project's docs/ directory (configurable). Each version is a subdirectory:

docs/
├── V1/
│   ├── index.md
│   ├── 1. Getting Started/
│   │   ├── 1. installation.md
│   │   └── 2. configuration.md
│   └── 2. Features/
│       └── 1. overview.md
├── V2/
│   ├── index.md
│   └── ...
└── index.md

Each version folder (e.g. V1/, V2/) maps to a version slug in the URL.
The folder name is normalized to lowercase for URL matching (V1 → v1).
Versions are discovered automatically from the filesystem, or can be explicitly listed in configuration.

URLs

The package registers the following canonical URL patterns under the configured prefix (default: /docs):

URL	Behavior
`/docs`	301 redirect to `/docs/{default}`
`/docs/v1`	Render the landing page (index) for V1
`/docs/v1/{slug}`	Render a specific document within V1
`/docs/v2`	Render the landing page (index) for V2
`/docs/v2/{slug}`	Render a specific document within V2

If a document slug does not exist in the requested version, the user is redirected to that version's root page (302).

Configuration

Publish the configuration file:

php artisan vendor:publish --tag=laradocs-versioning-config

This creates config/laradocs-versioning.php with the following keys:

`route.prefix`

The URL segment under which documentation is served.

'route' => [
    'prefix' => env('LARADOCS_VERSIONING_ROUTE_PREFIX', 'docs'),
],

`docs.path`

Absolute path to the root directory containing version folders.

'docs' => [
    'path' => env('LARADOCS_VERSIONING_PATH', base_path('docs')),
],

`versioning.default`

The fallback version slug when none is detected in the URL. Used when /docs is accessed directly.

'versioning' => [
    'default' => env('LARADOCS_VERSIONING_DEFAULT', 'v1'),
],

`versioning.available`

An explicit list of versions. When non-empty, this overrides filesystem discovery. Each entry needs at least a slug and label. Leave empty to auto-discover from the docs directory.

'versioning' => [
    'available' => [],
],

Environment Variables

Variable	Config Key	Default
`LARADOCS_VERSIONING_ROUTE_PREFIX`	`route.prefix`	`docs`
`LARADOCS_VERSIONING_PATH`	`docs.path`	`base_path('docs')`
`LARADOCS_VERSIONING_DEFAULT`	`versioning.default`	`v1`

Integration Behavior

View Namespace

The package loads its Blade views under the laradocs-versioning:: namespace. This is separate from the upstream petebishwhip/laradocs views to prevent namespace collisions.

To customize a view, publish it:

php artisan vendor:publish --tag=laradocs-versioning-views

Note: View publishing is not yet implemented. Views are loaded directly from the package's resources/views directory.

Route Integration

The package registers routes under the laradocs. route name prefix. These routes intentionally override the upstream Laradocs routes (laradocs.index and laradocs.show) so that version-aware routing takes precedence.

Routes are registered after all service providers have booted to ensure the override order is correct.

Service Bindings

The package registers the following singletons in the service container:

ArvinAjifTechnology\LaradocsVersioning\Services\VersionResolver
ArvinAjifTechnology\LaradocsVersioning\Services\VersionDocService
ArvinAjifTechnology\LaradocsVersioning\Services\NavigationResolver
ArvinAjifTechnology\LaradocsVersioning\Services\LaradocsData

Assets

CSS and JavaScript assets are served automatically by the upstream petebishwhip/laradocs package. No additional setup is required.

If you need to host assets from the public/ directory (e.g. for static hosting or CDN), you can publish them:

php artisan vendor:publish --tag=laradocs-assets

This copies the assets to public/vendor/laradocs/. This step is optional — the documentation UI works without it.

Database Requirement

The consumer Laravel application must have a working database and session configuration. If you are using SQLite (the Laravel default), ensure the database file exists and migrations have been run:

touch database/database.sqlite
php artisan migrate

Version Isolation

Navigation, search results, and document resolution are fully version-aware:

V1 navigation only shows V1 documents
V2 navigation only shows V2 documents
Searching within V1 only returns V1 results
Document slugs are scoped per version (the same slug can exist in both V1 and V2)

Development / Testing

From the package directory:

cd package/laradocs-versioning
composer install
vendor/bin/phpunit

The test suite uses Orchestra Testbench to run Laravel package tests in isolation.

License

MIT

arvinajiftechnology / laradocs-versioning

Package info

Security

Statistics