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

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.

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.

Edit permissions are configurable in config/grimoire.php:

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

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

License

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

blackpig-creatif / grimoire

Maintainers

Details