README

An extension for league/commonmark that allows you to use Laravel routes inside markdown, just as you would in your PHP code.

Warning: This extension is intended for use in controlled environments where the markdown is trusted. Do not use this extension for processing user-input markdown due to potential security risks.

Table of Contents

• Support This Project
• Installation
• Usage
  • Basic Usage
  • Spatie Laravel Markdown
• 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+

You can install the package via composer:

composer require mozex/commonmark-routes

Usage

Register RoutesExtension as a CommonMark extension and use the route function instead of URLs in your markdown, just as you would in your PHP code.

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

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

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

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

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

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

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

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

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

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

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

For more information on CommonMark extensions and environments, refer to the CommonMark documentation.

Spatie Laravel Markdown

When using the Laravel Markdown package, you may 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,
],

Testing

composer test

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

• Mozex
• All Contributors

License

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