Publish and operate semantic Markdown
Publish compact llms.txt navigation indexes, preserve representation-aware edge behavior, and test HTML and Markdown independently.
First add Markdown representations to the pages you want to link. An index helps a reader or agent choose a starting point; it does not create those representations or grant access to them. Group links by the tasks your audience needs to complete, with short descriptions that help readers choose without opening every page.
Publish an llms.txt index
#Indexes are concise, explicitly authored navigation resources, not generated route inventories:
import { md } from "brix/markdown";
import { createMarkdownIndexContract } from "#brix";
import { createMarkdownIndexRoute } from "#brix/server";
export const siteMarkdownIndexRoute = createMarkdownIndexRoute(
createMarkdownIndexContract({ 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. The route serves text/markdown; charset=utf-8:
# Example
> Task-oriented product documentation.
## Documentation
- [Start](/docs/start.md): Setup guide.
md.indexDocument takes a title (up to 200 characters), an optional summary blockquote (up to
500), optional details paragraph (up to 2,000), and 1 to 100 sections. Each section has a title
(up to 200) and at least one link; an index holds at most 500 links. Link titles allow 200
characters and descriptions 500, text may not be blank, and URLs follow the
builder URL rules. Link durable .md resources so
readers receive Markdown without negotiating.
The document callback receives the request context and { locale }, and may be async. Route
options also accept auth, middleware, and enabled, as on page routes.
Serve an index serialized ahead of time
#The callback runs and serializes the index on every request. When the index does not depend on the request, serialize it once when the module loads and return the wrapped string:
import { md, serializeMarkdownIndexDocument } from "brix/markdown";
import { createMarkdownIndexContract } from "#brix";
import { createMarkdownIndexRoute } from "#brix/server";
const siteIndex = md.serializedIndexDocument(
serializeMarkdownIndexDocument(
md.indexDocument({
title: "Example",
sections: [{ title: "Documentation", links: [{ title: "Start", url: "/docs/start.md" }] }],
}),
),
);
export const siteMarkdownIndexRoute = createMarkdownIndexRoute(
createMarkdownIndexContract({ path: "/llms.txt" }),
{ document: () => siteIndex },
);
The response bytes and headers are unchanged. md.serializedIndexDocument accepts only output of
serializeMarkdownIndexDocument; see
serve Markdown serialized ahead of time
for what it checks and why it exists. A localized index can serialize one document per locale and
select it from { locale }; an index that depends on other request data keeps building
md.indexDocument in the callback.
Scope and localize indexes
#Paths are static, parameter-free, and end in /llms.txt. They cannot contain empty, ., or ..
segments, which URL parsing would normalize away before routing. The parent path is the index scope:
/llms.txt covers the whole site and /docs/llms.txt covers /docs and everything below it. A
Markdown-enabled page is described by the most specific covering index with the same auth
setting. That page receives Link: </docs/llms.txt>; rel="describedby", a matching head link in
HTML, and a single > [Agent navigation index](/docs/llms.txt) line at the start of its Markdown
body. Author paths and scopes in decoded form, including Unicode; Brix matches them against encoded
request paths and emits the percent-encoded URL in headers and the navigation line.
For a localized index, pass a path per locale. The keys must exactly match the configured locales,
the callback receives that route's locale, and each localized index covers only pages in its
locales. Resolve its URL with getMarkdownIndexPath(contract, locale), which throws for an unknown
locale. An unlocalized index receives locale: undefined.
const docsIndex = createMarkdownIndexContract({
path: { en: "/docs/llms.txt", sv: "/dokument/llms.txt" },
});
const svIndexUrl = getMarkdownIndexPath(docsIndex, "sv");
Match index auth to every covered page. Route mounting fails when an index's auth setting
differs from a Markdown-enabled page in its scope, and edge manifest merging applies the same check
across services. Brix compares only whether auth is set: it cannot see restrictions in custom
middleware or verify authored link destinations. Test access for the intended audience, and keep
indexes compact instead of publishing llms-full.txt.
Cache and test representations
#Applications emit manifest schema 2, which lists page representations, durable aliases, and
indexes. A compatible central edge partitions HTML and Markdown cache keys, normalizes Accept,
validates the trusted origin marker and media type before storing, and strips the private marker
before responding. Durable aliases keep their own Markdown keys. Indexes are never cached 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.
For pages declaring Markdown, shellIndependent query values remain in both HTML and Markdown
cache keys. Markdown contains the fragment semantics, while HTML's automatic alternate URLs retain
the live query. HTML-only deferred shells can still exclude those values. Test contrasting values
such as two campaigns, not just HTML versus Markdown for one request.
Page keys use the brix:3 namespace and include the request origin and, for HTML, inline or
deferred mode. Markdown and plain-text responses receive a script-free CSP (script-src 'none', no
nonce), so the default policy does not block shared storage of Markdown; HTML still requires an
edge-delivered CSP. See the
cache admission contract for the full
request, response, CSP, and cache-key requirements.
Contentful projections share HTML's configured scope classification: private/Preview scopes force
private, no-store for negotiated and durable Markdown, independently of islands or hydration
payloads. Preserve those origin headers at every cache/proxy. This does not replace route auth,
index audience checks or private data-cache partitions. Public Markdown retains ordinary route
cache policy; a representation-specific key alone does not make personalized content public-safe.
Test HTML and Markdown independently. This example assumes a route fixture returning title
"Example" and summary "Summary.", without a covering index mounted in the test harness (a
covering index would prepend its navigation line):
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.