Jekyll Site Helpers Laravel Package

Getting Started

Minimal Steps

1. Installation:

   • Add the package to your composer.json under "require":

     "mi3ll/jekyll-site-helpers": "dev-master"
     

   • Configure Composer to install the package into your Jekyll _plugins directory:

     "extra": {
       "installer-paths": [
         "./src/_plugins/{$name}": ["mi3ll/jekyll-site-helpers"]
       ]
     }
     

   • Run composer update to install.

2. Verify Setup:

   • Ensure the package files are in src/_plugins/jekyll-site-helpers/.
   • Restart your Jekyll server (bundle exec jekyll serve).

3. First Use Case:

   • Use the relativity filter to make a path relative to the current page:

     {{ '/assets/image.png' | relativity }}
     

   • Use the cachebuster filter to append a timestamp for cache busting:

     {{ '/assets/image.png' | cachebuster | relativity }}
     

Implementation Patterns

Common Workflows

1. Asset Path Handling:

   • Use relativity to dynamically generate relative paths for assets (e.g., images, CSS, JS) based on the current page location.
   • Example:

     <img src="{{ '/images/logo.png' | relativity }}" alt="Logo">
     

2. Cache Busting:

   • Combine cachebuster and relativity to ensure users always fetch the latest version of assets.
   • Example:

     <link rel="stylesheet" href="{{ '/css/styles.css' | cachebuster | relativity }}">
     

3. Configurable Cache Busting:

   • Use filebuster with a custom variable in _config.yml (e.g., cache_version) to avoid hardcoding timestamps or requiring file existence.
   • Configure _config.yml:

     cache_version: v2
     

   • Use in Liquid:

     <script src="{{ '/js/app.js' | filebuster }}"></script>
     

4. Base Path for Links:

   • Use the {{ base }} tag to dynamically generate the root path of the site (useful for multi-level directories or subdirectories).
   • Example:

     <a href="{{ base }}/about">About</a>
     

Integration Tips

• Liquid Templates:

  • Place filters/tags in Liquid templates (e.g., index.html, _layouts/default.html).
  • Test locally with jekyll serve --watch to preview changes.

• Build Automation:

  • Integrate with CI/CD pipelines (e.g., GitHub Actions) to rebuild the site with cache-busted assets on deploy.

• Custom Variables:

  • Extend _config.yml to define reusable variables for filebuster (e.g., js_version, css_version).

Gotchas and Tips

Pitfalls

1. Filter Order Matters:

   • Use cachebuster before relativity to avoid incorrect path concatenation.
   • Example of wrong order:

     {{ '/assets/image.png' | relativity | cachebuster }}  <!-- May break paths -->
     

2. File Existence for cachebuster:

   • cachebuster requires the file to exist to read its modification time. Use filebuster if files don’t exist yet or for non-file-based versions.

3. Jekyll Plugin Directory:

   • Ensure _plugins is in the root of your Jekyll site (not src/_plugins unless configured). Adjust the Composer installer-paths if needed.

4. Ruby Dependencies:

   • The package requires Ruby/Jekyll. Ensure your environment has Jekyll installed (gem install jekyll).

Debugging

• Check Plugin Loading:

  • Run jekyll build --trace to verify the plugin is loaded. Errors here indicate path or dependency issues.

• Test Filters Isolated:

  • Create a test template (e.g., test-filters.html) to validate filters individually:

    {% assign test_path = '/test/path' %}
    Relative: {{ test_path | relativity }}
    Cachebusted: {{ test_path | cachebuster }}
    Filebusted: {{ test_path | filebuster }}
    

• Log Filter Output:

  • Use Jekyll’s debug tag to inspect filter results:

    {{ '/test' | relativity | debug }}
    

Extension Points

1. Custom Filters:

   • Extend the Ruby plugins (e.g., jekyll-site-helpers/lib/jekyll-site-helpers.rb) to add new filters or modify existing ones.
   • Example: Add a minify filter to compress asset paths.

2. Configuration Overrides:

   • Override default behavior by redefining methods in a custom plugin that includes jekyll-site-helpers.

3. Variable Scope:

   • Use filebuster with global _config.yml variables for team-wide consistency:

     cache:
       js: v1.2
       css: v3.0
     

   • Reference in Liquid:

     {{ '/js/app.js' | filebuster: site.cache.js }}
     

Performance Tips

• Cache Busting Strategy:
  • Prefer filebuster for static versions (e.g., v1, v2) over timestamps to reduce rebuild overhead.
• Relative Paths:
  • Cache relativity results in a variable if used repeatedly:

    {% assign relative_path = '/assets/img' | relativity %}
    <img src="{{ relative_path }}/logo.png">