Your work now has two audiences, and one of them is an agent

A person who lands on a documentation page can see the sidebar. They can notice that “Quickstart” comes before “Configuration,” scan the headings, follow a tag, or retreat to the homepage when they chose the wrong path.

A coding agent fetching the same URL may receive thousands of tokens of layout, navigation, scripts, attributes, and decorative markup. Remove all of that and serve only the page’s Markdown, and a different problem appears: the agent can read the page but no longer knows what else exists.

This is not a future edge case. Technical work now has at least two active audiences. People read it directly. Agents read it on behalf of people who are trying to install, compare, debug, or change something.

The answer is not to choose one audience. It is to author once and design a different reading surface for each.

One publication policy does not require one representation.

A human needs orientation, not only information

Suppose a developer opens a page called “Authentication.” The words may be accurate, but understanding still depends on context:

• Is this a tutorial, a reference, or an architectural explanation?
• Does it apply to the current version?
• What should be completed before this step?
• Where are the examples and failure cases?
• What is the next useful page?

The visible interface answers those questions through hierarchy, typography, sequence, and relationships. A docs sidebar establishes the product model. A writing index adds dates and authorship. A project page emphasizes outcomes and destinations. A table of contents shows the argument’s shape before the reader commits to it.

Calling all of that “chrome” misses its purpose. Good presentation compresses orientation into space.

That is why TidyPress does not render every collection through one generic template. The public interface should help a person understand what kind of knowledge they have entered.

Search needs smaller pieces

Interactive search has a different job. It should move a person from an imperfect phrase to the most useful passage without asking them to understand the site first.

TidyPress generates its local search index after static rendering. The index therefore sees the headings, prose, collection identity, and final public URLs that a visitor can actually open. The browser loads those generated search assets only when search is used; no hosted search account is required.

Collection filters matter here. “Deploy” in product documentation is not always the same intent as “Deploy” in a dated engineering essay. TidyPress marks indexed regions with collection metadata so the search interface can narrow results without inventing a taxonomy separate from the content model.

Authors can exclude a page with search: false without unpublishing it. A legal notice may need a public URL but offer little value in search. Publication and retrieval are related decisions, not identical ones.

An agent needs a map before it needs a page

Agents fail differently from people. They are willing to guess.

Give an agent one clean Markdown page and ask about a nearby feature. It may construct a plausible URL from the heading, fetch a path that never existed, then spend more context recovering. Give it raw HTML and it may waste tokens finding the article body. Give it titles alone and it has a map with no terrain.

Mintlify published a useful public benchmark of this behavior across 2,400 agent runs. Plain Markdown without a documentation map caused agents to guess paths; adding a link to llms.txt reduced dead-URL requests by roughly 90 percent. The important finding was not “Markdown wins.” It was that the map wins.

TidyPress currently produces one complete build/llms.txt on every build unless the capability is disabled. It is organized by enabled collection and includes each published entry’s title, public URL, description, and full authored body.

# Laboratory name
 
## writing
 
### [A notebook is evidence](/writing/one-renderer-two-toolchains)
Why computational evidence still needs an editorial pass.
 
The complete published Markdown follows.

For the relatively compact, Git-native publications TidyPress targets today, one inspectable file is a deliberate choice. An agent can read it from the build folder or fetch /llms.txt from the deployed site. There is no retrieval account required to discover the corpus.

The difficult problem is publication agreement

Generating HTML, a search index, and a text file is easy. Making them agree about what is public is the real work.

TidyPress applies the collection configuration and publication state before these artifacts diverge:

• published: false removes an entry from public routes and llms.txt;
• a future scheduled date keeps it out until that time;
• disabled collections do not leak into machine context;
• base paths used by routes are also used for exported public URLs;
• search exclusion remains separate because a public page may not belong in interactive search.

Without one policy, a draft can disappear from the website while remaining in an agent export. A renamed docs path can be correct in navigation while stale in a manually maintained context file. The most dangerous version of drift is the one no human reader sees.

Complete for agents does not mean exhausting for people

Writing for agents creates a pressure toward completeness. If a command is not documented, an agent may infer that it does not exist. If an error condition is only visible in a CLI help string, the agent may recommend a path the product rejects.

Human readers cannot absorb an undifferentiated dump of every flag and edge case. They need progressive disclosure: a short path to first success, then deeper explanation and reference when the task demands it.

The solution is not to make the human page resemble llms.txt. It is to keep the underlying knowledge complete while designing human paths through it:

• task pages remain concise and link to exact reference;
• reference remains exhaustive and searchable;
• components reveal examples without flattening the narrative;
• the agent representation receives complete authored bodies without visual machinery.

Single source is useful precisely because the representations can differ without the facts drifting.

What TidyPress does not claim yet

llms.txt is not a hosted retrieval system, an MCP server, or a guarantee that an agent will reason correctly. The default local search layer is retrieval, not a semantic answer engine. TidyPress does not currently measure agent traffic or rank context using private usage data.

Those could become optional layers. They should not be confused with the core promise: a complete, public, machine-readable artifact already exists before another service is added.

That boundary matters to a small lab, open-source maintainer, or independent developer. They can make work legible to agents without first operating a retrieval platform or surrendering the corpus to one.

Publish meaning, then choose the interface

The old publishing question was, “Does the site look good and can a person find the page?” That remains necessary.

The new question adds, “Can an agent discover the real paths, retrieve the authored context, and distinguish public truth from drafts?”

Those are not competing requirements. People deserve a deliberate interface. Agents deserve a low-noise map. Search deserves fragments aligned with the final site. The repository deserves to remain the point where all three agree.

The publication is not the HTML, the index, or the text export alone. It is the shared meaning that survives across them.