BridgeToAgent
Get the kit — $49
All posts
Audit4 min read

auto-discovery-links — the 3 link rel="alternate" tags Chrome looks for in your head

The auto-discovery-links audit passes or fails on a single three-line HTML paste. This post is the copy-paste reference — the exact three tags, the platform-specific paste locations for 7 CMSs, the four common mistakes that flunk the audit even with the tags present, and the curl one-liner to verify the paste worked.

BridgeToAgentEditorial team

auto-discovery-links — the 3 <link rel="alternate"> tags Chrome looks for in your <head>

auto-discovery-links is the Lighthouse Agentic Browsing audit that passes or fails on a single three-line HTML paste. Three <link rel="alternate"> tags in the homepage <head>, pointing at your three agent-readable files. Sites that pass the file-presence audits (llms-txt-present, agents-json-present, agent-runbook-present) but skip this one have the files but no machine-readable signal for agents to find them.

This post is the copy-paste reference. The exact tags, the paste-location for every major CMS, the four mistakes that flunk the audit even when the tags appear in your source, and the verification step.

The snippet

Paste these three lines inside your homepage <head>:

<link rel="alternate" type="application/json" title="Agent Action Map" href="/agents.json">
<link rel="alternate" type="text/plain" title="LLM Context" href="/llms.txt">
<link rel="alternate" type="text/markdown" title="Agent Runbook" href="/agent-instructions.md">

That's the entire fix. Every audit pass depends on these three lines being parseable, with the right attributes, with href values that resolve to the actual files.

The exact attributes that matter

AttributeRequired valueWhy
rel"alternate"Without this, the tag is invisible to the audit
typeMatches the file's served content typeMismatch flunks the audit even if the file exists
titleHuman-readable nameUsed for accessibility + agent UI surface
hrefAbsolute path with leading /Relative paths fail when the agent visits non-homepage URLs

The title values are recommendations, not requirements. The audit doesn't validate the specific text, but agent-facing tools render them in their UI when surfacing your kit files — pick names that are clear to a non-developer reading them. "Agent Action Map", "LLM Context", "Agent Runbook" are the kit's defaults.

Platform-specific paste locations

Shopify

layout/theme.liquid → inside the <head> block, near other <link> tags. Save. No build step.

If you don't want to edit theme.liquid directly, install a "Header Code Injection" app from the Shopify App Store — it lets you add <head> content without theme edits. Theme updates won't clobber app-injected code.

WordPress

Three options:

  1. "Insert Headers and Footers" plugin (by WPCode, ~10M active installs) — Settings → WPCode → Header → paste the three lines → save. Works on any theme.
  2. Yoast SEO Premium / RankMath Pro — both have a "custom head code" option in their general settings.
  3. Edit header.php directly — theme-specific path. Only do this on a child theme; otherwise theme updates clobber the change.

Webflow

Project Settings → Custom Code → Head Code → paste the three lines → save → publish.

The Head Code lives at the project level, not the page level — which is right; you want these on every page, not just the homepage. The audit checks the homepage but the spec actually wants them sitewide so agents finding deep links can still discover the kit files.

Squarespace

Settings → Advanced → Code Injection → Header → paste the three lines → save.

Code Injection requires a Business plan or higher on Squarespace 7.1. Personal-plan sites can't pass auto-discovery-links without upgrading or using a Cloudflare-front-of-site workaround (see Cluster-3 Squarespace+Wix checklist).

Wix

Settings → Advanced → Custom Code → Add Custom Code → paste the three lines → place in Head → apply to All pages → load Once per visit → save.

Wix Premium plan required. Free plans can't add Custom Code at all.

Next.js (App Router)

In app/layout.tsx, extend the metadata.alternates.types object:

export const metadata: Metadata = {
  // ... other metadata
  alternates: {
    types: {
      'application/json': [
        { url: '/agents.json', title: 'Agent Action Map' }
      ],
      'text/plain': [
        { url: '/llms.txt', title: 'LLM Context' }
      ],
      'text/markdown': [
        { url: '/agent-instructions.md', title: 'Agent Runbook' }
      ]
    }
  }
};

Next.js emits the corresponding <link rel="alternate"> tags from this metadata block. No manual HTML required.

Static HTML / Hugo / Jekyll

Paste the three lines into your site's <head> template (<head> partial, base layout, or whatever your generator calls it). Rebuild and redeploy.

Four mistakes that flunk the audit even with the tags present

1. href paths are relative

<!-- Wrong -->
<link rel="alternate" type="text/plain" title="LLM Context" href="llms.txt">

The href="llms.txt" resolves relative to the page URL. On the homepage that works, on /blog/some-post it resolves to /blog/llms.txt which 404s. Always use leading slash: href="/llms.txt".

2. type doesn't match the file's served content type

If your llms.txt is being served as application/octet-stream (some hosts default this for .txt files), and your tag declares type="text/plain", the audit flags the mismatch. Either fix the served content type (Audit 2 in the per-audit fix reference) or align the tag's type to what's actually served. Fixing the content type is correct — the alternative is technically debt.

3. Tags are added but the files don't exist

The audit verifies the href resolves. If the tag points at /agents.json but the file isn't there, the audit fails even with the tag perfectly written. Make sure the three files exist before pasting the tags — Audits 1, 3, 5 in the per-audit fix reference cover the file uploads.

4. Tags are pasted into the wrong section

A <link rel="alternate"> tag pasted inside <body> or inside an inner <section> doesn't count. The tags must be inside the <head> element. View-source your page and confirm the tags appear before </head> — not after.

Verifying the paste worked

Two checks:

  1. View-source on your homepage — Ctrl+U (Windows) or Cmd+Option+U (Mac) in any browser. Press Ctrl+F for in-page search and grep for rel="alternate". You want three matches.

  2. curl for the headers + tags —

curl -sL https://yourdomain.com | grep 'rel="alternate"'

You should see three lines, each containing type="application/json", type="text/plain", and type="text/markdown" respectively. If curl returns zero matches but view-source shows the tags, your page is being rendered client-side and Lighthouse won't see the tags either — see Next.js section above for the metadata-API approach that emits tags server-side.

After paste, the audit flips green on the next Lighthouse run. No cache to clear, no rebuild to wait for (beyond your site's own deploy step).

Why this audit is the cheapest five-point Lighthouse fix in the entire category

auto-discovery-links is weighted equally to the file-presence audits in the Lighthouse Agentic Browsing scoring. Three lines of HTML, five minutes of work, ~5 points on the category score. It's the highest-ROI single change inside the category for sites that already have the kit files but skipped the discovery tags.

If you're auditing a partial install, this is the first audit to close after the file-presence checks. Everything else (Schema density, action typing) is meaningfully more work for similar audit-score lift.

Related

Keep reading

All posts →