README

A league/commonmark extension that lets you use route(), url(), and asset() inside your Markdown content. Write links and images using the same Laravel helpers you already use in Blade, and they'll resolve to real URLs when the Markdown is converted.

Read the full documentation at mozex.dev: searchable docs, version requirements, detailed changelog, and more.

Note: Helper arguments are parsed, not executed. Only literal values get through, so Markdown can't run PHP. See Helper Arguments.

Installation
Upgrading from 1.x
Usage

Support This Project

I maintain this package along with several other open-source PHP packages used by thousands of developers every day.

If my packages save you time or help your business, consider sponsoring my work on GitHub Sponsors. Your support lets me keep these packages updated, respond to issues quickly, and ship new features.

Business sponsors get logo placement in package READMEs. See sponsorship tiers →

Installation

Requires PHP 8.2+ - see all version requirements

Install the package via Composer:

composer require mozex/commonmark-routes

Upgrading from 1.x

Version 1 ran every helper call through PHP's eval(). Any Markdown you converted could execute arbitrary code, which is why the old README told you never to process user-submitted content. Version 2 parses the arguments instead and accepts literal values only.

Ordinary usage is unaffected. route('product', 3), url('docs/api'), and route('home', ['id' => 'features']) all behave exactly as before.

What breaks is anything that isn't a literal:

[Docs](url('docs/' . $section))
[Docs](url(config('app.docs_path')))
[Logo](asset(strtolower('Logo.png')))

Those now throw Mozex\CommonMarkRoutes\Exceptions\InvalidHelperArgumentsException. Work the value out in PHP and pass the finished Markdown to the converter.

Three smaller changes, none of which raise an error, so check your output if any apply:

Link text that mixes prose with a helper keeps the prose now. [Go to route('home') now](route('home')) used to render as <a href="…">https://domain.com</a>, because version 1 replaced the whole text. It now renders as <a href="…">Go to https://domain.com now</a>. Text that was only a helper call, like [route('home')](route('home')), is unaffected.
RoutesExtension no longer implements League\Config\ConfigurationAwareInterface, and setConfiguration() is gone with it. The injected config was never read. This only matters if you subclassed the extension and touched $this->configuration.
Helper calls inside fenced code blocks and inline code used to resolve. They don't any more. If you were relying on that, move the content out of the code block.

Usage

Register the extension with your CommonMark environment, then use route(), url(), or asset() in place of URLs in your Markdown.

use League\CommonMark\CommonMarkConverter;
use Mozex\CommonMarkRoutes\RoutesExtension;

$converter = new CommonMarkConverter();
$converter->getEnvironment()->addExtension(new RoutesExtension());

Links

The route() helper works exactly the way it does in your PHP code. Named routes, parameters, query strings, relative URLs:

echo $converter->convert("[Home](route('home'))");
// <p><a href="https://domain.com">Home</a></p>

echo $converter->convert("[Product](route('product', 3))");
// <p><a href="https://domain.com/product/3">Product</a></p>

echo $converter->convert("[Features](route('home', ['id' => 'features']))");
// <p><a href="https://domain.com?id=features">Features</a></p>

echo $converter->convert("[Home](route('home', absolute: false))");
// <p><a href="/">Home</a></p>

The url() helper generates URLs from plain paths:

echo $converter->convert("[About](url('about'))");
// <p><a href="https://domain.com/about">About</a></p>

echo $converter->convert("[Docs](url('docs/getting-started'))");
// <p><a href="https://domain.com/docs/getting-started">Docs</a></p>

The asset() helper resolves static file paths through Laravel's asset pipeline. This is especially useful in environments like Laravel Vapor where assets are served from S3 or CloudFront and relative paths won't work:

echo $converter->convert("[Download PDF](asset('files/doc.pdf'))");
// <p><a href="https://domain.com/files/doc.pdf">Download PDF</a></p>

Helpers resolve in the link text too, wherever they appear:

echo $converter->convert("[route('home')](route('home'))");
// <p><a href="https://domain.com">https://domain.com</a></p>

echo $converter->convert("[Go to route('home') now](route('home'))");
// <p><a href="https://domain.com">Go to https://domain.com now</a></p>

Angle brackets work too, which can help with complex arguments:

echo $converter->convert("[Home](<route('home', absolute: false)>)");
// <p><a href="/">Home</a></p>

You can freely mix helpers with regular Markdown links in the same document:

echo $converter->convert("[Home](route('home')) | [Docs](url('docs')) | [Google](https://google.com)");
// <p><a href="https://domain.com">Home</a> | <a href="https://domain.com/docs">Docs</a> | <a href="https://google.com">Google</a></p>

Link Titles

Titles survive the rewrite. All three CommonMark forms work, on links and images alike:

echo $converter->convert("[Home](route('home') \"Go home\")");
// <p><a href="https://domain.com" title="Go home">Home</a></p>

echo $converter->convert("![Logo](asset('logo.png') 'Our logo')");
// <p><img src="https://domain.com/logo.png" alt="Logo" title="Our logo" /></p>

Images

Image syntax works the same way. Put a helper inside ![alt](...) and it resolves just like links do:

echo $converter->convert("![Logo](asset('images/logo.png'))");
// <p><img src="https://domain.com/images/logo.png" alt="Logo" /></p>

echo $converter->convert("![Banner](url('images/banner.jpg'))");
// <p><img src="https://domain.com/images/banner.jpg" alt="Banner" /></p>

echo $converter->convert("![Product](route('product', 3))");
// <p><img src="https://domain.com/product/3" alt="Product" /></p>

The asset() helper is the most common choice for images. If you're on Vapor or any setup that serves assets from a CDN, asset() gives you the correct absolute URL instead of a broken relative path.

Regular images without helpers pass through untouched:

echo $converter->convert("![Photo](https://example.com/photo.jpg)");
// <p><img src="https://example.com/photo.jpg" alt="Photo" /></p>

For more details on CommonMark extensions and environments, check the CommonMark documentation.

Helper Arguments

Write arguments the way you'd write them in PHP. These are the values the parser accepts:

Strings, single or double quoted: route('product'), url("about")
Integers and floats: route('product', 3)
Booleans and null: route('home', [], false)
Arrays, including nested ones: route('search', ['filters' => ['tag' => 'php']])
Named arguments: route('home', absolute: false)

Double-quoted strings don't interpolate. url("costs/$100") gives you a literal $100 in the path.

Anything else throws Mozex\CommonMarkRoutes\Exceptions\InvalidHelperArgumentsException with the offending source in the message. That covers variables, function calls, concatenation, and constants. It's what stops Markdown from reaching PHP.

Code Blocks

Helpers inside fenced code blocks and inline code are left alone, so you can document the syntax without it resolving on you:

```php
[Home](route('home'))
```

Inline `[Home](route('home'))` stays put too.

Both render as literal text. This README goes through the extension unchanged.

One gap worth knowing about: indented code blocks (the four-space kind) aren't protected. Telling them apart from nested list content needs a full block parse, and guessing wrong would silently break links inside lists. Use fenced blocks when the content has helper calls in it.

Spatie Laravel Markdown

If you're using the Laravel Markdown package by Spatie, register the extension in config/markdown.php:

/*
 * These extensions should be added to the markdown environment. A valid
 * extension implements League\CommonMark\Extension\ExtensionInterface
 *
 * More info: https://commonmark.thephpleague.com/2.4/extensions/overview/
 */
'extensions' => [
    Mozex\CommonMarkRoutes\RoutesExtension::class,
],

Resources

Visit the documentation site for searchable docs, auto-updated from this repository.

AI Integration: Use this package with AI coding assistants via Context7 and Laravel Boost
Requirements: PHP, Laravel, and dependency versions
Changelog: Release history with linked pull requests and diffs
Contributing: Development setup, code quality, and PR guidelines
Questions & Issues: Bug reports, feature requests, and help
Security: Report vulnerabilities directly via email

License

The MIT License (MIT). Please see License File for more information.

mozex / commonmark-routes

Maintainers

Package info

Fund package maintenance!

Statistics

Security