Build for AI tools #

View this page as Markdown

Prompt:

Make our docs readable by AI tools, and keep the generated reference out of the whole text.

Also works: "Stamp the docs with the version they describe." "Our docs are served under /docs, not at the root."

What your tool does #

• Passes the path the site is served under as --base, so that the routes in the machine files are addresses an agent can open.
• Finds the section generated from another source, such as a reference section, and passes its slug as --full-text-exclude. Those pages stay reachable but are left out of the whole text, which keeps it small enough for an agent to read.
• Passes the version of the product the corpus describes as --corpus-version, so that the manifest states it.
• Builds, and reads back the index and the manifest to confirm the routes, the Optional listing, and the version.
• Asks which version the corpus describes when the project does not state one.

What you need #

• The web address path your docs will be served under, for example whether they sit at your site's root or under a subfolder.
• Which version of your product these pages describe.

Before your AI starts #

This section is for your AI coding tool: what it checks and gathers before it begins. You don't need to do these steps yourself.

• A corpus that passes the check and builds (Getting started).

Steps #

1. Set the base path #

Pass the path the site is served under as --base. The build writes it in front of every route in the manifest, the index, and the whole text. The pages link relatively, so the flag changes only those machine files and, given --origin, the address in each page's canonical link and og:url tag. Without it, routes start at /.

tzdocs build --source docs --out site --base /docs

2. Keep the generated pages out of the whole text #

Pass the slug of the section to leave out as --full-text-exclude. Its pages are left out of the whole text and the index's section listing, and the index lists them under its Optional heading instead. They stay pages, and the manifest marks each one in_full_text: false.

The prefix is tree-relative: /reference, not /docs/reference. It matches a page whose slug equals it or begins with it followed by /.

tzdocs build --source docs --out site --base /docs --full-text-exclude /reference

3. Stamp the version #

Pass the version of the product the corpus describes as --corpus-version. The build writes it as the manifest's top-level version, so that an agent can read which version the pages describe before it opens one.

tzdocs build --source docs --out site --base /docs --full-text-exclude /reference --corpus-version 2.4.0

4. Read the machine files back #

Open llms.txt at the tree root. Confirm that the routes begin with the base path and that the excluded pages are listed under Optional. Open docs.json and confirm its version and each excluded page's in_full_text: false. Output describes the four files and the order in which an agent reads them.

Beside llms.txt, a build given --origin also writes sitemap.xml, the list of every page's absolute address that search engines read. An agent reads the index; a crawler reads the sitemap (Publish the site).

Expected result #

The success line gives the page count and the number of pages left out of the whole text. It has this form: built 40 pages into site; 12 pages excluded from the full text.

The index lists the excluded pages under Optional and every other page under its section, each route beginning with the base path. The manifest has the version, and the whole text contains every page except the excluded ones.

Refusals #

Refusals and findings gives the exact text.

Related #

• Output describes the index, the manifest, the Markdown copy, and the whole text.
• Getting started lists every flag with its default.
• Glossary defines route, base path, and tree-relative.