wamesk/docs

Laravel package that serves markdown files from your docs/ directory as a styled in-app documentation portal, with built-in authorization and optional API reference support via dedoc/scramble.

Requirements

• PHP 8.2+
• Laravel 11+
• dedoc/scramble ^0.13

Installation

composer require wamesk/docs

The service provider is registered automatically via Laravel's package discovery.

Setup

1. Create an application service provider

Create app/Providers/DocsServiceProvider.php by extending the abstract base class:

<?php

namespace App\Providers;

use Illuminate\Support\Facades\Gate;
use Wame\Docs\DocsApplicationServiceProvider;

class DocsServiceProvider extends DocsApplicationServiceProvider
{
    protected function gate(): void
    {
        Gate::define('viewDocs', function ($user) {
            return $user->is_admin;
        });
    }
}

2. Register the provider

Add it to bootstrap/providers.php:

return [
    // ...
    App\Providers\DocsServiceProvider::class,
];

3. Publish the config (optional)

php artisan vendor:publish --tag=docs-config

This publishes config/docs.php where you can customize the middleware stack:

return [
    'middleware' => [
        'web',
        \Wame\Docs\Http\Middleware\Authorize::class,
    ],
];

Usage

Place markdown files in your project's docs/ directory:

docs/
├── getting-started.md
├── installation.md
└── configuration.md

The package automatically discovers all .md files and lists them on the index page. The first heading (# Title) in each file is used as its display name.

Routes

Method	URI	Description
GET	/docs	Index — list of all documentation files
GET	/docs/{file}	Renders a single markdown file

Authorization

Access is controlled via the viewDocs Laravel Gate. Unauthenticated users are redirected to /. Authenticated users without permission receive a 403.

Override the gate() method in your application service provider to define who can access the docs:

protected function gate(): void
{
    Gate::define('viewDocs', function ($user) {
        return in_array($user->email, config('docs.allowed_emails', []));
    });
}

For full control over the authorization flow, override authorization():

protected function authorization(): void
{
    $this->gate();

    Docs::auth(function (Request $request): bool {
        return Gate::check('viewDocs', [$request->user()]);
    });
}

API Reference

The /docs/api route is reserved for API documentation rendered by dedoc/scramble. Configure Scramble separately in config/scramble.php.

License

MIT