Filament Documentation Laravel Package

Getting Started

Minimal Setup

1. Installation:

   composer require jeffersongoncalves/filament-documentation
   

   Publish the config and migrations (if needed):

   php artisan vendor:publish --provider="JeffersonGoncalves\FilamentDocumentation\FilamentDocumentationServiceProvider" --tag="config"
   

2. Configure Documentation Directory: Update config/filament-documentation.php to point to your Markdown files directory (default: resources/docs/):

   'directory' => resource_path('docs'),
   

3. First Use Case: Create a Markdown file (e.g., resources/docs/getting-started.md) with frontmatter:

   ---
   title: Getting Started
   order: 1
   ---
   # Welcome to the Admin Panel
   
   This is your first documentation page.
   

   Register the plugin in app/Providers/Filament/AdminPanelProvider.php:

   public function panel(Panel $panel): Panel
   {
       return $panel
           ->plugins([
               \JeffersonGoncalves\FilamentDocumentation\FilamentDocumentationPlugin::make(),
           ]);
   }
   

   Access the documentation via the Filament sidebar (default: "Documentation" tab).

Implementation Patterns

Workflow Integration

1. Documentation as Part of Admin Panel:

   • Use the plugin to embed internal team wikis, API references, or feature guides directly in Filament.
   • Example: Document a custom Filament resource’s fields in a dedicated .md file (e.g., resources/docs/resources/users.md).

2. Versioned Documentation:

   • Store Markdown files in versioned directories (e.g., resources/docs/v1/, resources/docs/v2/).
   • Override the directory config dynamically per environment or tenant:

     config(['filament-documentation.directory' => resource_path("docs/v{$version}")]);
     

3. Dynamic Sidebar Grouping:

   • Leverage YAML frontmatter to group pages hierarchically:

     ---
     title: "API"
     order: 2
     path: "/api"
     ---
     

   • Nest directories by naming conventions (e.g., resources/docs/api/auth.md, resources/docs/api/models.md).

4. Code Snippets with Syntax Highlighting:

   • Use GitHub Flavored Markdown (GFM) for code blocks:

     ```php
     public function mount()
     {
         FilamentDocumentation::register();
     }
     

   • Enable copy-to-clipboard via the plugin’s built-in highlight.js integration.

5. Localization:

   • Store translated Markdown files in resources/docs/en/, resources/docs/es/, etc.
   • Override the locale config or extend the plugin to auto-detect the Filament panel’s locale.

Integration Tips

• Link to Documentation from Resources/Pages: Add a custom action or button in Filament resources/pages to open relevant docs:

  use JeffersonGoncalves\FilamentDocumentation\Facades\FilamentDocumentation;
  
  FilamentDocumentation::open('resources/users');
  

• Embed Docs in Modals: Use the plugin’s render() method to display documentation in a modal:

  use JeffersonGoncalves\FilamentDocumentation\Widgets\DocumentationWidget;
  
  DocumentationWidget::make('getting-started')
      ->modalHeading('Documentation')
      ->modalWidth('75%');
  

• Customize Rendering: Extend the plugin’s DocumentationRenderer to add custom Markdown processors or post-render hooks:

  FilamentDocumentation::extend(function (Renderer $renderer) {
      $renderer->addExtension(new CustomMarkdownExtension());
  });
  

Gotchas and Tips

Pitfalls

1. Caching Issues:

   • Clear Filament’s cache and the plugin’s cache after updating Markdown files:

     php artisan filament:cache:clear
     php artisan cache:clear
     

   • Disable caching during development:

     'cache' => env('APP_ENV') !== 'local',
     

2. Frontmatter Parsing Errors:

   • Ensure YAML frontmatter is valid and indented correctly (use 3 dashes --- on new lines).
   • Debug with:

     php artisan filament-documentation:parse resources/docs/example.md
     

3. Directory Permissions:

   • Ensure the configured directory is readable by Laravel:

     chmod -R 755 resources/docs/
     

4. Highlight.js Conflicts:

   • If syntax highlighting fails, check for duplicate highlight.js scripts. Exclude the plugin’s script in your layout:

     @filamentScripts
     @vite(['resources/js/app.js', 'resources/js/filament-documentation.js'])
     

Debugging

• Log Parsing Errors: Enable debug mode in config/filament-documentation.php:

  'debug' => true,
  

  Check logs for frontmatter or file parsing issues.

• Verify File Structure: The plugin scans directories recursively. Ensure files are not hidden (e.g., .hidden.md) or excluded via .gitignore.

• Check for Plugin Registration: Confirm the plugin is registered in AdminPanelProvider and the panel is rebuilt:

  php artisan filament:panel rebuild
  

Extension Points

1. Custom Frontmatter Fields: Extend the DocumentationModel to support additional frontmatter keys (e.g., icon, tags):

   FilamentDocumentation::extend(function (DocumentationModel $model) {
       $model->fillable = ['icon', 'tags'];
   });
   

2. Dynamic Documentation Loading: Fetch Markdown from an external API or database by implementing a custom DocumentationProvider:

   FilamentDocumentation::provider(new ApiDocumentationProvider());
   

3. Search Functionality: Integrate with Laravel Scout or Algolia to add search to the documentation sidebar:

   use JeffersonGoncalves\FilamentDocumentation\Documentation;
   
   Documentation::search('laravel')->get();
   

4. Dark Mode Support: Override the plugin’s CSS to ensure compatibility with Filament’s dark mode:

   .filament-dark .filament-documentation {
       --filament-documentation-bg: #1a1a1a;
   }
   

5. Access Control: Restrict documentation access by user roles or permissions:

   FilamentDocumentation::middleware([
       \Filament\Panel::class,
       \JeffersonGoncalves\FilamentDocumentation\Middleware\Authorize::class,
   ]);