README

In-panel documentation for FilamentPHP v5 applications.

Grimoire lets you embed rich, versioned documentation directly inside your Filament admin panel. Organise content into Tomes (top-level books) and Chapters (individual pages), author in Markdown with YAML frontmatter, and edit chapters inline without leaving the panel.

Requirements

• PHP 8.2+
• Laravel 11 or 12
• Filament v5

Installation

composer require blackpig-creatif/grimoire

Publish the config (optional):

php artisan vendor:publish --tag="grimoire-config"

Plugin Registration

Register the plugin in your Filament panel provider:

use BlackpigCreatif\Grimoire\GrimoirePlugin;

public function panel(Panel $panel): Panel
{
    return $panel
        ->plugins([
            GrimoirePlugin::make()
                ->navigationGroup('Help')    // optional — defaults to 'Help'
                ->withDocs(),                // optional — enables Grimoire's own built-in docs
        ]);
}

Registering a Tome

A Tome is a top-level documentation section. Register one in your AppServiceProvider::boot():

use BlackpigCreatif\Grimoire\Facades\Grimoire;

Grimoire::registerTome(
    id: 'my-docs',
    label: 'My Documentation',
    icon: 'heroicon-o-book-open',
    path: resource_path('grimoire/my-docs'),
    clusterClass: \App\Filament\Grimoire\Clusters\MyDocsCluster::class,
);

Then scaffold the required Filament stubs:

php artisan grimoire:make-tome my-docs "My Documentation"

Adding Chapters

php artisan grimoire:make-chapter my-docs my-chapter "My Chapter Title"

This generates a Filament page stub and a Markdown file at resources/grimoire/my-docs/my-chapter.md. Add content with YAML frontmatter:

---
title: My Chapter
order: 1
icon: heroicon-o-document-text
---

# My Chapter

Content goes here.

Extending a Tome

Override or add chapters to any Tome (including vendor Tomes) from your app:

Grimoire::extendTome(
    id: 'my-docs',
    path: resource_path('grimoire/my-docs-local'),
);

Local chapters take priority over vendor chapters on slug collision — useful for overriding package documentation with app-specific notes.

Permissions

Access to view and edit documentation is controlled via config/grimoire.php:

'permissions' => [
    'view' => null,   // null = allow all authenticated users (default)
    'edit' => null,   // null = deny all (default)
],

Each key accepts one of the following:

null (default behaviour)

• view: all authenticated users may read chapters
• edit: no one may edit chapters

A Laravel Gate ability name

'permissions' => [
    'view' => 'view-docs',
    'edit' => 'edit-docs',
],

Define the ability in AuthServiceProvider (or a dedicated GrimoirePolicy):

Gate::define('view-docs', fn (User $user) => $user->hasRole('staff'));
Gate::define('edit-docs', fn (User $user) => $user->hasRole('admin'));

A Class@method string

'permissions' => [
    'view' => \App\Policies\GrimoirePolicy::class . '@view',
    'edit' => \App\Policies\GrimoirePolicy::class . '@edit',
],

The method receives the authenticated user as its only argument and must return a boolean.

A closure (local development only)

Closures work when config is not cached, making them convenient for local development. They cannot be used in production with php artisan config:cache.

'permissions' => [
    'view' => fn ($user) => true,
    'edit' => fn ($user) => $user->is_admin,
],

Inline Editing

Authenticated users with edit permission can edit chapter content directly in the panel. Click Edit on any chapter page to switch to an inline editor with a Markdown editor for content and a YAML editor for frontmatter.

Locale Support

Grimoire supports two locale strategies for multilingual documentation. Configure in config/grimoire.php:

'locale_strategy' => 'suffix',   // 'suffix' or 'directory'
'fallback_locale'  => 'en',

Suffix strategy — place locale variants alongside the default file:

my-chapter.md       ← locale-neutral fallback
my-chapter.fr.md    ← French
my-chapter.de.md    ← German

Directory strategy — organise by locale subdirectory:

my-chapter.md
fr/my-chapter.md
de/my-chapter.md

Grimoire resolves files in order: current locale → fallback locale → locale-neutral.

Built-in Self-Documentation

Enable Grimoire's own documentation Tome inside your panel with ->withDocs():

GrimoirePlugin::make()->withDocs()

// Or conditionally — e.g. local environment only:
GrimoirePlugin::make()->withDocs(fn ($user) => app()->isLocal())

Caching

For production, cache the navigation tree:

php artisan grimoire:cache
php artisan grimoire:clear-cache

Testing

composer test

Changelog

Please see CHANGELOG for more information on what has changed recently.

Contributing

Please see CONTRIBUTING for details.

Security Vulnerabilities

Please review our security policy on how to report security vulnerabilities.

Credits

• Blackpig Creatif
• All Contributors

License

The MIT License (MIT). Please see License File for more information.