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.

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.

Table of Contents

• Installation
• Usage
  • Links
  • Images
  • Spatie Laravel Markdown

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

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>

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

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.