GrahamCampbell/Laravel-Markdown for Laravel 10 to 13

Laravel-specific CommonMark integration

GrahamCampbell/Laravel-Markdown is a wrapper around the PHP CommonMark library from The League of CommonMark. It addresses a specific Laravel application problem: applications need a Markdown parser, but they also need that parser to participate in Laravel's service container, configuration system and view layer. The package targets Laravel developers rather than users looking for a standalone command-line Markdown converter.

The current version supports Laravel 10, 11, 12 and 13. Its stated PHP requirement is PHP 8.1 through 8.5. That support matrix is a concrete adoption constraint. A Laravel application on an older framework generation cannot use the current release as documented, even though the compatibility table lists older package versions for older Laravel releases.

The package does not replace Laravel Blade or introduce an unrelated template language. It extends Laravel's existing rendering model with Markdown views, a Blade directive and configurable CommonMark extensions. This makes it most relevant to applications that already depend on Laravel and need to author documentation, help content, stored articles or other prose as Markdown.

The project also provides a facade for accessing its Laravel-facing API. That choice is convenient in an application that favors facades, but applications using dependency injection can still work with registered services. The README centers the package on framework integration rather than syntax that differs from CommonMark.

Markdown views and Laravel view registration

The principal mechanism is Laravel view integration. When the `views` option is enabled, the package recognizes `.md`, `.md.php` and `.md.blade.php` files. It also registers the `@markdown` Blade directive. The README does not provide a complete input-and-render example for the directive, so the exact Blade invocation should be confirmed against the README or the installed package files before an application relies on a particular syntax.

View integration defaults to `true`. Enabling it means Laravel applications can place Markdown content alongside their existing view files instead of passing every document through a separately constructed converter. The Blade-based extension retains access to Laravel's view conventions while the parser performs CommonMark conversion.

This integration is optional. The README says that it can be disabled if it conflicts with another package. That makes the project usable as a Laravel service wrapper even when another package owns Markdown file resolution or Blade directive registration. The trade-off is that applications disabling `views` will not receive the documented Markdown filename extensions or `@markdown` directive.

Automatic package discovery may register the service provider. If an application does not use discovery, the README requires manual registration of `GrahamCampbell\Markdown\MarkdownServiceProvider` in `config/app.php`. This is a normal Laravel packaging boundary rather than a separate initialization script.

CommonMark extension and service-container flow

CommonMark extensions are not presented as an isolated list of parser switches. The `extensions` configuration accepts extension class names, and the README states that those classes are resolved through Laravel's service container before being registered with CommonMark. A custom extension can therefore participate in Laravel dependency resolution rather than requiring application code to construct every parser component manually.

The default extension list contains `League\CommonMark\Extension\CommonMark\CommonMarkCoreExtension` and `League\CommonMark\Extension\Table\TableExtension`. Applications that need another League extension can add its class name under the same setting. The README does not explain extension-specific installation requirements or provide examples for a third-party extension, so those details must come from the extension's own documentation.

Renderer and parser behavior are split across separate configuration groups. `renderer` contains HTML rendering options, while `commonmark` contains parsing choices such as emphasis, strong emphasis, marker characters and unordered-list markers. This reflects the wrapper's two-layer model: League CommonMark handles the document model and rendering rules, while Laravel Markdown controls how those components are configured and exposed.

That separation is useful when diagnosing configuration. A change to `use_asterisk`, `use_underscore` or `unordered_list_markers` belongs to CommonMark parsing behavior. A change to `block_separator`, `inner_separator` or `soft_break` belongs to renderer output. Treating these arrays as one option would make expected markup harder to reason about.

Installing Laravel Markdown 16.1 with Composer

Install version 16.1 through Composer. The README states that this release requires PHP 8.1 through 8.5 and supports Laravel 10 through 13, so both constraints should be checked before adding the dependency.

Run this command from the Laravel project:

$ composer require "graham-campbell/markdown:^16.1"

Composer should select a release allowed by the `^16.1` constraint. If automatic package discovery is disabled, register `GrahamCampbell\Markdown\MarkdownServiceProvider` in `config/app.php` as described in the README.

An optional facade alias can be added under the application's alias configuration. The README gives this entry:

        'Markdown' => GrahamCampbell\Markdown\Facades\Markdown::class,

The alias is not required. It shows that a Laravel application may access the package through `GrahamCampbell\Markdown\Facades\Markdown`, while service injection remains available to components that prefer constructor-based dependencies.

The README does not document a post-install cache-clearing command specific to this package. The installation sequence it provides ends with Composer installation and, when necessary, provider or facade registration.

Publishing config/markdown.php for a first Markdown view

The first application setup step is publishing the package configuration. Run Laravel's vendor publishing command:

$ php artisan vendor:publish

According to the README, this creates `config/markdown.php`. The published file exposes view integration, CommonMark extension classes, renderer settings, parsing behavior, HTML input policy, link policy and block nesting limits.

A practical first use starts with leaving view integration enabled, since `views` already defaults to `true`. Create a Laravel view using one of the supported `.md`, `.md.php` or `.md.blade.php` extensions, then render it through Laravel's normal view mechanism. The README does not include a concrete Blade expression showing the exact view call, so the tutorial does not invent one.

The same integration enables the `@markdown` Blade directive. Its availability is documented, but the README excerpt does not show a complete directive example with input and expected output. Confirm its invocation in the installed package documentation before writing production templates around it.

If another package modifies Laravel's Markdown or Blade handling, disable view integration through the `views` setting. That boundary lets the application retain the wrapper's CommonMark configuration without claiming the three documented Markdown view extensions.

HTML input, link filtering and nesting defaults

The security-related defaults deserve direct attention. The `html_input` option defaults to `strip`, so HTML embedded in Markdown input is stripped rather than accepted as normal document markup. That setting is relevant whenever Markdown comes from editors, comments, imported files or other users. The README does not enumerate every alternative value accepted for this option, so applications should not infer behavior beyond the documented default.

The `allow_unsafe_links` option has a less restrictive documented default. It is `true`, and the README describes the setting as controlling whether risky image URLs and links are allowed. Applications accepting untrusted Markdown should review this value against their content policy rather than assuming that stripped HTML makes every link or image URL acceptable.

The `max_nesting_level` option defaults to `PHP_INT_MAX`. The README does not establish a finite default ceiling for block nesting. Resource controls are consequently not presented as a bounded default in this configuration. This does not establish a specific denial-of-service outcome, but it does mean applications requiring a fixed nesting boundary must configure one rather than relying on a documented finite default.

Parser defaults enable emphasis and strong emphasis, allow both asterisk and underscore forms, and recognize `-`, `+` and `*` for unordered lists. Renderer defaults use a newline for `block_separator`, `inner_separator` and `soft_break`. Teams that compare generated HTML should account for these documented defaults before attributing formatting differences to Laravel Markdown itself.

Framework upgrades and configuration maintenance cost

Version 16.1 is not a drop-in choice for every Laravel application. The README associates Markdown 16.1 with Laravel 10, 11, 12 and 13, while the stated PHP range is 8.1 through 8.5. An application must satisfy both requirements. Older Laravel or PHP constraints belong on an earlier package line rather than the current release.

The repository's recent release list contains v16.1.0 from 2026-03-19, v16.0.0 from 2025-03-02 and v15.3.0 from 2025-03-02. This indicates separate major-version transitions around Laravel support. The README does not provide migration procedures, `CHANGELOG.md` contents or package-specific upgrade commands, so the exact work required to move between those lines cannot be determined from the installation page alone.

The README does instruct users to check for changes to the package's original config file between releases. After `php artisan vendor:publish`, a local `config/markdown.php` can therefore differ from the config expected by a newer package version. Applications with local changes need to compare the vendor configuration rather than assuming that a dependency update will merge every setting automatically.

The repository is not archived, and its last push was on 2026-05-06. The MIT License applies according to the repository metadata and README. This article does not interpret license obligations; the repository's `LICENSE` file is the source to review for the exact terms.

Direct CommonMark versus the Laravel wrapper

The closest alternative is The League of CommonMark used directly. Both approaches can parse CommonMark and produce HTML, but their integration boundaries differ. Laravel Markdown registers behavior through Laravel configuration and service-container resolution, adds Markdown view extensions and exposes the `@markdown` Blade directive.

Direct CommonMark use is the better fit when rendering does not need Laravel's view conventions, when code must run outside Laravel, or when an application already manages parser and renderer instances explicitly. It avoids the extra Laravel-specific layer, although it does not mean the wrapper uses a different Markdown syntax. The underlying parser remains part of GrahamCampbell/Laravel-Markdown.

Laravel Markdown is more relevant when Markdown is one format among Laravel views and configuration must be exposed through `config/markdown.php`. That integration reduces the need to wire parser components into each Laravel consumer, but it adds framework and PHP version constraints. It also makes view registration part of the package's behavioral surface.

For application code that only needs conversion in a PHP library or worker process, direct CommonMark offers a narrower dependency. For Laravel templates, documentation views and Blade directives, the wrapper addresses problems that the lower-level library does not automatically solve.

Editorial conclusion

Laravel applications on PHP 8.1 through 8.5 and Laravel 10 through 13 that want Markdown views, the @markdown directive and Laravel service-container integration should evaluate version 16.1. Applications needing an older Laravel release, a different PHP range or rendering outside Laravel should use The League of CommonMark directly. Before adoption, inspect config/markdown.php after publishing, especially html_input and allow_unsafe_links, because their defaults affect how untrusted input is handled. The repository is not archived, its last push was on 2026-05-06, and its current release line requires Laravel 10 or later.

Frequently asked questions

Official sources

1. GrahamCampbell/Laravel-Markdown on GitHub
2. License: MIT
3. Project website
4. README
5. Releases