Docsmith Laravel Package

Getting Started

Minimal Setup

1. Installation:

   composer require mrpunyapal/docsmith
   

   Publish the package assets (if needed):

   php artisan vendor:publish --provider="MrPunyapal\DocSmith\DocSmithServiceProvider" --tag="public"
   

2. Basic Configuration: Edit config/docsmith.php to define your documentation source directory (default: resources/docs):

   'source' => resource_path('docs'),
   'output' => public_path('docs'),
   'theme' => 'default', // or a custom theme path
   

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

   ---
   title: Getting Started
   order: 1
   ---
   # Welcome to DocSmith!
   
   Write your documentation here in Markdown.
   

   Generate the site:

   php artisan docsmith:generate
   

   Access the output at /docs/getting-started.html.

Implementation Patterns

Workflows

1. Local Development:

   • Use php artisan docsmith:watch to auto-generate on file changes.
   • Integrate with Laravel Mix/Vite for live-reloading:

     // vite.config.js
     import { defineConfig } from 'vite';
     import { docsmithPlugin } from 'mrpunyapal/docsmith/vite';
     
     export default defineConfig({
       plugins: [docsmithPlugin()],
     });
     

2. CI/CD Pipeline:

   • Add to deployment scripts:

     # .github/workflows/deploy.yml
     - run: composer require mrpunyapal/docsmith
     - run: php artisan docsmith:generate --force
     

3. Multi-Language Docs:

   • Use frontmatter tags to group by language:

     ---
     lang: es
     ---
     

   • Override the generate command with a --lang flag (customize via service provider).

Integration Tips

• Laravel Blade Integration: Embed docs in Blade templates:

  @docsmith('getting-started', ['theme' => 'custom-theme'])
  

  Requires registering the Blade directive in AppServiceProvider.

• API Documentation: Combine with spatie/laravel-api-docs for OpenAPI specs:

  // config/docsmith.php
  'api_docs' => [
    'spec' => 'api/openapi.yaml',
    'output' => 'api-docs',
  ],
  

• Versioning: Use symbolic links or Git tags to manage versions:

  # Generate for v1.0
  php artisan docsmith:generate --version=v1.0
  

Gotchas and Tips

Pitfalls

1. Frontmatter Parsing:

   • YAML frontmatter must be indented with 3 spaces (not tabs).
   • Use this validator to debug malformed frontmatter.

2. Theme Conflicts:

   • Custom themes must include base.html and styles.css in their directory.
   • Override partials (e.g., partials/nav.html) by placing them in your theme folder.

3. Asset Pipeline:

   • If using Laravel Mix, ensure docsmith:generate runs after assets are compiled:

     // mix.js
     mix.js('resources/js/app.js', 'public/js')
       .then(() => run('docsmith:generate'));
     

4. Caching:

   • Clear the cache if changes aren’t reflecting:

     php artisan cache:clear
     php artisan view:clear
     

Debugging

• Verbose Output:

  php artisan docsmith:generate --verbose
  

• Dry Run:

  php artisan docsmith:generate --dry-run
  

  Lists files that would be processed without writing.

Extension Points

1. Custom Processors: Extend DocSmith\Processors\ProcessorInterface to handle custom Markdown:

   // app/Processors/CustomProcessor.php
   namespace App\Processors;
   
   use DocSmith\Processors\ProcessorInterface;
   
   class CustomProcessor implements ProcessorInterface {
       public function process(string $content): string {
           return str_replace('{{CUSTOM}}', 'Replaced!', $content);
       }
   }
   

   Register in config/docsmith.php:

   'processors' => [
       \App\Processors\CustomProcessor::class,
   ],
   

2. Event Listeners: Listen for docsmith.generated events to post-process output:

   // app/Listeners/PostProcessDocs.php
   namespace App\Listeners;
   
   use DocSmith\Events\DocsGenerated;
   
   class PostProcessDocs {
       public function handle(DocsGenerated $event) {
           // Example: Minify generated HTML
           foreach ($event->files as $file) {
               file_put_contents($file, $this->minify($file));
           }
       }
   }
   

   Register in EventServiceProvider.

3. CLI Customization: Override commands in AppServiceProvider:

   public function boot() {
       $this->app->singleton(\DocSmith\Console\GenerateCommand::class, function () {
           return new \App\Console\CustomGenerateCommand();
       });
   }