rias/statamic-markdown-highlight
A Statamic addon that adds syntax highlighting to Markdown code blocks, making fenced code in your content easier to read. It integrates with Statamic’s Markdown rendering and supports common programming languages.
1. Confirm it fits before installing. This addon is archived (last release 2023-10-06, ~6 stars, zero dependents). It was built for the Statamic 3/4 era and wraps the PHP port of highlight.js (scrivo/highlight.php). Check the README and composer.json for PHP and statamic/cms constraints against your project before you commit — on Statamic 5/6 or PHP 8.2+ this is the first thing that will bite you.
2. Install.
composer require rias/statamic-markdown-highlight
Statamic addons normally auto-register via extra.statamic in composer.json, so there is usually nothing to do in config/app.php. If it does not appear, manually add the service provider to config/app.php (Statamic 3 style) or check bootstrap/providers.php on Laravel 11+.
3. Look here first.
src/ServiceProvider.php — the source of truth. It tells you whether the addon registers a CommonMark extension, swaps the fenced-code-block renderer, or ships a config.config/statamic-markdown-highlight.php (if present) — publish with php artisan vendor:publish --tag=statamic-markdown-highlight if the README mentions options.config/statamic/markdown.php — where Statamic’s Markdown parser is configured. Confirm your site actually uses the CommonMark parser ('parser' => 'commonmark'); the addon will not touch a custom/legacy parser.4. First use case. Create or edit an entry with a Markdown field containing a fenced code block:
```php
echo "hello";
```
Render it in a template ({{ content | markdown }} or {{ markdown }}) and inspect the HTML. You should see server-rendered highlight.js markup — i.e. <pre><code class="hljs language-php"> with <span class="hljs-keyword">-style wrappers around tokens instead of plain text.
5. Ship the theme CSS yourself. The addon generates highlighting classes; it does not give you a stylesheet. Add a highlight.js theme (CDN, npm import into your Vite bundle, or a hand-rolled hljs-* stylesheet) and load it in your layout. Without it the output looks like ordinary <pre>.
Rely on the standard Markdown render path. The addon works wherever Statamic’s Markdown parser runs — Markdown fieldtypes, {{ text | markdown }} in Antlers, Str::markdown()-style helpers if the extension is registered globally. The practical rule: if the content becomes HTML through Statamic’s Markdown renderer, it gets highlighted; if it bypasses it, it doesn’t.
Keep content authoring plain. Author fenced blocks with an explicit language tag. Authors should not need to add classes or raw HTML — the whole point is that ```php becomes highlighted HTML automatically. Document the supported language identifiers (highlight.js aliases like js, ts, shell, yaml, blade) for your editors so nobody invents ```laravel.
Bring your own theme, ideally via Vite. A typical pattern:
// package.json
"dependencies": { "highlight.js": "^11.x" }
// resources/js/app.js
import 'highlight.js/styles/github-dark.css';
This decouples the pre-rendered markup (server) from the palette (client), so restyling is a CSS change rather than a content re-render.
Static caching / response caching is fine. The output is deterministic for a given input, so it plays nicely with Statamic’s static caching and any full-page cache. No need to disable caching; just clear it after changing the theme CSS asset hashes.
Coexist with Tailwind Typography. Because you control the CSS, you can either use a real highlight.js theme or map hljs-* classes onto your Tailwind palette via @layer. Prefer the latter if you already use prose styling, so code blocks don’t visually clash with the rest of the page.
Graceful migration path if you need more. If the addon’s language set or performance becomes limiting, the same pre-rendered approach is achievable with a maintained CommonMark extension (e.g. a FencedCode renderer backed by scrivo/highlight.php in your own service provider), or with a build-time highlighter (Torchlight/Shiki). Both keep the pre-rendered property; the difference is who owns the extension.
"rias/statamic-markdown-highlight": "x.y.*") and keep it in a throwaway/legacy project rather than on a long-lived site. If you adopt it, budget a replacement.scrivo/highlight.php or the addon itself) and on Statamic 5 (Laravel 11 bootstrap changes). If you get a blank page or unregistered provider, the first check is composer why-not statamic/cms and composer show rias/statamic-markdown-highlight.hljs-* spans, then fix the CSS, not the addon.blade, antlers, statamic may not exist. For those, either map to the closest supported alias (html/php) or accept plaintext rendering — the block still renders, just uncoloured.<pre> in fields will not be highlighted because they never hit the CommonMark fenced-code renderer. If your editors paste code into Bard, this addon won’t help.htmlspecialchars/e() on the raw code first.php artisan about / container), confirm the parser in config/statamic/markdown.php is the one the addon hooks into, then dump the rendered HTML before blaming CSS. If you extend CommonMark yourself elsewhere, check that your custom Environment still registers the addon’s extension — two independently configured Markdown environments is the classic silent failure.composer.json — often the right end state for this package.How can I help you explore Laravel packages today?