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:

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 and server setup.

Test HTML and Markdown independently:

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.

brix test
brix check
brix build

See testing for route-harness options.