Jekyll Provider Bundle Laravel Package

Getting Started

Minimal Setup

1. Installation Add the package via Composer:

   composer require bloghoven/jekyll-provider-bundle
   

   Enable the bundle in config/bundles.php:

   Bloghoven\JekyllProviderBundle\BloghovenJekyllProviderBundle::class => ['all' => true],
   

2. Configuration Publish the default config:

   php artisan vendor:publish --tag=jekyll-provider-config
   

   Update config/jekyll_provider.php with your Jekyll site details (e.g., repo URL, branch, build command).

3. First Use Case Trigger a Jekyll build via Artisan:

   php artisan jekyll:build
   

   Verify output in the configured _site directory.

Implementation Patterns

Workflow Integration

1. CI/CD Pipelines Use the jekyll:build command in GitHub Actions/GitLab CI:

   - name: Build Jekyll
     run: php artisan jekyll:build
   

   Cache dependencies with composer install --no-dev before running the build.

2. Event-Driven Builds Hook into Laravel events (e.g., released for post-publish builds):

   use Bloghoven\JekyllProviderBundle\Events\JekyllBuilt;
   
   Event::listen(JekyllBuilt::class, function () {
       // Notify Slack/email on success
   });
   

3. Custom Build Commands Extend the base command for custom logic:

   use Bloghoven\JekyllProviderBundle\Commands\BuildJekyll;
   
   class CustomBuildJekyll extends BuildJekyll {
       protected function getBuildCommand() {
           return 'bundle exec jekyll build --trace --future';
       }
   }
   

   Register in AppServiceProvider:

   $this->commands([CustomBuildJekyll::class]);
   

4. Local Development Use jekyll:serve for live-reload during development:

   php artisan jekyll:serve
   

   Access the site at http://localhost:4000.

Gotchas and Tips

Pitfalls

1. Dependency Conflicts

   • Ensure ruby and bundler are installed globally.
   • Use a .ruby-version file to pin Ruby versions (e.g., 3.0.0).
   • Debug with:

     bundle exec jekyll --version
     

2. Permission Issues

   • Jekyll may fail if _site lacks write permissions:

     chmod -R 777 storage/_site
     

   • Use absolute paths in jekyll_provider.php to avoid relative path issues.

3. Build Failures

   • Check logs in storage/logs/jekyll.log.
   • Common causes:
     • Missing _config.yml (copy from a template repo).
     • Syntax errors in Markdown (validate with jekyll doctor).

4. Caching Quirks

   • Clear Laravel cache after config changes:

     php artisan cache:clear
     php artisan config:clear
     

Tips

1. Docker Integration Use a Dockerfile to isolate dependencies:

   FROM ruby:3.0
   RUN gem install bundler jekyll
   COPY . /app
   WORKDIR /app
   CMD ["bundle", "exec", "jekyll", "build"]
   

2. GitHub Actions Optimization Cache Ruby gems and node modules:

   - uses: actions/cache@v2
     with:
       path: vendor/bundle
       key: ${{ runner.os }}-gems-${{ hashFiles('**/Gemfile.lock') }}
   

3. Custom Providers Extend the bundle for non-GitHub repos (e.g., local directories):

   // config/jekyll_provider.php
   'provider' => [
       'class' => \Bloghoven\JekyllProviderBundle\Providers\LocalProvider::class,
       'path' => '/path/to/jekyll/source',
   ],
   

4. Debugging Enable verbose output:

   php artisan jekyll:build --verbose
   

   Or override the command class to log raw output:

   protected function handle() {
       $output = shell_exec($this->getBuildCommand() . ' 2>&1');
       file_put_contents(storage_path('logs/jekyll_debug.log'), $output);
   }