Lighthouse Fails Your Llms.txt With out Markdown Hyperlinks

Chrome’s new Lighthouse Agentic Looking audit treats your .txt file as a markdown doc. In case your llms.txt doesn’t use markdown hyperlink syntax, you fail the audit, even when each hyperlink within the file is correct and works. I ran the audit on nohacks.co. Two of six audits handed. Three got here again not relevant. One failed: the llms.txt audit, with the verbatim error “File doesn’t seem to include any hyperlinks.” The repair was 5 characters per hyperlink. The file remains to be served as plain textual content. Solely the audit end result modified.

Lighthouse 13.3.0 shipped the Agentic Looking class alongside Efficiency, Accessibility, search engine optimisation, and Greatest Practices. Six audits within the default set: accessibility tree well-formedness (agent-accessibility-tree), cumulative structure shift (cumulative-layout-shift), llms.txt discoverability (llms-txt), and three WebMCP checks (webmcp-registered-tools, webmcp-form-coverage, webmcp-schema-validity). The class returns a fractional go ratio as an alternative of a 0-to-100 rating, as a result of the requirements for the agentic internet are nonetheless in movement.

1 Of 6 Audits Failed On Nohacks.co

I ran the audit through the Lighthouse CLI: npx lighthouse@newest https://nohacks.co --only-categories=agentic-browsing. Six audits returned. Three got here again not-applicable, all WebMCP: webmcp-registered-tools, webmcp-form-coverage, and webmcp-schema-validity. Lighthouse provides no purpose for a not-applicable end result, it simply marks the audit and strikes on. nohacks.co does expose WebMCP, however solely by means of the experimental crucial navigator.modelContext API (two glossary instruments, two for an agentic-browser listing), with no declarative type annotations. The scan ran in a default headless Chrome 150 with no WebMCP flag, so the not-applicable verdict might imply the web site exposes nothing these audits acknowledge, or that the scan surroundings had no WebMCP API energetic on the time. Lighthouse doesn’t say which. Two audits handed cleanly: agent-accessibility-tree reported “All audits handed,” confirming the semantic HTML and ARIA construction is well-formed sufficient for brokers to navigate, and cumulative-layout-shift got here again at zero.

One audit failed: llms-txt. The verbatim error message from Lighthouse was:

File doesn’t seem to include any hyperlinks.

The class rating was 0.67. That was the primary shock. The file at nohacks.co/llms.txt has many hyperlinks. Navigation paths to articles, episodes, visitors, the glossary. RSS feed URLs. Audio file URL patterns. The file is over 5 kilobytes of structured content material. So why was Lighthouse reporting zero hyperlinks?

Lighthouse Parses .txt As Markdown And Rejects Plain-Textual content Hyperlinks

The file extension is .txt, however Lighthouse parses the contents as markdown, and calls for markdown hyperlink syntax for any textual content to depend as a hyperlink. The file is known as llms.txt. The HTTP server returns it with a textual content/plain MIME kind. Open it in a browser, and also you see plain textual content. However the llms.txt specification at llmstxt.org defines the format as a markdown doc. The spec is specific: “Every part comprises a markdown bullet checklist of hyperlinks. Every checklist merchandise has a hyperlink adopted by non-compulsory notes concerning the hyperlink, separated from the hyperlink by a colon.” Lighthouse’s parser enforces that strictly. Each hyperlink should be encoded as markdown hyperlink syntax, [text](url), with sq. brackets across the hyperlink textual content and parentheses across the URL.

My file had been utilizing a extra pure plain-text format:

- Homepage: / - Publication masthead, cornerstone sequence, newest articles and episodes
- Articles: /weblog - All articles on AXO, the agentic internet, and AI brokers
- Episode: /episode/[slug] - Full present notes, transcript, audio participant

Identical locations. Identical descriptions. Identical data. Lighthouse’s parser doesn’t register these strains as hyperlinks. Throughout the complete file, it registered precisely zero. Audit fails.

A file with a .txt extension, served with a textual content/plain MIME kind, that fails an audit except it’s formatted as markdown. That may be a mismatch the audit layer goes to must be extra sincere about. The extension says one factor. The MIME kind says one factor. The parser is the supply of fact, and the parser calls for markdown.

The Repair Is 5 Characters Per Hyperlink

Wrap every hyperlink goal in markdown bracket-paren syntax, [text](url), and substitute the - separator earlier than every description with : . 5 characters per hyperlink. Mechanical conversion, repeated throughout the file.

- [Homepage](/): Publication masthead, cornerstone sequence, newest articles and episodes
- [Articles](/weblog): All articles on AXO, the agentic internet, and AI brokers
- [Episode](/episode/[slug]): Full present notes, transcript, audio participant

I made the edit. Re-ran the audit. Rating went from 0.67 to 1.0. The audit title flipped from “llms.txt doesn’t comply with suggestions” to “llms.txt follows suggestions.” No element gadgets within the after-report. Clear go.

The file remains to be served as textual content/plain. The file extension remains to be .txt. The file content material remains to be the identical content material. Solely the hyperlink encoding modified.

Lighthouse Measures Parseable Hyperlink Syntax, Not File High quality

The audit checks whether or not your file is mechanically parseable. It doesn’t verify whether or not the file describes your web site usefully. Each reads are true on the identical time.

The primary learn: The audit is measuring one thing actual. Markdown hyperlink syntax is mechanically parseable. Plain-text descriptive strains are usually not. If an AI agent (or the Lighthouse parser standing in for an agent) must extract hyperlinks from the file programmatically, the markdown format is required. The audit is right that the file earlier than my repair couldn’t be parsed for hyperlinks by the usual tooling. The conversion to markdown hyperlink syntax fixes an actual interoperability hole.

The second learn: format compliance is just not the identical as file high quality. A thoughtfully-written, correct, complete llms.txt that makes use of plain-text descriptions fails this audit. A skinny, auto-generated llms.txt with markdown hyperlink syntax passes. The audit can’t inform the distinction between the 2. The WordPress plugin AIOSEO, utilized by over 3 million web sites per its WordPress.org itemizing, generates llms.txt information with markdown hyperlink syntax by default, a default-on habits Glenn Gabe surfaced, and the plugin’s personal documentation confirms. These auto-generated information use markdown hyperlink syntax as a result of that’s what the generator emits. Most of them in all probability go this audit. Most hand-curated, owner-aware llms.txt information in all probability fail it.

That hole is price occupied with earlier than treating the audit’s go/fail as a measurement of how agent-ready your web site actually is. The audit is checking whether or not your file is parseable. It isn’t checking whether or not your file is helpful.

Ought to You Care About Lighthouse Agentic Looking’s Llms.txt Test?

Sure, however narrowly. Lighthouse can let you know whether or not your llms.txt is parseable as markdown. It can’t let you know whether or not the file describes your web site truthfully. That verify is yours. Open Chrome DevTools, click on the Lighthouse tab, confirm the Agentic Looking class is checked, and run Analyze in your URL. The audit takes beneath a minute. If it fails on the no-links error, the repair is 5 characters per hyperlink and 5 minutes of enhancing. If it passes, the tougher query is the one Lighthouse can’t ask. Was the file auto-generated by a plugin you didn’t configure, or did you write it your self, and both approach, does it describe what your web site truly is?

The Machine-First Structure Construction pillar sits beneath all of this: information fashions earlier than web page layouts, rendering independence, content material that doesn’t rely on client-side JavaScript or human-display defaults to be machine-readable. The llms.txt audit is a slender verify at that layer. The larger structural query, whether or not your machine-readable floor describes your web site precisely, is yours to run.

Extra Assets:

This publish was initially printed on No Hacks.

Featured Picture: Darko 1981/Shutterstock