Skip to content
brix.v2.15.0+b120c49

Search documentation

Loading search…

    Documentation menu
    Docs / Integrations / ContentfulRead Markdown
    On this page

    Contentful Rendering

    Use rendering adapters when Contentful owns nested, polymorphic page composition. Adapters keep CMS fields at the integration boundary while providing visual components and semantic Markdown from the same entry.

    Create the adapter factory

    #

    First generate the type map from your published models. The examples assume hero, article, and cardList models; substitute your actual IDs and fields. Create one browser-safe factory from that map:

    src/contentful-rendering.ts
    import { createContentfulAdapterFactory } from "brix/contentful/rendering";
    import type { Context } from "brix/hono";
    import type { ContentTypeMap } from "#/contentful-types.ts";
    
    export const createAdapter = createContentfulAdapterFactory<ContentTypeMap, Context>();
    

    The second type argument is the context type passed to adapter loader handlers; it defaults to unknown. Use a narrower type, such as Context<{ Bindings: Readonly<CoercedEnvSchema> }> with the generated environment type, when handlers read typed c.env.

    Write an adapter

    #

    Only conventional *.adapter.ts and *.adapter.tsx modules inspect Contentful fields and sys; brix check reports entry-field access anywhere else, including items[0]!.fields, getPage().fields, entries.map(({ fields }) => ...), and for (const { fields } of entries). Each adapter module exports exactly one PascalCase runtime value ending in Adapter, defined by a direct factory call with an object literal and a literal contentType. Type-only exports are allowed; config spreads and computed keys are rejected. Components receive ordinary application props.

    src/features/content/hero/Hero.adapter.tsx
    import { md } from "brix/markdown";
    import { createAdapter } from "#/contentful-rendering.ts";
    import { Hero } from "./Hero.tsx";
    
    export const HeroAdapter = createAdapter({
      contentType: "hero",
      markdown: ({ entry }) => md.heading(1, md.text(entry.fields.heading)),
      component: ({ entry, preview }) => (
        <Hero heading={entry.fields.heading} headingAttributes={preview?.getProps("heading")} />
      ),
    });
    

    Hero is an application component that accepts the projected heading and optional inspector attributes. Rendering a hero entry through the generated registry now selects this adapter; normal components do not need to read entry.fields themselves.

    The component callback receives:

    • entry — the entry, typed from contentType;
    • loaded — null for a loaderless adapter, otherwise the loader state described below;
    • props — extra props declared with propsOf;
    • renderEntry — renders a nested entry through the same registry;
    • preview — inspector attributes and controls, present only inside Live Preview;
    • assetsUrl — the configured assets base URL, empty by default.

    Declare extra props a parent passes with propsOf. Because the standalone preview renders an entry without its parent, TypeScript requires preview.props fallbacks when any extra prop is required:

    src/features/content/cardList/CardList.adapter.tsx
    import { propsOf } from "brix/contentful/rendering";
    import { createAdapter } from "#/contentful-rendering.ts";
    import { CardList } from "./CardList.tsx";
    
    export const CardListAdapter = createAdapter({
      contentType: "cardList",
      props: propsOf<{ appearance: "light" | "dark" }>(),
      preview: { props: { appearance: "light" } },
      component: ({ entry, props, renderEntry }) => (
        <CardList appearance={props.appearance} heading={entry.fields.heading}>
          {entry.fields.cards.map((card) => renderEntry(card))}
        </CardList>
      ),
    });
    

    Link resolution turns missing, unpublished, or inaccessible links into null, and generated types include it (for example Array<ICard | null>). The component and Markdown renderEntry accept null and undefined and render nothing for them, so entry.fields.cards.map(renderEntry) needs no filtering. In Markdown, await renderEntry(null) resolves to null, like a markdown: false child.

    Keep top-level adapter imports browser-safe: adapters run in islands too. Browser builds remove loader handlers, Markdown projections, and their exclusive imports, but retain response schemas.

    Declare loader responses

    #

    An adapter may define a bounded server loader for data that is not in the entry itself. Use a loader object to validate the data intended for the page's recipient:

    import { z } from "brix/zod";
    
    export const ArticleAdapter = createAdapter({
      contentType: "article",
      loader: {
        response: z.strictObject({
          related: z.array(z.strictObject({ title: z.string(), href: z.string() })),
        }),
        handler: async (entry, c, signal) => {
          const { loadRelatedCards } = await import("./related.server.ts");
          return { related: await loadRelatedCards(entry, c, signal) };
        },
      },
      preview: { data: { related: [] } },
      component: ({ loaded }) => {
        if (loaded.status === "pending") return <p role="status">Loading related cards…</p>;
        if (loaded.status === "error") return <p>Related cards unavailable</p>;
        return <RelatedCards cards={loaded.data.related} />;
      },
    });
    

    loadRelatedCards and RelatedCards are application code. The loader object must contain response and an inline async handler; spreads, computed keys, and method shorthand are not supported, nor are function-style loaders. The handler receives (entry, context, signal): dynamically import server-only code inside it and pass signal to downstream requests. Every loader adapter must also declare preview.data, a deterministic fixture used by Live Preview and Storybook; TypeScript rejects a loader without it. Keep compact card mappings: they describe the intended response and reduce payload size.

    Visual components receive { status: "pending" } | { status: "ok", data: T } | { status: "error", reason: "failed" | "timeout" }. Handle all three states in the same component; there is no separate pending callback. During SSR Brix awaits the loader before invoking the component, so pending is only a browser state. The Loaded<T> type passed to Markdown has only the two settled states.

    Handlers return schema input; loaded.data in visual and Markdown callbacks is inferred from schema output. Brix JSON-normalizes the result before validating it. Invalid or non-serializable data becomes { status: "error", reason: "failed" }, without rejected data or validation diagnostics in hydration payloads. Timeouts remain reason: "timeout". Failed results are not retried within the preparation.

    Validated JSON input is transported unchanged. For example, z.string().transform(Number) sends a string and gives callbacks a number. SSR reuses parsed results; hydration parses the original input, not already-transformed output. Schemas and transforms must be synchronous, deterministic, and browser-safe. preview.data and explicit loadedData fixtures supply schema input too and pass through the same validation without calling the handler; treat their result envelopes as immutable and replace them when data changes.

    JSON normalization rejects results larger than 16 MiB of expanded UTF-8 JSON, including repeated references and escaped strings. This is an output bound, not a new cap on trusted SSR entry-graph traversal. Serialization checks the loader deadline; parsing and validation check it on return. Late asynchronous completions are not serialized. Failures never silently truncate content.

    Validation is not redaction or authorization. Loader results used during island hydration are browser-visible, so never return credentials or private data the recipient may not see. Use strict objects at every nested object boundary to reject unexpected fields: plain z.object strips unknown fields only from parsed output, not transported input. Never rely on stripping, preprocessing, or transforms to conceal secrets. Enforce authorization server-side and configure private caching for authenticated responses. A schema alone does not enable the client endpoint or grant remote permission.

    Render polymorphic entries

    #

    Vite generates the registry from every discovered adapter module and exposes renderEntry:

    import { renderEntry } from "brix/contentful/rendering/registry";
    import type { Entry } from "brix/contentful";
    
    export function ContentPage({ entry }: { entry: Entry<unknown> }) {
      return <main>{renderEntry(entry)}</main>;
    }
    

    renderEntry(entry, props?) selects the adapter by the entry's content type and renders nothing for a content type without an adapter. Pass an optional transport props record as the second argument for polymorphic children; directly render a known adapter, such as <HeroAdapter entry={entry} />, when those props should be statically checked.

    Brix wraps every server render in the generated registry and loader preparation, so pages and islands need no provider. Outside the generated registry, for example in a component test or a library that ships its own adapters, build the registry yourself:

    import type { Entry } from "brix/contentful";
    import {
      ContentfulRenderingProvider,
      contentfulEntryKey,
      createContentfulRegistry,
      renderContentfulEntry,
      type Loaded,
    } from "brix/contentful/rendering";
    import { ArticleAdapter } from "./Article.adapter.tsx";
    import { HeroAdapter } from "./Hero.adapter.tsx";
    
    const registry = createContentfulRegistry([HeroAdapter, ArticleAdapter]);
    
    export function RenderedArticle({ entry }: { entry: Entry<unknown> }) {
      const loadedData = new Map<string, Loaded<unknown>>([
        [contentfulEntryKey(entry), { status: "ok", data: { related: [] } }],
      ]);
      return (
        <ContentfulRenderingProvider registry={registry} loadedData={loadedData}>
          {renderContentfulEntry(entry, registry)}
        </ContentfulRenderingProvider>
      );
    }
    

    createContentfulRegistry rejects duplicate content types. ContentfulRenderingProvider requires registry; its optional props are loadedData, clientLoading (a resource from createContentfulLoadingResource), and assetsUrl. loadedData is a ReadonlyMap of loader results keyed by contentfulEntryKey(entry), which joins space, environment, locale (* for wildcard-locale reads), content type, and entry ID with :. Values are schema input in a Loaded envelope. renderContentfulEntry(entry, registry, props?) renders without an enclosing provider too, but loader adapters then fail unless their data is prepared. Inside a provider with a different registry, such as the generated one during SSR, it keeps the provider's data, loading, and preview state but resolves the entry and its nested renderEntry calls through the explicit registry. Server and browser renders therefore select the same adapters. isContentfulAdapter recognizes adapter values.

    Explicit loadedData wins per entry; absent keys fall back to SSR preparation or the browser resource. In the browser it overrides the scoped resource for the current generation without fetching or replacing the resource's shared values. A supplied dictionary belongs to the resource generation that first observed it: session reset or failed session discovery invalidates it, even after remount, so it cannot restore stale private data. Supply new authorized data through the resource's reset({ scope, permissions, loadedData }), not by remounting the old provider.

    SSR preparation and hydration

    #

    During HTML SSR, Brix starts and awaits a loader when rendering reaches its adapter, before invoking the consumer component. Nested adapters reached through the supplied renderEntry, including those selected from loader results, work the same way. Brix does not scan raw page props or loader-result graphs for entries that are merely carried but never rendered.

    Preparation is request-local, deduplicated, bounded, cancellable, and deadline-limited. Each page request:

    • runs at most eight loaders concurrently;
    • observes at most 10,000 adapter renders and nests adapters at most 32 levels deep;
    • allows one loader round per nesting level;
    • shares one five-second deadline.

    Traversal overflow fails the render; loader timeouts become Loaded errors.

    Hydration retains results consumed by client-executed adapters plus already-prepared results reachable from emitted island props and client-owned adapter inputs and parsed results. Selection never runs a loader. This scan has no node or depth limit: it is linear in the island props that the page already serializes, so large charts or tables in islands do not fail the render. Brix skips it when no adapter declares a loader. This conservative closure preserves reuse for an adapter first mounted after a click; it does not predict which interactions will happen.

    Available results are those observed when an adapter renders. Unused entries in a server-only provider's loadedData dictionary are not automatically exported, even if an island receives the matching entry in its props. A later mount needs retained observed data, a provider/prepared data reconstructed in the browser, or authorized client loading.

    Server-only adapters, including visible and hidden JSX slots, do not automatically publish their complete loader results. Slots attach their prepared HTML; independent islands inside slots retain their own required results. Effective explicit-provider successes and failures are included; conflicting values for one entry key within one hydration payload fail explicitly during SSR. Page and fragment resources remain isolated. Loaderless adapter inputs still contribute reachable children.

    An adapter first introduced by browser interaction has no loader result unless that entry was prepared during SSR and retained as client-reachable data. Without the opt-in loading policy below, it fails clearly before its consumer component runs, naming the entry and the three ways to supply data. Loaderless adapters receive null; prepared failures remain typed loaded results.

    Authorize client-introduced adapters

    #

    Loaders can run in the browser through the framework-owned POST /_/contentful/load endpoint. This is opt-in: add createContentfulClientLoadingIntegration from the server-only brix/contentful/server subpath to defineBrixServer(brix, { integrations }).

    During loading, a subscribed component receives loaded.status === "pending", then the settled result. Declare hooks before conditional returns. Brix preserves the component identity across pending and settled states, including Preview refresh. Keep shared controls in a stable subtree when their DOM state should also survive; changing your returned element type can still replace that DOM node. No loading hook, token, or per-adapter cache is needed.

    Configure the loading policy

    #

    The integration accepts static options or an async request-scoped factory, evaluated lazily once for render-time scope classification or loading/Preview. Keep that factory limited to configuration; establish sessions in middleware, which runs after token verification on loading endpoints. This middleware does not run for page issuance. The page rendering permissions must establish the same session before scope and authorize run, using its own page middleware or application-global session setup. The generated Contentful registry is required. Configure every policy explicitly; page middleware is not inherited by endpoints:

    src/brix.server.ts
    import { createContentfulClientLoadingIntegration } from "brix/contentful/server";
    
    export const brixServer = defineBrixServer(brix, {
      env,
      integrations: [
        createContentfulClientLoadingIntegration({
          audience: "site",
          generation: "v1",
          signingKey: "current",
          keys: permissionKeys,
          middleware: [identifySession],
          scope: (c) => resolveLoadingScope(c),
          authorize: (c, operation) => authorizeLoader(c, operation),
          resolve: (c, { identity, scope }, signal) =>
            resolveCanonicalEntry(c, identity, scope, signal),
        }),
      ],
    });
    

    permissionKeys, session middleware, and the three policy functions are application-owned server code, not Brix defaults:

    • audience, generation, and signingKey — nonempty labels of at most 256 characters without :. Changing generation revokes earlier permissions.
    • keys — a record of Web Crypto CryptoKey values: HMAC SHA-256, at least 256 bits, with verification usage, plus signing usage on the signingKey entry. Import stable secret key material from server bindings; never generate a new key on each request or deployment.
    • middleware — required, possibly empty; runs on the loading endpoints after token verification.
    • scope(c) — the current session's scope.
    • authorize(c, operation) — approves each phase; return false to deny.
    • resolve(c, { identity, scope }, signal) — returns the current authorized canonical entry or null.
    • maxResponseBytes — expanded loader JSON limit; default 1 MiB, positive integer up to 16 MiB.
    • maxUpstreamAttempts — shared upstream attempt budget; default 64, positive safe integer.

    TypeScript cannot infer the server's request context inside the nested factory call, so callback parameters default to Hono's untyped Context. Annotate them, for example createContentfulClientLoadingIntegration(async (c: ServerContext) => policy) with type ServerContext = Context<{ Bindings: Readonly<CoercedEnvSchema> }>, when the callbacks read typed c.env. Adapter loader handlers are typed by the factory instead: createContentfulAdapterFactory<ContentTypeMap, TContext>() passes TContext as the handler's second argument.

    For example, reuse the session helper on each page that issues private grants:

    import { createPageRoute } from "#brix/server";
    
    export const articlePageRoute = createPageRoute(articlePageContract, {
      middleware: [identifySession],
      component: ArticlePage,
      load: loadArticlePage,
    });
    

    articlePageContract, ArticlePage, loadArticlePage, and identifySession are application code. Application-global session middleware is another option, but it runs before endpoint token checks; make repeated session setup request-memoized/idempotent if it is also registered on the endpoint. Brix does not run loading-endpoint middleware on unrelated pages. Cache classification runs at the render boundary even when a conditional island is absent or the page has no islands: private/Preview scope marks HTML private, no-store, while public scope leaves the application's cache policy intact.

    Identities, scopes, and authorization

    #

    The identity contains space, environment, locale, contentType, and entryId. Entries read with locale: "*" have no sys.locale; their identity locale is "*", so resolve should read them again with locale: "*". A scope is { mode: "public", tenant } or { mode: "private" | "preview", tenant, principal, expires }. expires is an absolute Unix timestamp in milliseconds, in the next 24 hours. Scope strings are nonempty, at most 256 characters, and cannot contain :. Match the current session and tenant on every request.

    authorize receives phase, identity, scope, and an optional entry. Approve resolve before any CMS read, and load before executing a handler. issue separately approves browser-visible candidates for signing; seeing an entry must not implicitly authorize a more privileged loader response. The issue entry is a candidate, not proof of canonical content; the load entry has been resolved by the server. resolve must never accept editor or browser snapshots as canonical data. A denied phase returns 403, and a null or mismatched resolved entry returns 404. The browser resource settles a 404 as that entry's { status: "error", reason: "failed" } result. Sibling adapters keep their data, because a deleted or unpublished entry is content state, not a session change.

    The request sends only a signed permission. Handlers receive the new API request context, not the original page parameters. Use getContentfulLoadingContext(c) from brix/contentful/server for the verified identity and scope, and choose the correct locale, tenant, credentials, and data-cache partition. On loading endpoints this context is available to middleware and scope after signature verification. Use its mode to select public/private/Preview policy, but derive the current principal and tenant from the authenticated session; returning the token's scope unchanged is not session validation. On the real-loader Preview page route, middleware and the scope callback both run before any verified identity exists, so the context is undefined in both; select Preview policy from the request path instead. During initial Preview SSR, after the root is resolved, this is the shared preview-root identity, not each concurrent child; use the handler's entry argument for that child's identity. Do not authorize loaders that still depend on page-only context. Handlers must be read operations.

    Grants and browser resources

    #

    Brix signs distinct eligible entries in actually emitted island props and prepared loader results; it does not run their loaders speculatively. Successful remote results can grant same-space, same-environment, same-locale children after policy approval. Only entries whose adapter declares a loader become candidates. Issuance fails explicitly beyond 256 distinct candidates or 256 KiB of permissions instead of emitting partial state; this also applies to page grants. Endpoint grant collection over loader results and saved Preview graphs also fails beyond 10,000 visited objects or depth 32. Page grant collection shares the unbounded hydration scan of emitted props. Only the serialized data view contributes grants. Entries fabricated in browser code or fetched through unrelated APIs receive no implicit permission. Permission candidates are authorized separately: an unopened entry can receive a grant without loading, and a prepared result can hydrate even when remote reloading is denied.

    Committed mounts share requests within the page/fragment resource, with four concurrent requests. Unmounting the last subscriber cancels work. Settled successes and failures are reused without automatic retries. Transport failures and unavailable (404) entries become generic Loaded failures for that entry. Missing, revoked, or unauthorized permissions (401, 403, 409) produce a reload-required diagnostic and discard stale resource data. Subscribed descendants can remain pending while current-generation grant discovery or authorized loader requests can supply their grants. They load only when granted; if that work finishes without granting them (including parent failure), missing permission becomes terminal rather than pending forever. Initial missing-grant errors wait through committed subscription discovery, allowing a child to mount before its granting parent in the same tree. Abandoned renders start no requests; genuine settled loader failures remain cached rather than being retried when new grants arrive.

    Applications changing private sessions without navigation must replace the provider resource or call its reset({ scope, permissions, loadedData }) with the new authorized payload; reset clears old prepared and fetched results and ignores old replies. Pass an application-created resource from createContentfulLoadingResource({ scope, permissions, loadedData?, transport? }) as the provider's clientLoading to own resets or to supply a server-free fixture transport.

    Endpoint limits

    #

    All endpoint responses are no-store; requests must be same-origin application/json POSTs. The effective server request URL must retain the public HTTPS origin behind a TLS proxy. Brix does not trust forwarded headers to bypass this check. On Node (brix start) and generated Lambda, set BRIX_PUBLIC_ORIGIN to the public HTTPS origin; see Node and Lambda deployment.

    • Request bodies are limited to 10 KiB of consumed bytes, independently of Content-Length.
    • Resolution, authorization, and loader work inside the endpoint handler share a five-second monotonic deadline; the browser timeout is ten seconds. Exceeding the deadline produces a timeout.
    • maxResponseBytes bounds expanded loader JSON and maxUpstreamAttempts bounds the shared upstream budget; exceeding either fails the load. Permissions retain their separate 256 KiB limit.

    Configuration, body reading, and application middleware are outside the handler deadline: bound their I/O and enforce a host-level request timeout. Aborting cannot forcibly stop application code that ignores its signal. Grant collection checks cancellation before and after asynchronous authorization/signing so it starts no further grant work after cancellation.

    Share the request budget with native clients

    #

    Native clients opt into the shared budget with request: getContentfulLoadingContext(c)?.request. Use the same object for every client in canonical resolution and handler execution. Create these clients lazily inside resolution/loading, not session middleware: middleware has the verified identity but precedes execution-budget setup. Select source credentials and cache partitions from verified identity/scope, and pass the verified locale to each query. Initial Preview SSR and ordinary page loaders can instead use request: { signal } with the supplied loader/resolver signal.

    Retries count as attempts; the native default is three attempts. Set retry: { maxAttempts: 1, on: [] } when retries are inappropriate. Cache hits and same-request flight joiners consume no additional attempts. Flights do not cross request budgets, but stored values still share through normal cache/source identity. Raw fetches and other clients must pass the scope signal and call its onAttempt?.() before each HTTP attempt or they bypass the budget.

    No JavaScript timer can preempt synchronous application code, getters, toJSON, or schema callbacks; overruns are detected when control returns. Upstream response sizes and noncooperative I/O still need host limits. Prefer compact projections and explicit pagination to loading every card or fanning out over every tag; budget rejection is not a substitute for application query design. Add aggregate rate limits at your host: concurrency limits do not prevent bearer-token replay across requests or instances. Reuse native data caching inside read handlers with the correct partition.

    Permission lifetime

    #

    Public permissions deliberately have no time expiry, so cached and SSG HTML can remain usable. They are bearer permissions, not encrypted data. Keep old verification keys for the supported HTML and open-page lifetime. Removing keys or changing the compatibility generation revokes old grants: coordinate cache invalidation/rebuilds and reload open clients. Keep schemas and handlers compatible with older browser bundles within a generation. Permission does not freeze content: deleted, unpublished, or newly unauthorized entries can become unavailable. Private/preview HTML must remain private, no-store through every edge and proxy. Static hosting still needs the same-origin runtime endpoint; cross-origin transport is not supported.

    Add semantic Markdown

    #

    An adapter's markdown callback runs on the server and returns safe nodes from brix/markdown, synchronously or as a promise, not a string or complete document. It receives the typed entry, readonly extra props, the settled loaded result (or null without a loader), and an awaitable renderEntry. Await child results before passing them to synchronous builders:

    markdown: async ({ entry, renderEntry }) => {
      const children = await Promise.all(entry.fields.children.map((child) => renderEntry(child)));
      return md.fragment(...children.filter((child) => child !== null));
    },
    

    Use markdown: false only for intentionally visual-only nested content; it produces a null nested result. Omitting a projection for an entry that Markdown reaches fails with its content type and identity, and a root marked false fails rather than returning an empty page. Neither omitted nor unsupported projections start a loader.

    Represent the root in a page route whose contract declares representations: ["markdown"], and add the single document wrapper there:

    import { markdownEntry } from "brix/contentful/rendering/registry";
    import { md } from "brix/markdown";
    import { createPageRoute } from "#brix/server";
    
    export const articlePageRoute = createPageRoute(articlePageContract, {
      component: ArticlePage,
      load: async (c, { params }) => ({ entry: await getArticle(c, params.slug) }),
      markdown: async (c, { entry }) => md.document({ body: await markdownEntry(entry, c) }),
    });
    

    In this page-route excerpt, articlePageContract, ArticlePage, and getArticle are application code. getArticle must return the adapter-backed entry in the explicit entry load prop. The Markdown representation then produces one complete document from the same content tree. markdownEntry is available only in server code.

    Markdown loads only the entries explicitly requested by the projection. Unused fields, props, loader results, and Rich Text hyperlinks do not start loaders. Repeated entries share one handler execution, but each projection runs once with its own props; path-local cycles are omitted without confusing shared parallel children for cycles. Calling renderEntry requests work even if its promise is discarded, so always await or return it.

    markdownEntry(entry, c, options) accepts:

    • props — props for the root adapter;
    • signal — the request signal by default;
    • timeoutMs — the loader session deadline, 5000 by default;
    • concurrency — concurrent loader handlers, 8 by default;
    • maxProjectionDepth — 32 by default;
    • maxProjectionNodes — 10000 by default.

    Only handlers occupy concurrency slots, so concurrency one supports nested composition. The deadline spans the whole loader session and stops new handlers after expiry or cancellation. Failures remain settled loaded states for truthful fallback content. Keep external I/O inside loader.handler: arbitrary asynchronous projection promises and CPU work are not preempted by the loader deadline. Apply host request limits.

    Configured private/Preview scopes force private, no-store for HTML and both negotiated and durable Contentful Markdown, even without islands. This is cache classification, not page authorization or automatic data-cache partitioning. New smaller payloads do not revoke grants or erase data from already cached HTML; deployment key/generation and cache-invalidation requirements remain unchanged.

    Project Contentful Rich Text

    #

    Keep visual Rich Text rendering in your application component. For agent-readable output, project the structured document directly rather than converting rendered HTML:

    import { projectContentfulRichText } from "brix/contentful/rendering/markdown";
    
    export const ArticleAdapter = createAdapter({
      contentType: "article",
      markdown: ({ entry, renderEntry }) =>
        projectContentfulRichText(entry.fields.body, { renderEntry }),
      component: ({ entry }) => <Article body={entry.fields.body} />,
    });
    

    Import projection helpers from brix/contentful/rendering/markdown and use them only inside markdown; browser adapter builds remove them. The projector returns a promise of content and awaits embedded entries while preserving order. It supports paragraphs, headings, lists, blockquotes, separators, GFM tables, text marks, safe hyperlinks, assets, and embedded entries. Embedded entries use the adapter registry. Supply getEntryUrl(entry) for entry hyperlinks; when it is omitted or returns null, readable labels remain but Brix invents no destination.

    Content degrades rather than failing when editors publish something Markdown cannot express safely:

    • A hyperlink, entry hyperlink, or asset URL that Brix Markdown rejects (a disallowed scheme, a protocol-relative URL, credentials, a non-absolute HTTP URL, or an invalid host or encoding) keeps its label without a link.
    • Link resolution replaces missing, unpublished, or inaccessible targets with null. Hyperlinks to them keep their labels; embedded entries and assets with null targets are omitted.
    • Underline, superscript, and subscript have no portable Markdown form, so their text is kept without presentation.

    Unknown node types and marks, unsupported placements, malformed targets, raw unresolved Link objects (resolve links before projecting), malformed tables, and documents deeper than 64 levels or larger than 10,000 nodes still fail explicitly.