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.

Warning: This extension evaluates helper calls from the Markdown source. Only use it with trusted content that you control. Don't process user-submitted Markdown with this extension.

Support This Project
Installation
Usage
Testing
Changelog
Contributing
Security Vulnerabilities
Credits
License

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+

Install the package via Composer:

composer require mozex/commonmark-routes

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 on 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>

When the helper is used as both the link text and the URL, the resolved URL appears in both places:

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

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.

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,
],

Changelog

Please see CHANGELOG for more information on what has changed recently.

Contributing

Please see CONTRIBUTING for details.

Security Vulnerabilities

Please review our security policy on how to report security vulnerabilities.

Credits

License

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

mozex / commonmark-routes

Maintainers

Package info

Fund package maintenance!

Statistics

Security