Filament Docs Laravel Package

Getting Started

Minimal Steps to First Use

1. Installation

   composer require eightynine/filament-docs
   php artisan vendor:publish --tag="filament-docs-config"  # Optional, for customization
   mkdir -p resources/docs
   

2. Generate a Documentation Page

   php artisan make:filament-docs-page GettingStarted \
     --navigation-group="Documentation" \
     --navigation-icon="heroicon-o-book-open"
   

   This creates a Filament resource (app/Filament/Resources/DocsPageResource.php) and a corresponding navigation entry.

3. Add Markdown Content Create a file at resources/docs/getting-started.md:

   # Getting Started
   
   Welcome to your documentation!
   

4. Access the Docs Navigate to the Filament admin panel—the new "Documentation" section will appear in the sidebar, linking to your page.

First Use Case: Quick Documentation Page

• Use the CLI to scaffold a page (make:filament-docs-page).
• Write content in Markdown (e.g., resources/docs/quick-start.md).
• Leverage the built-in search to test real-time filtering (e.g., type quick in the search bar).
• Customize the navigation group/icon via the CLI flags or manually in the resource.

Implementation Patterns

Workflows

1. Content-Driven Development

   • Store Markdown files in resources/docs/ with a logical folder structure (e.g., resources/docs/admin/, resources/docs/api/).
   • Use the make:filament-docs-page command to generate Filament resources for each top-level category (e.g., AdminGuide, APIReference).
   • Example structure:

     resources/docs/
     ├── admin/
     │   ├── authentication.md
     │   └── permissions.md
     ├── api/
     │   └── endpoints.md
     └── getting-started.md
     

2. Integration with Filament Resources

   • Extend the DocsPageResource to add custom fields or logic. For example, add a published_at field to schedule documentation releases:

     // app/Filament/Resources/DocsPageResource.php
     public static function form(Form $form): Form
     {
         return $form
             ->schema([
                 // ... existing fields
                 TextInput::make('published_at')->date(),
             ]);
     }
     

3. Search Optimization

   • Use the built-in search to index content dynamically. For large documentation sets, pre-generate a search index via an Artisan command:

     // app/Console/Commands/GenerateDocsSearchIndex.php
     use Eightynine\FilamentDocs\Facades\Docs;
     
     public function handle()
     {
         Docs::rebuildSearchIndex();
     }
     

4. Multi-Language Support

   • Place language-specific Markdown files in subdirectories (e.g., resources/docs/es/, resources/docs/fr/).
   • Configure the config/filament-docs.php file to specify default and available locales:

     'locales' => [
         'en' => 'English',
         'es' => 'Español',
         'fr' => 'Français',
     ],
     

Integration Tips

1. Theming

   • Customize the appearance by publishing the config and modifying the Blade templates in resources/views/vendor/filament-docs/.
   • Override the default CSS by adding styles to your Filament theme’s assets:

     /* resources/css/filament-docs.css */
     .filament-docs .prose {
         font-family: 'Inter', sans-serif;
     }
     

2. Authentication & Permissions

   • Restrict access to documentation pages using Filament’s built-in policies. For example, limit the AdminGuide to users with the view-docs permission:

     // app/Filament/Resources/DocsPageResource.php
     public static function canAccess(): bool
     {
         return auth()->user()->hasPermissionTo('view-docs');
     }
     

3. Versioning

   • Use Git tags or a version field in the resource to track documentation versions. Example:

     # v1.2.0 - 2025-06-24
     ## Changes
     - Added new API endpoints.
     

   • Filter pages by version in the resource’s table:

     public static function table(Table $table): Table
     {
         return $table
             ->columns([
                 // ... other columns
                 TextColumn::make('version')->searchable(),
             ]);
     }
     

4. Embedding Docs in Filament Pages

   • Embed documentation snippets directly in Filament pages using the DocsEmbed component:

     use Eightynine\FilamentDocs\Components\DocsEmbed;
     
     public function form(Form $form): Form
     {
         return $form->schema([
             DocsEmbed::make('api_reference')
                 ->path('api/endpoints.md')
                 ->height('400px'),
         ]);
     }
     

Gotchas and Tips

Pitfalls

1. Markdown Parsing Quirks

   • Issue: Custom Markdown syntax (e.g., shortcodes or plugins) may not render correctly.
   • Fix: Use the parse method with custom options:

     use Eightynine\FilamentDocs\Facades\Docs;
     
     $content = Docs::parse(file_get_contents('path/to/file.md'), [
         'enable_autolink' => true,
         'enable_emphasis' => true,
     ]);
     

   • Tip: Test edge cases like nested lists, tables, or code blocks in your Markdown files.

2. Search Index Lag

   • Issue: Real-time search may feel slow for large documentation sets (>100 pages).
   • Fix: Schedule the search index rebuild during off-peak hours:

     // app/Console/Commands/RebuildDocsSearch.php
     protected function schedule(Schedule $schedule)
     {
         $schedule->command(self::class)->nightly();
     }
     

3. Navigation Group Conflicts

   • Issue: Duplicate navigation groups if multiple pages use the same --navigation-group flag.
   • Fix: Manually override the navigation group in the resource’s getNavigationGroup() method:

     public static function getNavigationGroup(): string
     {
         return 'Custom Documentation';
     }
     

4. Dark Mode Inconsistencies

   • Issue: Dark mode styling may not apply uniformly across all components.
   • Fix: Extend the default dark mode CSS in your Filament theme:

     /* resources/css/filament-docs-dark.css */
     .filament-docs.dark .prose {
         color: #e2e8f0;
     }
     .filament-docs.dark .prose a {
         color: #60a5fa;
     }
     

Debugging

1. Markdown Rendering Errors

   • Debug Tip: Check the storage/logs/laravel.log for parsing errors. Enable verbose logging in config/filament-docs.php:

     'debug' => [
         'markdown' => true,
         'search' => true,
     ],
     

   • Common Fixes:
     • Ensure Markdown files are UTF-8 encoded.
     • Avoid unsupported syntax (e.g., HTML blocks may not render as expected).

2. Search Not Returning Results

   • Debug Steps:
     1. Verify the search index is up-to-date:

        php artisan docs:rebuild-search-index
        

     2. Check for typos in the search query (case-sensitive by default).
     3. Ensure the searchable column is included in the resource’s table:

        TextColumn::make('content')->searchable()->hidden(),
        

3. Artisan Command Failures

   • Debug Tip: Use the --verbose flag for detailed output:

     php artisan make:filament-docs-page TestPage --verbose
     

   • Common Issues:
     • Missing resources/docs/ directory (create it manually if needed).
     • Permission denied errors (ensure the directory is writable).

Extension Points

1. Custom Markdown Extensions

   • Extend the Markdown parser by registering custom syntax:

     // app/Providers/FilamentDocsServiceProvider.php
     use Eightynine\FilamentDocs\Markdown\DocsMarkdown;
     
     public function boot()
     {
         DocsMarkdown::extend(function ($parser) {
             $parser->addRule('alert', function ($parser) {
                 // Custom rule for alert blocks
             });
         });
     }
     

2. Dynamic Content Loading

   • Load Markdown content dynamically from a database or API:

     use Eightynine\FilamentDocs\Facades\Docs;
     
     $content = Docs::parse($this->getContentFromDatabase());
     

3. Custom Search Providers

   • Replace the default search with Algolia or Meilisearch