Wikilinks Laravel Package

Getting Started

statamic/wikilinks is a Statamic addon that lets content editors write wiki-style [[Entry Title]] links inside Markdown-ish content and have them resolved to real entry URLs at render time.

Version note for 2.2.0: this release's only change is Statamic 6 support. The Composer constraint on statamic/cms was widened (v5 and v6), so:

• New installs on Statamic 6 should require statamic/wikilinks:^2.2 — earlier 2.x tags will not resolve.
• Existing Statamic 5 sites need no code changes; it is a drop-in minor bump.
• If you are mid-upgrade to Statamic 6, bump this addon at the same time as statamic/cms so Composer can solve the dependency graph in one pass.

composer require statamic/wikilinks:^2.2
php artisan vendor:publish --tag=wikilinks-config   # if a config is published

Where to look first:

1. config/wikilinks.php (if published) — the resolution strategy, link target field, and broken-link behaviour all live here.
2. The fieldtype/renderer registration in the addon's service provider — this tells you exactly which fieldtypes get the treatment (usually Markdown and Bard's Markdown sets).
3. vendor/statamic/wikilinks/src — the resolver class is small; read it before assuming how titles are matched.

First use case: create a Markdown field on a collection, add [[My Other Entry]] to a value, save, and view the rendered page. If you see a link, the addon is wired correctly; if you see literal brackets, jump to the Gotchas section.

Implementation Patterns

Editor workflow (the primary use case). Wikilinks are authoring sugar: writers type entry titles, the addon turns them into links without needing the entry's URL. Keep the raw [[...]] text in the stored value — do not pre-process on save. Resolution at render time means renaming an entry's slug silently fixes every inbound link, which is the whole point of the package.

Where to apply it. Restrict wikilink parsing to fields that genuinely need it (a body Markdown field, a Bard set marked as Markdown). Blanket-enabling it across every text field usually produces surprising linkification in summaries, meta descriptions, and SEO fields.

Bard integration. If your Bard sets render Markdown, the addon's transform runs in the same pipeline. Confirm the order: wikilinks must resolve before the Markdown parser converts to HTML, otherwise the brackets arrive already wrapped in a <p> and may not match. Test with a Bard entry that has two adjacent wikilinks.

Antlers/Blade templates. Treat the field like any other Markdown field — {{ body }} in Antlers, {!! $entry->body !!} in Blade. The addon typically augments the fieldtype's rendered value rather than the raw value, so $entry->raw('body') still shows the literal brackets, which is handy for a "what links here" feature.

Programmatic resolution. For sitemaps, exports, or backlink indexes, resolve links outside the template layer by instantiating the resolver against a string and inspecting the matches. This is the cleanest way to build a "referenced by" index without parsing stored content yourself.

Testing. Wikilink behaviour is content-dependent, so write one feature test per rendering path (Markdown field, Bard field, and any custom fieldtype you've extended) and assert on the resulting href, not on the raw string. When you bump to 2.2.0, those tests are your compatibility check — Statamic 6 rewrote parts of the Markdown rendering pipeline, so a passing render test on v5 plus a passing render test on v6 is the only meaningful proof.

Custom resolution. If entry titles are not unique in your site, override the default resolver (via config or a bound implementation) to match on a dedicated wiki_key or slug field. Doing this before editors start using the syntax is far cheaper than cleaning up ambiguous links afterwards.

Gotchas and Tips

• Ambiguous titles. Two entries named "Changelog" make [[Changelog]] non-deterministic — usually first-match-wins in query order, which is not stable across publishes. Enforce unique titles on the target collection, or move to a slug/key-based resolver.
• Case and punctuation. Matching is typically exact-ish on the title as stored. [[my entry]] may not find "My Entry". Agree on a house style with editors, or normalise in a custom resolver.
• Broken links. Decide explicitly what happens when no entry matches: leave the [[...]] visible (good — writers can see the gap) or strip it (bad — the text vanishes silently). Check the config default and set it deliberately. Add a scheduled check that greps stored content for unresolved links.
• Double parsing. If a field is processed both by the addon and by your own text filter (or a Bard set that also runs Markdown), you can get escaped output or nested anchors. One transform per field.
• Cache invalidation. Resolution is usually cached by entry ID/title. Renaming or re-slugging an entry should bust it, but bulk imports via php artisan commands frequently do not fire the events that clear it — run php artisan cache:clear / statamic:stache:clear after scripted imports.
• Multisite. [[Title]] should resolve to the localised version of the entry. Verify on your second site: a link that resolves to the default-locale URL is a common and quiet bug, and it is not covered by Statamic 6 compatibility work.
• Escaping. Show editors how to write a literal [[ (usually \[\[ or a code span) before they hit the problem in a draft.
• Upgrade order. On Statamic 6, bump this addon alongside any other addons that touch Markdown or Bard. A single addon pinned to ^5.0 will fail the whole Composer solve, and the error message points at this package rather than the real culprit.
• Version pinning. Because 2.2.0 is the first Statamic-6-capable tag, pin ^2.2 in composer.json rather than a wildcard — a later 3.x may change the config schema, and wikilink config drift is invisible until content renders wrong.