Weave Code
Commonmark Wire Navigate Laravel Package
spatie/commonmark-wire-navigate
CommonMark extension that adds a wire:navigate attribute to links rendered from Markdown, enabling Livewire SPA navigation. Install via Composer and register WireNavigateExtension in your CommonMark environment or spatie/laravel-markdown config.
Add wire:navigate to links in Markdown files
Frequently asked questions about Commonmark Wire Navigate
- How do I add `wire:navigate` to Markdown links in a Laravel + Livewire project?
- Install the package via Composer, then register the `CommonmarkWireNavigate` extension with your CommonMark parser. For `spatie/laravel-markdown`, add it in `config/markdown.php` under `extensions`. If using raw `league/commonmark`, inject it into your `Environment` before converting Markdown.
- Does this package work with Livewire’s SPA mode only?
- Yes, this package is designed specifically for Livewire’s SPA navigation mode. If your project doesn’t use `wire:navigate` or SPA mode, this package won’t function as intended. Ensure Livewire’s SPA mode is enabled via `Livewire::configureToUseSPAMode()`.
- Can I use this with other CommonMark extensions without conflicts?
- The package follows the standard CommonMark extension pattern, so it should integrate smoothly with other extensions. However, if multiple extensions modify links (e.g., adding attributes), test thoroughly to avoid conflicts like duplicate `wire:navigate` or malformed HTML.
- What Laravel and Livewire versions are supported?
- The package supports Laravel 8.1+ and Livewire projects using SPA mode. It’s compatible with `league/commonmark` v1.0+, which is the default in most Laravel setups. Check the [Livewire docs](https://livewire.laravel.com/docs/navigate) for SPA mode requirements.
- How do I test if `wire:navigate` is correctly applied to Markdown links?
- Render a Markdown link (e.g., `[Test](/test)`) and inspect the output HTML for the `wire:navigate` attribute. Use Livewire’s `wire:navigate` testing utilities or simulate SPA navigation in your tests. Verify behavior with dynamic components by testing links inside conditionally rendered Markdown.
- Will this break existing Markdown processing pipelines?
- No, the package is non-intrusive and designed to slot into existing pipelines. If you’re using `spatie/laravel-markdown`, configure it in the `extensions` array. For custom setups, ensure the extension is added *after* other link-modifying extensions to avoid attribute clashes.
- Are there performance concerns with adding this to every Markdown link?
- The package adds minimal overhead—it only processes links during Markdown conversion. Since it’s a CommonMark extension, the impact is negligible unless you’re rendering thousands of links in a single batch. Benchmark in your specific use case if performance is critical.
- What if I need to exclude certain links (e.g., external URLs) from `wire:navigate`?
- The package applies `wire:navigate` to all links by default. To exclude specific links, pre-process your Markdown or use a custom extension that filters links based on conditions (e.g., URL patterns). Alternatively, manually edit the HTML output post-conversion.
- Does this work with non-Livewire links or fallback for JavaScript-disabled users?
- The `wire:navigate` attribute is client-side only. For accessibility or non-JS users, ensure your links have fallback behavior (e.g., standard HTTP requests). Consider adding a `data-wire-navigate` attribute or testing with JavaScript disabled in your browser.
- Are there alternatives if I’m not using `league/commonmark`?
- This package is built for `league/commonmark`. If you’re using another parser like Parsedown, you’d need to create a custom solution or wrapper to inject `wire:navigate` into links. Check if your parser supports extensions or post-processing HTML.
Weaver
How can I help you explore Laravel packages today?