Commonmark Shiki Highlighter Laravel Package

Product Decisions This Supports

• Enhancing Developer Documentation & Markdown Support: Integrate high-quality syntax highlighting into internal wikis, API docs, or developer portals (e.g., Swagger/OpenAPI Markdown, READMEs) to improve readability and reduce onboarding friction.
• Roadmap for Content Platforms: Accelerate development of a Markdown-based CMS or knowledge base by leveraging Shiki’s 100+ languages (plus Blade/Antlers) without reinventing syntax highlighting. Aligns with trends like content-as-code (e.g., Next.js, Docusaurus).
• Build vs. Buy: Buy: Avoid building a custom syntax highlighter (time/maint cost) or licensing a proprietary tool (e.g., Prism.js). This package is MIT-licensed and integrates natively with Laravel’s ecosystem. Build: Only if needing unique theming or language support beyond Shiki’s scope (e.g., proprietary DSLs).
• Use Cases:
  • Internal Tools: Highlight code snippets in Laravel Nova customizations or Laravel Forge docs.
  • Customer-Facing: Syntax-highlighted tutorials, error messages, or template examples (e.g., for a SaaS product).
  • Legacy Migration: Modernize old PHP/Markdown docs with consistent, performant highlighting.

When to Consider This Package

• Adopt If:
  • Your stack uses Laravel + league/commonmark (or plans to).
  • You need zero-config syntax highlighting for 100+ languages (including Blade/Antlers).
  • Your team prioritizes developer experience (e.g., docs, tutorials) over customization.
  • You want to avoid JavaScript dependencies (Shiki PHP is server-side).
• Look Elsewhere If:
  • You’re not using Laravel (though the core package works with any PHP/CommonMark setup).
  • You need client-side interactivity (e.g., copy-to-clipboard) → Pair with Alpine.js or Laravel Livewire.
  • Your use case requires dynamic language detection or real-time collaboration (e.g., VS Code-like editors) → Consider Monaco Editor or CodeMirror.
  • You’re highlighting non-code content (e.g., regex, SQL) with niche needs → Evaluate Prism.js or Highlight.js.

How to Pitch It (Stakeholders)

For Executives: *"This package lets us deliver polished, professional documentation with minimal effort. By integrating Shiki’s syntax highlighting into our Laravel-based Markdown tools, we can:

• Reduce dev onboarding time by 30% with clearer code examples.
• Cut maintenance costs by avoiding custom highlighter development.
• Future-proof our content with support for 100+ languages out of the box. It’s a low-risk, high-impact upgrade—think of it as ‘Google Fonts for code.’"*

For Engineering: *"Spatie’s package wraps Shiki PHP (a battle-tested highlighter) into a CommonMark block renderer, so we get:

• Server-side rendering: No client-side JS bloat.
• Blade/Antlers support: Critical for Laravel templates.
• Laravel-first integration: Works seamlessly with spatie/laravel-markdown. Tradeoff: Minimal theming control (uses Shiki’s defaults), but we can extend it later if needed. Time to implement: 1–2 dev days for basic setup."*