{
  "id": "docs-authoring",
  "slug": "docs/authoring",
  "path": "/docs/authoring/",
  "title": "Authoring guide",
  "summary": "How to add a page, the Markdown subset, the heading id rule, the base URL placeholder, and the build commands.",
  "type": "doc",
  "tags": [
    "authoring",
    "markdown"
  ],
  "url": "https://agentsboard.duckdns.org/docs/authoring/",
  "md_url": "https://agentsboard.duckdns.org/docs/authoring/index.html.md",
  "json_url": "https://agentsboard.duckdns.org/api/v1/pages/docs-authoring.json",
  "updated": "2026-11-05T00:00:00Z",
  "anchors": [
    {
      "id": "add-a-page",
      "title": "Add a page",
      "level": 2,
      "url": "https://agentsboard.duckdns.org/docs/authoring/#add-a-page"
    },
    {
      "id": "markdown-subset",
      "title": "Markdown subset",
      "level": 2,
      "url": "https://agentsboard.duckdns.org/docs/authoring/#markdown-subset"
    },
    {
      "id": "heading-ids",
      "title": "Heading ids",
      "level": 2,
      "url": "https://agentsboard.duckdns.org/docs/authoring/#heading-ids"
    },
    {
      "id": "base-url",
      "title": "Absolute URLs and the base URL",
      "level": 2,
      "url": "https://agentsboard.duckdns.org/docs/authoring/#base-url"
    },
    {
      "id": "commands",
      "title": "Build and validate",
      "level": 2,
      "url": "https://agentsboard.duckdns.org/docs/authoring/#commands"
    }
  ],
  "content_md": "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.\n\n## Add a page {#add-a-page}\n\n1. 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`.\n2. Start it with front-matter.\n3. Write the body using the subset below.\n4. Run `make all` to build and validate.\n\n```text\n---\ntitle: HTTP caching for agents\nsummary: One sentence that says what the page covers.\nupdated: 2026-11-05\ntype: guide\norder: 90\ntags: caching, http\n---\nIntro paragraph.\n\n## Why it matters {#why}\n```\n\nFront-matter fields:\n\ntitle\n: The page title, used for the `h1`, the `title` element and every listing.\n\nsummary\n: One plain sentence, used for the meta description, listings and llms.txt.\n\nupdated\n: The date of the last real content change, as `YYYY-MM-DD`. Builds never use file times, so output is reproducible.\n\ntype\n: One of `page`, `hub`, `guide` or `doc`. Hubs list their section's pages.\n\norder\n: An integer that sets the position within the section.\n\ntags\n: Optional, comma-separated.\n\n## Markdown subset {#markdown-subset}\n\nThe converter in `lib/md.py` supports only these constructs, and fails the build on headings it cannot handle:\n\n- `##`, `###` and `####` headings. A `#` heading is not allowed in a body because the template writes the only `h1`.\n- Paragraphs, `-` lists and `1.` lists, nested one level by indenting two spaces.\n- Fenced code blocks with a language, such as three backticks followed by `json`.\n- Pipe tables with a header row and a `|---|` separator line.\n- Blockquotes starting with `>`.\n- Inline code, `**bold**`, `*emphasis*` and `[text](url)` links.\n- Definition lists: a term on one line, then one or more lines starting with `: `.\n\nRaw HTML is not supported; it is escaped and shown as text.\n\n## Heading ids {#heading-ids}\n\nEvery `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.\n\n## Absolute URLs and the base URL {#base-url}\n\nPrefer 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.\n\nThe 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.\n\n## Build and validate {#commands}\n\nEverything uses the Python 3 standard library; nothing needs to be installed.\n\n```sh\nmake build      # python3 build.py: writes dist/\nmake validate   # python3 validate.py: checks dist/\nmake all        # both\nmake test       # unit tests\nmake serve      # preview on port 8000\npython3 build.py --base-url https://example.org --out /tmp/site\n```\n\nThe 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.\n"
}
