Laravel Docit Laravel Package

Getting Started

Minimal Setup

1. Installation

   composer require christhompsontldr/laravel-docit
   

   Publish the config and assets:

   php artisan vendor:publish --provider="ChrisThompson\Docit\DocitServiceProvider" --tag="docit-config"
   php artisan vendor:publish --provider="ChrisThompson\Docit\DocitServiceProvider" --tag="docit-assets"
   

2. Configuration Edit config/docit.php to define:

   • source (Markdown/Blade directory, default: resources/docit)
   • build (output directory, default: public/docs)
   • theme (customize HydePHP theme paths)

3. First Use Case Create a Markdown file (resources/docit/guide.md) with frontmatter:

   ---
   title: Getting Started
   ---
   # Welcome to Docit!
   Write your docs in **Markdown** or **Blade**.
   

   Generate static site:

   php artisan docit:build
   

   Access at /docs/guide.html.

Implementation Patterns

Workflow Integration

1. Markdown + Blade Hybrid

   • Use Blade for reusable components (e.g., resources/views/docit/partials/nav.blade.php).
   • Embed Blade in Markdown:

     @include('docit.partials.alert', ['type' => 'info', 'message' => 'Note:'])
     

2. Versioning

   • Organize docs by version in subdirectories (e.g., resources/docit/v1/, resources/docit/v2/).
   • Override build config per version in docit.php:

     'versions' => [
         'v1' => ['source' => 'resources/docit/v1', 'build' => 'public/docs/v1'],
         'v2' => ['source' => 'resources/docit/v2', 'build' => 'public/docs/v2'],
     ],
     

3. CI/CD Pipeline

   • Add to deploy.php (Deployer):

     task('build-docs', function () {
         run('php artisan docit:build');
     })->desc('Generate documentation');
     

   • Use GitHub Actions:

     - name: Build Docs
       run: php artisan docit:build
     

4. Theming

   • Extend HydePHP theme by copying vendor/hydephp/hydephp/resources/views to resources/views/docit.
   • Override config/docit.php:

     'theme' => [
         'views' => 'resources/views/docit',
         'assets' => 'resources/assets/docit',
     ],
     

5. Dynamic Content

   • Fetch Laravel data in Blade (e.g., resources/docit/api.blade.md):

     @php
         $routes = \Route::getRoutes()->getByName();
     @endphp
     ## API Endpoints
     @foreach($routes as $route)
         - `{{ $route->uri }}` ({{ $route->methods()[0] }})
     @endforeach
     

Gotchas and Tips

Pitfalls

1. Frontmatter Parsing

   • YAML frontmatter must be valid (e.g., no trailing commas in lists).

     # ❌ Fails
     tags: ['api', 'auth',]
     

     # ✅ Works
     tags: ['api', 'auth']
     

2. Blade Caching

   • Clear Blade cache after theme changes:

     php artisan view:clear
     

3. Asset Paths

   • Use @asset() in Blade for correct public path resolution:

     <link rel="stylesheet" href="{{ asset('docs/css/custom.css') }}">
     

4. Markdown Extensions

   • Enable GFM (GitHub Flavored Markdown) in config/docit.php:

     'markdown' => [
         'extra' => ['tables', 'fenced_code'],
     ],
     

Debugging

• Verbose Build Run with --verbose to diagnose issues:

  php artisan docit:build --verbose
  

• Check Compiled Files Inspect bootstrap/cache/docit.log for errors.

Extension Points

1. Custom Processors Extend DocitProcessor to add pre/post-processing:

   // app/Providers/DocitServiceProvider.php
   public function boot()
   {
       $this->app->extend('docit.processor', function ($processor) {
           $processor->afterRender(function ($content, $file) {
               return str_replace('{{ VERSION }}', '1.0.0', $content);
           });
           return $processor;
       });
   }
   

2. Hooks Bind to docit.beforeBuild/docit.afterBuild events:

   // app/Providers/EventServiceProvider.php
   protected $listen = [
       'ChrisThompson\Docit\Events\BeforeBuild' => [
           \App\Listeners\BackupDocs::class,
       ],
   ];
   

3. Custom Commands Create a new Artisan command to extend functionality:

   php artisan make:command DocitDeploy
   

   // app/Console/Commands/DocitDeploy.php
   public function handle()
   {
       $this->call('docit:build');
       $this->deployToS3();
   }