spatie/commonmark-wire-navigate

Add a wire:navigate attribute to links rendered in Markdown

An extension for league/commonmark to add a wire:navigate attribute to links rendered in Markdown and enable SPA mode in Livewire.

Support us

We invest a lot of resources into creating best in class open source packages. You can support us by buying one of our paid products.

We highly appreciate you sending us a postcard from your hometown, mentioning which of our package(s) you are using. You'll find our address on our contact page. We publish all received postcards on our virtual postcard wall.

Installation

You can install the package via composer:

composer require spatie/commonmark-wire-navigate

Usage

Register CommonMarkWireNavigate as a CommonMark extension.

use League\CommonMark\Environment\Environment;
use League\CommonMark\CommonMarkConverter;
use Spatie\CommonMarkWireNavigate\WireNavigateExtension;

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

echo $converter->convert('[About](https://github.com/spatie/commonmark-wire-navigate/blob/HEAD/about)');
// <p><a href="https://github.com/spatie/commonmark-wire-navigate/blob/HEAD/about" wire:navigate>About</a></p>

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

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' => [
    Spatie\CommonMarkWireNavigate\WireNavigateExtension::class,
],

Choosing which links to enhance

By default, the extension will add wire:navigate to all internal links except fragments of the current page. To know which link is internal, you must specify your application's base URL.

$converter = new CommonMarkConverter($environment);
$converter->getEnvironment()->addExtension(new WireNavigateExtension(
    baseUrl: 'https://example.app',
));


echo $converter->convert('[About](https://github.com/spatie/commonmark-wire-navigate/blob/HEAD/about)');
// <p><a href="https://github.com/spatie/commonmark-wire-navigate/blob/HEAD/about" wire:navigate>About</a>

echo $converter->convert('[About](https://example.app/about)');
// <p><a href="https://example.app/about" wire:navigate>About</a>

echo $converter->convert('[Twitter](https://twitter.com/spatie_be)');
// <a href="https://twitter.com/spatie_be">Twitter</a></p>

Additionally, you can configure whether the attribute will be added using an array of patterns or a callback.

Using an array to specify a root path in your application:

$converter = new CommonMarkConverter($environment);
$converter->getEnvironment()->addExtension(new WireNavigateExtension(
    baseUrl: 'https://example.app',
    enabled: ['docs', 'guide'],
));

echo $converter->convert('[Installation](https://github.com/spatie/commonmark-wire-navigate/blob/HEAD/docs/installation)');
// <p><a href="https://github.com/spatie/commonmark-wire-navigate/blob/HEAD/docs/installation" wire:navigate>Installation</a>

echo $converter->convert('[Guide](https://github.com/spatie/commonmark-wire-navigate/blob/HEAD/guide)');
// <p><a href="https://github.com/spatie/commonmark-wire-navigate/blob/HEAD/guide" wire:navigate>Guide</a>

echo $converter->convert('[About](https://github.com/spatie/commonmark-wire-navigate/blob/HEAD/about)');
// <p><a href="https://github.com/spatie/commonmark-wire-navigate/blob/HEAD/about">About</a>

Using a callback:

$converter = new CommonMarkConverter($environment);
$converter->getEnvironment()->addExtension(new WireNavigateExtension(
    baseUrl: 'https://example.app',
    enabled: fn (string $url) => preg_match('/\/docs\//', $url),
    hover: true, 
));

Enable on fragments of the current page:

$converter = new CommonMarkConverter($environment);
$converter->getEnvironment()->addExtension(new WireNavigateExtension(
    fragment: true, 
));

Prefetching pages on hover

If you want to have Livewire prefetch pages when a link is hovered, enable the hover option.

$converter = new CommonMarkConverter($environment);
$converter->getEnvironment()->addExtension(new WireNavigateExtension(
    baseUrl: 'https://example.app',
    hover: true, 
));

Now the extension will add wire:navigate.hover to links instead.

echo $converter->convert('[About](https://github.com/spatie/commonmark-wire-navigate/blob/HEAD/about)');
// <p><a href="https://github.com/spatie/commonmark-wire-navigate/blob/HEAD/about" wire:navigate.hover>About</a></p>

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

• Sebastian De Deyne
• All Contributors

License

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