Torchlight Commonmark Laravel Package

Getting Started

Start by installing the package and its Laravel client dependency via Composer:

composer require torchlight/torchlight-commonmark

Next, publish the configuration with:

php artisan torchlight:install

This generates config/torchlight.php, where you configure your Torchlight API token (free for personal/open-source projects), default theme, and cache driver. Then, register the extension — if using graham-campbell/laravel-markdown, add it to config/markdown.php:

'extensions' => [
    Torchlight\Commonmark\V2\TorchlightExtension::class,
],

For raw CommonMark usage, inject the versioned extension when building the environment:

$environment = new Environment(['extensions' => [
    new \CommonMark\Extension\CoreExtensions(),
    new \Torchlight\Commonmark\V2\TorchlightExtension(),
]]);

Any fenced code block (```) in parsed Markdown is now automatically syntax-highlighted — no view changes needed.

Implementation Patterns

• Per-block theming: Override the global theme per code fence inline using theme:name:

  ```php theme:material-theme-palenight
  echo "Custom theme for this block!";
  ```
  

• File embedding: Pull in live code from your project with <<< syntax — ideal for keeping docs in sync with source:

  ```php <<<app/Services/PaymentService.php
  ```
  
  // Also supports comment-wrapped form:
  // ```php
  // // <<<app/Services/PaymentService.php
  // ```
  

• Dark/light mode: Use config/torchlight.php to define multiple themes (themes.dark, themes.light), then apply via custom rendering or CSS to toggle contexts. Torchlight respects data-theme attributes if present.

• Blade integration: With Laravel Markdown, use @markdown or @markdownify() — Torchlight automatically enhances code blocks. Disable blade_components only if building highly custom UIs.

• Caching: Set cache.driver to redis/file. Consider pre-warming cache in CI/CD (php artisan view:clear && php artisan view:cache) for production, and use Torchlight::flushCache() after theme/token updates.

• Diff highlighting: Torchlight auto-detects +/- prefixes and applies diff colors — perfect for changelogs:

  ```diff
  - $old = 1;
  + $new = 2;
  ```
  

Gotchas and Tips

• Use versioned extensions: The unnamespaced TorchlightExtension is deprecated — always use \Torchlight\Commonmark\V2\TorchlightExtension (or V1 if stuck on CommonMark 1.x). Forgetting this causes silent failures or errors in v0.5.0+.

• Only fenced blocks get highlighted: Indented code (e.g., 4-space leading) won’t be processed — ensure your Markdown uses backtick fences.

• API latency: First parse in a request may be slower due to remote API call. Always warm cache in deployments and use Redis for shared caching in multi-server envs.

• Theme switching ≠ dynamic caching: Switching themes at runtime (e.g., per-user preference) won’t auto invalidate the cache. Either flush cache on context change or use a per-context key in custom logic.

• Custom rendering hook: Override rendering pipeline with useCustomBlockRenderer() (e.g., wrap in <div class="code-wrapper">) — useful for analytics, copy buttons, or analytics.

• Testing gotcha: Don’t hit the real API in tests. Set TORCHLIGHT_HOST=http://localhost:9999 in phpunit.xml, or mock Torchlight::highlight() and return a cached fixture.

• Attribute forwarding: Torchlight returns attributes like data-lang; if your HTML looks unstyled, verify they’re being rendered (e.g., {{ $block->data-lang }} in custom renderer).

• Cache key nuance: Keys include lang, theme, and file_hash. If you change a theme without modifying code, cache won’t invalidate — use Torchlight::flushCache() or append ?cache-bust=1 during theme rollout.