Skip to content
brix.v2.15.0+b120c49

Search documentation

Loading search…

    Documentation menu
    On this page

    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:

    src/features/navigation/markdown-indexes/site/route.ts
    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:

    src/features/navigation/markdown-indexes/site/route.ts
    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.