Filament Documentation

https://github.com/jeffersongoncalves/filament-documentation
Admin
Filament Documentation is a Laravel Filament plugin that adds markdown-based documentation directly...
Tokens:5,341
Snippets:76
Trust Score:9.8
License:MIT
Update:1 month ago
Show doc for...
Tokens:
Raw
### Publish Config and Example Docs

Source: https://github.com/jeffersongoncalves/filament-documentation/blob/3.x/README.md

Publishes the config and example docs.

```bash
php artisan docs:install
```

--------------------------------

### Install filament-documentation with Composer

Source: https://github.com/jeffersongoncalves/filament-documentation/blob/3.x/tests/fixtures/docs/installation.md

Install the package via Composer. Requires PHP 8.2+ and Laravel 11+.

```bash
composer require jeffersongoncalves/filament-documentation
```

--------------------------------

### Install and register FilamentDocumentationPlugin

Source: https://github.com/jeffersongoncalves/filament-documentation/blob/3.x/resources/docs/installation.md

Install the package with Composer and run the artisan command to publish assets. Then register the plugin in the AdminPanelProvider with the given configuration, setting the slug, navigation label, and icon.

```bash
composer require jeffersongoncalves/filament-documentation
php artisan docs:install
```

```php
use JeffersonGoncalves\FilamentDocumentation\FilamentDocumentationPlugin;

public function panel(Panel $panel): Panel
{
    return $panel
        ->plugins([
            FilamentDocumentationPlugin::make()
                ->slug('docs')
                ->navigationLabel('Documentation')
                ->navigationIcon('heroicon-o-book-open'),
        ]);
}
```

--------------------------------

### YAML frontmatter example

Source: https://github.com/jeffersongoncalves/filament-documentation/blob/3.x/README.md

Optional YAML frontmatter for each documentation file. Supports title, path, and order keys.

```yaml
---
title: "Getting Started"
path: home
order: 1
---
```

--------------------------------

### Relative links example

Source: https://github.com/jeffersongoncalves/filament-documentation/blob/3.x/README.md

Relative links between documentation files are automatically converted to panel routes.

```markdown
- [Installation](installation.md)
- [Advanced](advanced/overview.md)
```

--------------------------------

### Nested documentation directory structure

Source: https://github.com/jeffersongoncalves/filament-documentation/blob/3.x/resources/docs/advanced/overview.md

Example directory structure for organizing documentation in subdirectories. Subdirectories automatically become collapsible groups in the sidebar.

```text
resources/docs/
├── home.md
├── installation.md
├── configuration.md
└── advanced/
    ├── overview.md
    ├── authorization.md
    └── customization.md
```

--------------------------------

### Manually publish config or docs with vendor:publish

Source: https://github.com/jeffersongoncalves/filament-documentation/blob/3.x/resources/boost/skills/documentation-development/SKILL.md

Use these commands to manually publish only the configuration file or only the example documentation files. The tags are filament-documentation-config and filament-documentation-docs.

```bash
# Config only
php artisan vendor:publish --tag=filament-documentation-config

# Example docs only
php artisan vendor:publish --tag=filament-documentation-docs
```

--------------------------------

### Enable authorization and define viewDocumentation gate

Source: https://github.com/jeffersongoncalves/filament-documentation/blob/3.x/resources/docs/advanced/overview.md

Enable authorization on the plugin, then define a gate for the 'viewDocumentation' ability. The gate example restricts access to users with the 'admin' role.

```php
FilamentDocumentationPlugin::make()
    ->withAuthorization(true)
```

```php
Gate::define('viewDocumentation', function ($user) {
    return $user->hasRole('admin');
});
```

--------------------------------

### Configure custom docs path in config file

Source: https://github.com/jeffersongoncalves/filament-documentation/blob/3.x/resources/docs/advanced/overview.md

Set the documentation source directory by configuring the 'docs_path' option in the plugin's config file. The example points to the project's 'docs' directory.

```php
// config/filament-documentation.php
'docs_path' => base_path('docs'),
```

--------------------------------

### Publish Config and Docs Individually

Source: https://github.com/jeffersongoncalves/filament-documentation/blob/3.x/README.md

Publishes the config and docs individually.

```bash
php artisan vendor:publish --tag=filament-documentation-config
php artisan vendor:publish --tag=filament-documentation-docs
```

--------------------------------

### Publish the configuration file

Source: https://github.com/jeffersongoncalves/filament-documentation/blob/3.x/resources/docs/configuration.md

Run this artisan command to publish the plugin's config file to config/filament-documentation.php.

```bash
php artisan vendor:publish --tag=filament-documentation-config
```

--------------------------------

### Configure config/filament-documentation.php

Source: https://github.com/jeffersongoncalves/filament-documentation/blob/3.x/resources/boost/skills/documentation-development/SKILL.md

This is the default configuration file. The cache_minutes option is set to 10 by default and can be set to 0 to disable caching. The login_route is null by default.

```php
// config/filament-documentation.php
return [
    'title'         => env('DOCS_TITLE', 'Documentation'),
    'docs_path'     => resource_path('docs'),
    'home'          => 'home.md',
    'cache_minutes' => env('DOCS_CACHE', 10),  // 0 to disable
    'login_route'   => null,
];
```

--------------------------------

### Configuration file config/filament-documentation.php

Source: https://github.com/jeffersongoncalves/filament-documentation/blob/3.x/README.md

Configuration file for the Filament documentation plugin. The docs_path is configurable and cache_minutes can be set to 0 to disable caching.

```php
// config/filament-documentation.php

return [
    'title'         => env('DOCS_TITLE', 'Documentation'),
    'docs_path'     => resource_path('docs'),
    'home'          => 'home.md',
    'cache_minutes' => env('DOCS_CACHE', 10),  // 0 to disable
    'login_route'   => null,
];
```

--------------------------------

### Enable authorization with withAuthorization and Gate::define

Source: https://github.com/jeffersongoncalves/filament-documentation/blob/3.x/resources/boost/skills/documentation-development/SKILL.md

Enable authorization by calling withAuthorization(true) on the plugin, then define a gate named 'viewDocumentation' in your AuthServiceProvider or a policy. When enabled, DocumentationPage::canAccess() checks auth()->user()->can('viewDocumentation').

```php
FilamentDocumentationPlugin::make()
    ->withAuthorization(true)
```

```php
use Illuminate\Support\Facades\Gate;

Gate::define('viewDocumentation', function ($user) {
    return $user->hasRole('admin');
});
```

--------------------------------

### Enable authorization with withAuthorization

Source: https://github.com/jeffersongoncalves/filament-documentation/blob/3.x/README.md

Enables authorization for the Filament documentation plugin by calling withAuthorization(true) on the plugin instance.

```php
FilamentDocumentationPlugin::make()
    ->withAuthorization(true)
```

--------------------------------

### Run tests with composer test

Source: https://github.com/jeffersongoncalves/filament-documentation/blob/3.x/README.md

Runs the test suite for the package using Composer.

```bash
composer test
```

--------------------------------

### File resolution order for DocumentationPage

Source: https://github.com/jeffersongoncalves/filament-documentation/blob/3.x/resources/boost/skills/documentation-development/SKILL.md

File resolution order used by resolveFilePath(): tries direct file, then directory index, then falls back to the configured home file. The home setting defaults to 'home.md'.

```php
// 1. Direct file match
$docsPath . '/' . $slug . '.md'

// 2. Directory index
$docsPath . '/' . $slug . '/index.md'

// 3. Fallback to home
$docsPath . '/' . config('filament-documentation.home', 'home.md')
```

--------------------------------

### Cache documentation parsing with Cache::remember

Source: https://github.com/jeffersongoncalves/filament-documentation/blob/3.x/resources/boost/skills/documentation-development/SKILL.md

Caches parsed documentation files using a key based on file path and modification time. The cache duration is configured in minutes, defaulting to 10. Set DOCS_CACHE=0 to disable caching during development.

```php
// Cache key includes file path + modification time
$cacheKey = 'filament_docs_' . md5($filePath . filemtime($filePath));

// Cached for configured minutes (default: 10)
Cache::remember($cacheKey, now()->addMinutes($cacheMinutes), fn () => $this->parseFile($filePath));
```

--------------------------------

### YAML frontmatter for documentation pages

Source: https://github.com/jeffersongoncalves/filament-documentation/blob/3.x/resources/docs/configuration.md

Add this YAML frontmatter to each .md file to set the page title, custom URL slug, and sidebar sort order.

```yaml
---
title: "Page Title"
path: custom-slug
order: 1
---
```

--------------------------------

### Register Plugin in PanelProvider

Source: https://github.com/jeffersongoncalves/filament-documentation/blob/3.x/README.md

Registers the plugin in the PanelProvider with optional configuration methods.

```php
use JeffersonGoncalves\FilamentDocumentation\FilamentDocumentationPlugin;

public function panel(Panel $panel): Panel
{
    return $panel
        ->plugins([
            FilamentDocumentationPlugin::make()
                ->slug('docs')
                ->navigationLabel('Documentation')
                ->navigationIcon('heroicon-o-book-open')
                ->navigationGroup('Help')
                ->navigationSort(99)
                ->withAuthorization(false),
        ]);
}
```

--------------------------------

### Configure plugin options with FilamentDocumentationPlugin

Source: https://github.com/jeffersongoncalves/filament-documentation/blob/3.x/resources/docs/configuration.md

Use these chainable methods to customize the plugin's slug, navigation label, icon, group, sort order, and authorization requirement.

```php
FilamentDocumentationPlugin::make()
    ->slug('docs')                          // URL: /admin/docs
    ->navigationLabel('Documentation')      // Sidebar label
    ->navigationIcon('heroicon-o-book-open') // Sidebar icon
    ->navigationGroup('Help')               // Group in sidebar
    ->navigationSort(99)                    // Sort order
    ->withAuthorization(false)              // Require authorization policy
```

--------------------------------

### Define viewDocumentation gate in AuthServiceProvider

Source: https://github.com/jeffersongoncalves/filament-documentation/blob/3.x/resources/boost/skills/documentation-development/SKILL.md

Required when withAuthorization(true) is enabled and no viewDocumentation gate is defined. Place this in your AuthServiceProvider to allow access.

```php
Gate::define('viewDocumentation', fn ($user) => true);
```

--------------------------------

### Navigation node structure for NavigationBuilder

Source: https://github.com/jeffersongoncalves/filament-documentation/blob/3.x/resources/boost/skills/documentation-development/SKILL.md

Structure of a navigation node in the recursive tree. Files use type 'file', directories use 'directory' with children. The 'active' flag is set by markActive() based on the current slug.

```php
[
    'type'     => 'file',        // 'file' or 'directory'
    'title'    => 'Getting Started',
    'slug'     => 'home',
    'order'    => 1,
    'path'     => 'home',
    'active'   => true,
    'children' => [],
]
```

--------------------------------

### Define viewDocumentation gate

Source: https://github.com/jeffersongoncalves/filament-documentation/blob/3.x/README.md

Defines a gate named 'viewDocumentation' that checks if the user has the 'admin' role, used to restrict access to the documentation.

```php
Gate::define('viewDocumentation', function ($user) {
    return $user->hasRole('admin');
});
```
Tokens:
Raw