Pug Filter Markdown Laravel Package

Getting Started

• Install with Composer and let Laravel auto-discovery register the service provider. Publish the package config if you need to change the view extension, cache path, or Pug-php options:

  composer require <vendor>/<package>
  php artisan vendor:publish --tag=pug-config
  

• Look first at config/pug.php (or the package’s published config) for:
  • the view file extension (commonly .pug)
  • compilation/cache settings
  • Pug-php options such as pretty, extension, and custom keywords/filters
• Create a first view at resources/views/welcome.pug and return it like any Laravel view:

  Route::get('/', fn () => view('welcome', ['name' => 'Taylor']));
  

  doctype html
  html
    body
      h1 Hello #{name}
  

• First use case: convert one small Blade partial or layout to Pug and render it alongside existing Blade views. This validates the view engine registration, cache behavior, and your team’s comfort with indentation-sensitive syntax before migrating larger sections.
• Version 1.2.0 adds Pug-php 3 compatibility. On upgrade, verify your pug-php/pug dependency constraint resolves to ^3.0 and that your PHP version meets Pug-php 3’s requirements.

Implementation Patterns

• Mixed view engines: Keep existing .blade.php views and introduce .pug views incrementally. Laravel resolves views by extension, so both can coexist. This is the lowest-risk migration path.
• Layouts and partials: Use Pug’s native inheritance and includes rather than Blade directives:

  //- resources/views/layouts/app.pug
  doctype html
  html
    body
      block content
  
  //- resources/views/dashboard.pug
  extends layouts/app
  block content
    h1 Dashboard
    include partials/nav
  

• Data passing: Use the same view('name', $data) API as Blade. In Pug, #{value} escapes output and !{value} renders unescaped HTML. Prefer #{} for user-supplied data.
• Reusable components: Use Pug mixins for repeated UI fragments:

  mixin button(label, variant='primary')
    button(class=`btn btn-${variant}`)= label
  
  +button('Save')
  +button('Cancel', 'secondary')
  

• Local vs production rendering: Enable pretty output in local development for readable HTML, and enable compiled-template caching in production. Clear caches during deployment.
• Testing: Rendered Pug output is normal HTML, so Laravel HTTP tests and assertSee() continue to work without special handling.
• Integration boundary: Use Pug for HTML views. Keep Blade for parts of Laravel that depend heavily on Blade directives—mail templates, notification markdown, and packages that publish Blade-only views—unless you deliberately port those views.

Gotchas and Tips

• Pug-php 3 upgrade: 1.2.0 is a minor package release, but the Pug-php 3 dependency may introduce behavior changes. Re-test custom keywords, filters, and any code that calls Pug-php APIs directly. Pin compatible versions in composer.json and run the full test suite after upgrading.
• Indentation is syntax: Mixed tabs and spaces, or inconsistent indentation, cause confusing compile errors. Enforce an editor config for .pug files.
• Escaping mistakes: !{} does not escape output. Avoid it with user data; use #{} or explicit sanitization.
• Blade directives do not work inside Pug: @csrf, @if, @foreach, and similar Blade constructs are not processed in .pug views. Use Pug conditionals/loops or the PHP expressions supported by Pug-php. For CSRF fields, render the token through view data or a custom Pug helper/filter.
• Stale compiled templates: Pug-php compiles and caches templates. After config changes, dependency upgrades, or deployments, run:

  php artisan view:clear
  

  If errors reference generated PHP rather than your .pug file, inspect the compiled cache.
• Extension mismatch: If views return “not found,” confirm the configured Pug extension matches your filenames and that Laravel’s view finder is checking the expected paths.
• Debugging compile errors: Enable pretty output locally and check the package’s error reporting. Pug compile errors often include line numbers, but nested includes can shift the reported location.
• Extension points: Custom Pug keywords/filters are the cleanest way to expose Laravel-specific helpers to templates. Register them through the package config or a service provider, and verify they still work under Pug-php 3 before relying on them broadly.
• Cache in CI/CD: Ensure deployment scripts clear compiled views and that the storage view cache directory is writable by the web server.