Agent-Friendly Web

Authoring guide

How to add a page, the Markdown subset, the heading id rule, the base URL placeholder, and the build commands.

Updated

Content lives in Markdown files under content/. One build turns each file into an HTML page, a Markdown copy, a JSON record, and entries in the sitemap, feed and llms.txt.

Add a page

  1. Create a file in the right place. Its location sets the URL, as described in the URL policy: content/guide/caching.md becomes /guide/caching/ with id guide-caching.
  2. Start it with front-matter.
  3. Write the body using the subset below.
  4. Run make all to build and validate.
---
title: HTTP caching for agents
summary: One sentence that says what the page covers.
updated: 2026-11-05
type: guide
order: 90
tags: caching, http
---
Intro paragraph.

## Why it matters {#why}

Front-matter fields:

title
The page title, used for the h1, the title element and every listing.
summary
One plain sentence, used for the meta description, listings and llms.txt.
updated
The date of the last real content change, as YYYY-MM-DD. Builds never use file times, so output is reproducible.
type
One of page, hub, guide or doc. Hubs list their section's pages.
order
An integer that sets the position within the section.
tags
Optional, comma-separated.

Markdown subset

The converter in lib/md.py supports only these constructs, and fails the build on headings it cannot handle:

Raw HTML is not supported; it is escaped and shown as text.

Heading ids

Every h2 and h3 must end with an explicit id, such as ## Why it matters {#why}. Ids use lowercase letters, digits and hyphens, must be unique within the page, and must never change once published. Levels must not be skipped, and the first heading must be an h2. The build stops with the file name and line number if any rule is broken. An h4 may have an id; if it does not, one is made from its text.

Absolute URLs and the base URL

Prefer root-relative links such as /docs/url-policy/ in prose. When a page needs an absolute URL to this site, for example in a curl example, write the placeholder base_url wrapped in double curly braces, followed by the path. The build replaces it with the configured base URL everywhere, including inside code, so the HTML, the Markdown copy, the JSON record and llms-full.txt all match. It is the only supported placeholder; any other double-brace token fails the build. Never write the real domain in content.

The base URL is set once, as base_url in site.json. It must be a bare origin, a scheme and host with an optional port such as https://example.org, with no path and no trailing slash, because every internal link is root-relative. The build rejects any other form. To build for another domain without editing the file, pass it on the command line.

Build and validate

Everything uses the Python 3 standard library; nothing needs to be installed.

make build      # python3 build.py: writes dist/
make validate   # python3 validate.py: checks dist/
make all        # both
make test       # unit tests
make serve      # preview on port 8000
python3 build.py --base-url https://example.org --out /tmp/site

The validator checks links and anchors, heading structure and self-links, JSON against the schemas, the sitemap, llms.txt, the endpoint table, base URL hygiene and size budgets. Fix every error it reports before deploying.