The Machine-Readable Layer: How to Write llms.txt, JSON-LD, and evidence.json

The machine-readable layer consists of three files and fragments: llms.txt at the site root, JSON-LD inside pages, and the evidence index file. They lower a model's comprehension cost but do not replace content quality or primary sources.

Who it applies to and prerequisites

It applies to sites that already have a stable content structure and a source register. The prerequisites are stable page addresses, unified entity information, and registrable sources.

• Page addresses no longer change frequently.
• Author and publisher identifiers are unified.
• There is a maintainable set of evidence numbers and a source table.

Why do it this way

A generative model needs to understand which subject a page discusses, which content is worth crawling, and where the basis for each claim lies. The three materials map to these three questions.

llms.txt provides a site-level guide, JSON-LD provides page-level structure, and the evidence index provides claim-level sources. None of them changes crawl permission or promises indexing or citation.

Generating all three at build time avoids the inconsistency of manual maintenance.

Steps

1. Write the llms.txt guide. Structure it as site description, core definitions, methods, metrics, evidence index, and citation suggestions. Criterion: every link is absolute and opens.
2. Write page JSON-LD. Give the main type and required fields by page type, and write only identifier and name for entities. Criterion: validation passes and fields match body text.
3. Write the evidence index. Sort by evidence number and include claim, type, level, address, source, verification date, and review cycle. Criterion: numbers are unique and source addresses open.
4. Connect the build. Generate all three files from the content manifest at build time without manual editing. Criterion: files match actual content after publishing.
5. Measure regularly. Each quarter, check whether the files are crawled and whether citations change, and record the observation method. Criterion: observations are recorded and conclusions are not overstated when nothing changes.

Counterexample: three files, three sets of facts

The following is a common counterexample (an illustration, not a real client). llms.txt is maintained by hand, JSON-LD is generated from a template, and the evidence index lives in another spreadsheet, with inconsistent subject names and page addresses across the three.

The model receives conflicting signals, which is worse than having only body text. The fix is to consolidate all three into one content manifest and generate them at build time.

Evidence and basis

【Claim】The machine-readable layer lowers comprehension cost but does not replace content quality or primary sources. 【Basis】This site's method page The Machine-Readable Layer (working definition). 【Publisher】GEOA (Xingge, one-person company). 【Date】Published 2026-11-09; review cycle 365 days. 【Location】Section 2, Why do it this way. 【Excerpt】The three materials map to these three questions. 【Link】https://geoa.com.cn/method/machine-readable/ | verified 2026-11-09

This method is empirical, marked L2, has no third-party validation, and must not be cited as a standard.

Limitations and unsuitable scenarios

• llms.txt is a community proposal, not a W3C or IETF standard, and its crawling effect requires measurement.
• Structured data only lowers comprehension cost and cannot produce citations or indexing.
• The evidence index covers only registered items; unregistered claims do not appear.
• All three files are generated by the build, so they are unsuitable as a fast channel for temporary campaigns.

Self-check list

FAQ

Is llms.txt an official standard? No. It is a community proposal, its crawling effect requires measurement, and pages must not claim certain indexing.

Will adding JSON-LD get content cited? No. It only affects comprehension cost; citation also depends on content and sources.

Does evidence.json duplicate the on-page evidence blocks? No. Page evidence blocks serve readers, the index file serves machines, and fields share one source.

Related reading

Related sections: glossary index, metric index, method index, checklist index, whitepaper, editorial policy.