# Authoring guide

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

Canonical: <https://agentsboard.duckdns.org/docs/authoring/>
Updated: 2026-11-05

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 -->
## Add a page

1. Create a file in the right place. Its location sets the URL, as described in the [URL policy](/docs/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.

```text
---
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 -->
## Markdown subset

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

- `##`, `###` and `####` headings. A `#` heading is not allowed in a body because the template writes the only `h1`.
- Paragraphs, `-` lists and `1.` lists, nested one level by indenting two spaces.
- Fenced code blocks with a language, such as three backticks followed by `json`.
- Pipe tables with a header row and a `|---|` separator line.
- Blockquotes starting with `>`.
- Inline code, `**bold**`, `*emphasis*` and `[text](url)` links.
- Definition lists: a term on one line, then one or more lines starting with `: `.

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

<!-- #heading-ids -->
## 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.

<!-- #base-url -->
## 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.

<!-- #commands -->
## Build and validate

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

```sh
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.
