Statamic Markdown Highlight Laravel Package

Technical Evaluation

What it actually is. Despite being catalogued as a Laravel/PHP package, this is a Statamic add-on, not a framework-level library. Its entire value is realized inside a Statamic site's Markdown rendering pipeline: fenced code blocks are converted to pre-highlighted HTML server-side using highlight.js, so the browser receives finished markup with no client-side highlighting JavaScript. In a plain Laravel application the package is inert — it registers a Statamic service provider and hooks the Markdown parser, so there is no fit unless Statamic is the CMS.

Architecture fit. Conceptually clean. Server-side highlighting removes a runtime JS dependency, eliminates FOUC on code blocks, improves LCP on documentation-heavy pages, and is compatible with a strict CSP (no inline scripts, no CDN). It also composes naturally with Statamic's static caching, since output is deterministic per entry. The architectural question is where in the lifecycle highlighting happens — on save, on render, or on cache warm — because that determines cache invalidation strategy and publish latency.

Integration feasibility. Low effort to evaluate, high effort to trust. Installation is a composer require plus auto-discovered provider; a spike should take under a day. The blockers are not integration mechanics but provenance: the repository is archived, the last release is October 2023 (predating Statamic 5 and Laravel 11), it has 6 stars and 0 dependents, and it is a single-maintainer project. There is no field validation of any kind, and no upgrade path.

Technical risk.

• Lifecycle risk (high). Archived means no PHP/Laravel/Statamic version bumps, no security patches, and no fixes for highlight.js grammar CVEs.
• Compatibility risk (high). A 2023 Statamic add-on almost certainly targets Statamic 3/4 and PHP 8.1/8.2; boot failures on Statamic 5 are the likely default outcome.
• Security risk (medium). Highlighting untrusted author-supplied Markdown requires rigorous HTML escaping inside <pre><code>. Any escaping gap is stored XSS in rendered entry content.
• Supply-chain risk (medium). If highlighting shells out to a Node binary or bundles a pinned grammar set, container images and CI need matching runtimes — an easy source of "works locally, fails in prod."

Key questions for the spike.

1. Which highlight.js binding is used — pure-PHP port, bundled JS, or Node subprocess — and what does that imply for the deploy image?
2. Is highlighting performed at save time, request time, or static-cache warm, and how is it invalidated on edit?
3. Does the renderer escape HTML within code fences, and does it strip raw HTML in Markdown generally?
4. Does the provider boot cleanly on our exact Statamic/Laravel/PHP matrix?
5. Do we actually need server-side highlighting, or would maintained client-side highlight.js/Shiki meet the requirement with less ownership?

Integration Approach

Stack fit. Adopt only under a narrow condition: Statamic CMS, authors writing fenced code blocks, and a hard requirement for no-JS or CSP-strict rendering. If any of those is false, stop — the package adds ownership cost with no benefit.

Do not take a direct dependency on an archived artifact. Pin-and-hope is the wrong posture for a package with zero dependents and no maintainer. Two acceptable paths:

• Fork-and-own: mirror the source into an internal VCS or path repository under a first-party namespace, pin the highlight.js grammar set, and treat it as internally maintained code.
• Reimplement: a CommonMark extension wrapping a maintained highlighter (pure-PHP highlight.php, Torchlight/Shiki at build time, or client-side highlight.js) is on the order of a few hundred lines and gives us a supportable surface.

Migration path. (1) Branch spike with the existing add-on to capture current output; (2) run a compatibility matrix against our Statamic, Laravel, and PHP versions plus the container image; (3) if green, fork and pin; (4) if red, reimplement the renderer behind the same HTML contract so templates and CSS themes are unchanged; (5) roll out behind a feature flag with a static-cache purge.

Compatibility. Explicitly verify PHP 8.2/8.3, Laravel 10/11/12, and Statamic 4/5. Assume the 2023 release fails the matrix until proven otherwise; budget the spike to fail fast.

Sequencing. Audit existing content for code-block volume and language coverage → define the output contract (HTML structure, CSS class scheme, theme asset) → decide render-time vs. save-time → implement/fork → snapshot-test rendered HTML → migrate templates → decommission the original dependency.

Recommendation. Treat this as a reference implementation to read, not a package to install. The pre-rendered-Highlight.js approach is sound; the artifact is not maintainable.

Operational Impact

Maintenance. Ownership transfers to us entirely. Ongoing work is modest but real: grammar updates for new languages, highlight.js security patches, and re-validation on every Statamic major upgrade. Estimate a few days per upgrade cycle; near-zero in steady state.

Support. No upstream, no issue tracker activity, no community to escalate to. Requires a named internal owner, a short design note explaining the fork, and a documented decision record so a future maintainer understands why the code is vendored.

Scaling. Strong on the delivery side: pre-rendered HTML means no client JS bundle, no runtime CPU on the reader's device, better LCP on documentation pages, and clean interaction with static caching and CDNs. The cost shifts to write/render time — watch re-render expense on large entry sets, static-cache warm duration during redeploys, and memory if grammar sets are loaded eagerly per request.

Failure modes.

• Escaping regression → stored XSS in published content (highest severity).
• Missing grammar → silently unstyled code block, visible to readers, invisible to monitoring.
• Statamic upgrade → service provider boot error or unhighlighted output sitewide.
• Node/runtime drift → build or render failures only in CI or production.
• Pinned highlighter → new languages adopted by authors render plain, eroding trust in the feature.

Ramp-up. A Laravel developer can understand the add-on in an afternoon; the fork, compatibility matrix, escaping review, and rollout plan are roughly a one-week risk burn-down. Plan for that explicitly rather than treating this as a drop-in dependency — the low star count and archived status mean the package's real cost is ownership, not integration.