- How do I integrate league/commonmark with Laravel Blade templates for rendering Markdown?
- Use a custom Blade directive or a wrapper like `aptoma/twig-markdown` to convert Markdown to HTML before rendering. For example, create a Blade component that instantiates `CommonMarkConverter` and processes the input. Ensure you configure `html_input => 'strip'` to prevent XSS risks in user-generated content.
- Does league/commonmark support GitHub-Flavored Markdown (GFM) features like tables and task lists?
- Yes, the package includes `GithubFlavoredMarkdownConverter`, which supports GFM features out of the box. Simply instantiate this converter instead of `CommonMarkConverter` to enable tables, task lists, and other GitHub-specific syntax. Check the [README](https://github.com/thephpleague/commonmark) for full feature compatibility.
- What Laravel versions and PHP requirements does league/commonmark support?
- The package requires PHP 7.4+ (with `mbstring` extension) and works seamlessly with Laravel 8.x, 9.x, and 10.x, as these align with its PHP version support. For older Laravel versions (e.g., 7.x), ensure PHP 7.4+ compatibility is maintained, as the package drops support for earlier PHP versions.
- How can I securely render user-generated Markdown in Laravel to prevent XSS attacks?
- Configure the converter with `html_input => 'strip'` and `allow_unsafe_links => false` to strip unsafe HTML and block dangerous links. For additional security, combine it with HTML Purifier or Laravel’s built-in sanitization. Always validate and sanitize input before rendering, especially in forums or wikis.
- Can I use league/commonmark to store and retrieve Markdown from Eloquent models?
- Yes, store Markdown in database fields (e.g., `description` or `content`) and render it dynamically in views or APIs. Use a service class to instantiate the converter and parse the Markdown on-the-fly. For APIs, return raw Markdown or HTML based on the `Accept` header, using middleware to handle conversion.
- What are the performance implications of parsing large Markdown documents in Laravel?
- The package is optimized for PHP 7.4+, but parsing very large documents (e.g., 10,000+ lines) may impact performance. Benchmark your use case and consider caching parsed Markdown using Laravel’s cache drivers (e.g., Redis) to avoid reprocessing. For static content, pre-render Markdown during deployment.
- How do I add custom extensions (e.g., YouTube embeds or LaTeX) to league/commonmark?
- Use the package’s extension system to add custom functionality. For example, register a `YouTubeEmbedExtension` or `LaTeXExtension` via the converter’s environment. Document dependencies clearly in your `composer.json` and test thoroughly, as third-party extensions may introduce vulnerabilities or compatibility issues.
- Is league/commonmark a drop-in replacement for graham-campbell/laravel-markdown?
- While both packages parse Markdown, `league/commonmark` offers more control and extensibility. You’ll need to replace Laravel-Markdown’s facade or service provider with your own wrapper. The trade-off is greater flexibility for custom use cases, but you’ll lose Laravel-specific conveniences like Blade directives out of the box.
- How do I handle nested Blade directives (e.g., `@if`) inside Markdown content?
- Blade directives won’t parse inside raw Markdown output. To support nested Blade logic, pre-process the Markdown to escape or replace Blade tags, or use a custom Blade component that conditionally renders Markdown. Alternatively, parse Markdown first, then inject Blade logic into the resulting HTML using string manipulation or DOM methods.
- What should I consider when upgrading from league/commonmark v1.x to v2.0+?
- Major version upgrades require migrating from `CommonMarkConverter` to `MarkdownConverter`. Review the [upgrading guide](https://github.com/thephpleague/commonmark/blob/main/UPGRADING.md) for breaking changes, such as renamed classes or configuration options. Plan a phased rollout, testing thoroughly with your existing templates to catch HTML output differences or rendering issues.