> [Agent navigation index](/llms.txt)

# Publish and operate semantic Markdown

Publish compact `llms.txt` navigation indexes, preserve representation-aware edge behavior, and test HTML and Markdown independently.

This is not the website's `markdown-it` prose parser. `markdown-it` parses trusted documentation
files such as this one for display. Application representations use the closed `brix/markdown`
builder so CMS and user text cannot become active Markdown or raw HTML.

## Publish an `llms.txt` index

Indexes are concise, explicitly authored navigation resources, not generated route inventories:

```ts
import { md } from "brix/markdown";
import { createMarkdownIndex } from "#brix";
import { createMarkdownIndexRoute } from "#brix/server";

export const siteMarkdownIndexRoute = createMarkdownIndexRoute(
  createMarkdownIndex({ path: "/llms.txt" }),
  {
    document: () =>
      md.indexDocument({
        title: "Example",
        summary: "Task-oriented product documentation.",
        sections: [
          {
            title: "Documentation",
            links: [{ title: "Start", url: "/docs/start.md", description: "Setup guide." }],
          },
        ],
      }),
  },
);

```

Place the route in `src/features/<feature>/markdown-indexes/<name>/route.ts` and export one lower-camel
runtime value ending in `MarkdownIndexRoute`. Paths are static, parameter-free, and end in
`/llms.txt`; localized path maps must exactly match configured locales. The normalized parent path is
the index scope, and the most-specific covering index describes a page.

Match index `auth` to every covered page. Brix checks known route auth modes but cannot understand
restrictions hidden in custom middleware or verify authored destinations. Test access for the intended
audience and link durable `.md` resources. Keep indexes compact instead of publishing `llms-full.txt`.

## Cache and test representations

Representation-aware applications emit manifest schema 2. A compatible central edge partitions HTML
and Markdown cache keys, normalizes Accept, validates a trusted successful origin marker and media
type before storing, and strips the private marker before responding. Durable aliases choose fixed
Markdown keys. Indexes remain uncached at the shared Brix edge. Deploy schema-2 edge support before
represented origins and retain route auth, locale, query, and named cache policies. See
[caching](/docs/caching) and [server setup](/docs/server).

Test HTML and Markdown independently:

```ts
const html = await testPage(articlePageRoute, {
  params: { slug: "example" },
  representation: "html",
});

const markdown = await testPage(articlePageRoute, {
  params: { slug: "example" },
  representation: "markdown",
});

expect(html.html).toContain("Example");
expect(markdown.markdown).toBe("# Example\n\nSummary.\n");

```

`testPage` uses the durable path for Markdown, so an Accept override cannot change the selected test
representation. Add application tests for canonical negotiation, durable equivalence, discovery,
authorization, index coverage, `HEAD`, locale, and error responses.

```sh
brix test
brix check
brix build

```

See [testing](/docs/testing) for route-harness options.