Statamic Backlinks Laravel Package

Getting Started

This is a Statamic addon (Antlers tags, CP sidebar, please commands) that runs inside a Laravel app — so treat it as a Laravel package with a Statamic-shaped surface area. The install path is standard, but the value only shows up once the index exists.

1. composer require the addon, then publish its config: php artisan vendor:publish --tag="<addon>-config" (check php artisan vendor:publish output for the exact tag).
2. Read the published config file top to bottom before anything else — it is the whole map of the addon: which collections are scanned, which field handles are parsed for [[...]] syntax, and the CSS class names for existing vs. missing links.
3. Enable wiki-links on one collection and one field handle to start. Do not turn it on globally on day one; parsing cost and index size scale with the number of entries × fields you opt in.
4. Write [[Some Other Entry]] into an entry's markdown/textarea field, save, and render it through the modifier:

{{ content | wiki_links }}

5. Open the entry in the CP and confirm the sidebar shows the backlinks panel. Then run the rebuild command once so you're not debugging against an empty index:

php please backlinks:rebuild

First real use case: a small internal knowledge base or docs collection where 10–50 entries cross-reference each other. That's the size where the missing-link styling (red-link behaviour, MediaWiki-style) is genuinely useful for spotting content gaps rather than just noise.

Implementation Patterns

Rendering. The wiki_links modifier is the workhorse — every place you output a field that can contain wiki-links needs it. That means more than the main content field: teasers, search results, RSS feeds, meta descriptions. Grep your templates for the field handles you enabled and add the modifier deliberately rather than assuming it's global.

Order of modifiers matters. Decide whether wiki_links runs before or after your Markdown modifier, and be consistent across templates. Doing the conversion on raw text and then passing through Markdown is usually the safer order, since it keeps the anchor markup inside the Markdown parse rather than depending on your Markdown config allowing raw HTML through.

Backlinks tag. The backlinks Antlers tag is for anywhere other than the CP sidebar — related-content blocks, "referenced by" footers, entry-level SEO/sitemap context:

{{ backlinks }}
    <a href="{{ url }}">{{ title }}</a>
{{ /backlinks }}

Wrap it in an emptiness check; most entries in a young site have zero backlinks and you don't want an empty <h3>Referenced by</h3> in the markup.

Page creation from missing links is the highest-leverage workflow here, and also the one that needs a policy decision. Authors can click a missing link and get a stub entry. Decide up front: which collection do stubs land in, what's their published state (draft is the sane default), and who is allowed to do it. If your content team is large, wire this to Statamic permissions rather than leaving it open to anyone with CP access — otherwise you get a sprawl of half-titled stubs.

Rebuild as a deployment step, not a request-time operation. The index is derived data, so treat backlinks:rebuild like a cache warm. Hook it into your deploy script (Envoyer/Forge deploy hooks, or a Laravel post-deploy command) and run it after content imports or bulk edits. If the collection is large, run it in a queue job or a scheduled task off-peak rather than blocking the deploy.

Widget. The dashboard widget is zero-config past registration — but if you have multiple user roles, remember dashboards are per-user-editable in Statamic, so "everyone sees backlink activity" is not automatic. Add it to the default dashboard config if you want it to be a shared signal rather than opt-in.

Theming. Point the configurable CSS classes at your existing design tokens instead of shipping the addon's defaults into a Tailwind build you'll then have to purge-match. Missing-link styling in particular should be visually distinct but not alarming — it's a to-do, not an error.

Gotchas and Tips

• The index is derived and will drift. Bulk imports, programmatic entry creation via the REST API or Artisan, entry renames, and anything that writes entries without firing the normal save events will leave stale backlinks. When a link "should" work and doesn't, run the rebuild before you read a single line of code.
• Title-based resolution is brittle by design. [[Page Title]] resolves against the entry's title, so a rename silently converts every inbound link into a missing link. That's the feature working as intended — but it means renames need a migration plan (alias/redirect entries, or sweep the referrers). Consider a naming convention or an internal style guide for titles so renames are rare.
• Cache invalidation. If you use Statamic's static caching or a response cache, a rebuild does not flush it. The two-step is: rebuild index, then clear/warm the cache. Order matters.
• Config caching quirk. Changing collection or field handles in the config requires clearing Laravel's config cache in any environment running config:cache. This bites in production where the config was cached during deploy but the addon config was edited afterwards.
• Escaping on |Display Text. The display-text half of [[Page Title|Display Text]] comes from content authors. Verify how the modifier emits it — if it's dropped into the anchor unescaped, you've handed authors an HTML injection vector. Test with a payload before you let non-technical users near it.
• Empty and self-referential links. An entry that links to itself, or a link inside a loop over the same collection, can produce recursive or duplicated rendering if you invoke the modifier inside a nested loop. Guard for id !== current id when you build related-content blocks manually.
• Performance in loops. The backlinks tag inside a collection listing is an N+1 shape — one lookup per entry. Fine for ten entries, not for a paginated 200-item index page. Either eager-load via the index or restrict the tag to single-entry templates.
• Drafts and unpublished entries. Missing-link styling will likely flag links to drafts as broken. Make sure your editorial workflow (draft → publish) doesn't cause authors to "fix" a link that was already correct.
• Extension points to check first: the CP sidebar and dashboard widget views (overridable in your theme), the config's class names, and whether the addon exposes events on link creation — useful if you want to notify an author when someone links to their page.
• Debugging order. Link not rendering → is the modifier present and in the right order? Link rendering as plain text → is the field handle enabled in config, and is the config cached? Link red/missing when the page exists → is the entry published and in an enabled collection, and is the index current? That tree resolves most reports in under a minute.