@contentbit/astro 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 contentbit
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,52 @@
+# @contentbit/astro
+
+Astro renderer for [Content Blocks](https://contentbit.dev): `.astro` components
+for rendering validated documents, with per-block component overrides.
+
+Load content with Astro's built-in `glob()` loader, then parse and validate
+with `@contentbit/core`:
+
+```ts
+// src/content.config.ts
+import { defineCollection } from 'astro:content'
+import { glob } from 'astro/loaders'
+
+export const collections = {
+  articles: defineCollection({
+    loader: glob({ pattern: '**/*.md', base: './content' }),
+  }),
+}
+```
+
+```astro
+---
+import { genericBlocks } from '@contentbit/blocks'
+import { createBlockRegistry, parseDocument, validateDocument } from '@contentbit/core'
+import { ContentBlocks } from '@contentbit/astro/components'
+import { getEntry } from 'astro:content'
+
+const entry = await getEntry('articles', 'example')
+if (!entry?.body) throw new Error('Entry "example" not found.')
+
+const registry = createBlockRegistry().use(genericBlocks())
+const { document } = validateDocument(parseDocument(entry.body), registry)
+---
+
+<ContentBlocks document={document} />
+```
+
+For static pages this runs at build time, so throwing on diagnostics fails the
+build. To validate every content file in CI with `file:line:col` diagnostics,
+run the CLI: `contentbit validate "content/**/*.md"`.
+
+Override any block with your own Astro component via
+`components={{ callout: MyCallout }}`. Overrides receive the block's validated
+props as component props, a reserved `node` prop with the full block node
+(`node.data` holds the parsed content), and the block's nested content via
+`<slot />`.
+
+The default prose pipeline is marked (GFM) with raw HTML escaped — the same
+safe-by-default stance as every other render target. Pass your own
+`renderMarkdown` to opt into raw HTML for trusted content.
+
+Docs: https://contentbit.dev/docs

package/components/ContentBlocks.astro

@@ -0,0 +1,48 @@
+---
+import type { DocumentNode } from '@contentbit/core'
+import type { HtmlBlockRenderer } from '@contentbit/html'
+
+import { genericHtmlRenderers } from '@contentbit/html'
+
+import { defaultRenderMarkdown } from '../dist/markdown.js'
+import RenderNodes from './RenderNodes.astro'
+
+interface Props {
+  /** A validated document: validateDocument(parseDocument(entry.body), registry).document. */
+  document: DocumentNode
+  /**
+   * Per-block Astro component overrides, keyed by block name. An override
+   * receives the block's validated props spread as component props, plus a
+   * reserved `node` prop (the full ValidatedBlockNode); nested content
+   * arrives through the default <slot />. A block prop literally named
+   * "node" is shadowed by the reserved prop.
+   */
+  components?: Record<string, unknown>
+  /** Per-block string renderers, merged over the generic html defaults. */
+  renderers?: Record<string, HtmlBlockRenderer>
+  /** CSS class prefix for default renderers. Default "cb-". */
+  classPrefix?: string
+  /** Prose pipeline. Default: marked (GFM) with raw HTML escaped. */
+  renderMarkdown?: (md: string) => string
+  /** Invalid-block behavior: throw, visible dev box, or escaped body. Default "annotated". */
+  onInvalid?: 'strict' | 'annotated' | 'fallback'
+}
+
+const {
+  document,
+  components = {},
+  renderers,
+  classPrefix = 'cb-',
+  renderMarkdown = defaultRenderMarkdown,
+  onInvalid = 'annotated',
+} = Astro.props
+---
+
+<RenderNodes
+  nodes={document.children}
+  components={components}
+  renderers={{ ...genericHtmlRenderers, ...renderers }}
+  classPrefix={classPrefix}
+  renderMarkdown={renderMarkdown}
+  onInvalid={onInvalid}
+/>

package/components/RenderNodes.astro

@@ -0,0 +1,66 @@
+---
+import type { ContentNode, ValidatedBlockNode } from '@contentbit/core'
+import type { HtmlBlockRenderer } from '@contentbit/html'
+
+import { isValidatedBlock } from '@contentbit/core'
+import { fallbackMarkdown, invalidBlockHtml, unrenderableBlockError } from '@contentbit/html'
+
+import { renderBlockShell } from '../dist/render-block.js'
+
+interface Props {
+  nodes: ContentNode[]
+  components: Record<string, unknown>
+  renderers: Record<string, HtmlBlockRenderer>
+  classPrefix: string
+  renderMarkdown: (md: string) => string
+  onInvalid: 'strict' | 'annotated' | 'fallback'
+}
+
+const { nodes, components, renderers, classPrefix, renderMarkdown, onInvalid } = Astro.props
+const childProps = { components, renderers, classPrefix, renderMarkdown, onInvalid }
+
+type OverrideComponent = (props: Record<string, unknown>) => unknown
+
+type Plan =
+  | { kind: 'html'; html: string }
+  | { kind: 'override'; node: ValidatedBlockNode<unknown>; Component: OverrideComponent }
+  | { kind: 'shell'; parts: string[]; childSlots: ContentNode[][] }
+
+const plans: Plan[] = nodes.map((node) => {
+  if (node.type === 'markdown') return { kind: 'html', html: renderMarkdown(node.value) }
+  if (isValidatedBlock(node)) {
+    const override = components[node.name]
+    if (override) return { kind: 'override', node, Component: override as OverrideComponent }
+    const shell = renderBlockShell(node, { classPrefix, renderMarkdown, renderers })
+    if (shell) return { kind: 'shell', ...shell }
+  }
+  // Not validated, or validated with no renderer and no override. The
+  // invalid-block policy (markup, message, fallback escaping) is shared with
+  // renderToHtml so the two targets cannot drift.
+  if (onInvalid === 'strict') throw unrenderableBlockError(node.name)
+  if (onInvalid === 'annotated') {
+    return { kind: 'html', html: invalidBlockHtml(node, classPrefix) }
+  }
+  return { kind: 'html', html: fallbackMarkdown(node.body) }
+})
+---
+
+{
+  plans.map((plan) => {
+    if (plan.kind === 'html') return <Fragment set:html={plan.html} />
+    if (plan.kind === 'override') {
+      const Override = plan.Component
+      return (
+        <Override {...plan.node.props} node={plan.node}>
+          <Astro.self nodes={plan.node.children} {...childProps} />
+        </Override>
+      )
+    }
+    return plan.parts.map((part, i) => (
+      <>
+        <Fragment set:html={part} />
+        {i < plan.childSlots.length && <Astro.self nodes={plan.childSlots[i]} {...childProps} />}
+      </>
+    ))
+  })
+}

package/components/index.ts

@@ -0,0 +1 @@
+export { default as ContentBlocks } from './ContentBlocks.astro'

package/dist/index.d.ts

@@ -0,0 +1,3 @@
+export { defaultRenderMarkdown } from './markdown.js';
+export { renderBlockShell, type BlockShell, type RenderBlockOptions } from './render-block.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,qBAAqB,EAAE,MAAM,eAAe,CAAA;AACrD,OAAO,EAAE,gBAAgB,EAAE,KAAK,UAAU,EAAE,KAAK,kBAAkB,EAAE,MAAM,mBAAmB,CAAA"}

package/dist/index.js

@@ -0,0 +1,2 @@
+export { defaultRenderMarkdown } from './markdown.js';
+export { renderBlockShell } from './render-block.js';

package/dist/markdown.d.ts

@@ -0,0 +1,3 @@
+/** Default prose pipeline: marked with GFM (its default), raw HTML escaped, synchronous. */
+export declare function defaultRenderMarkdown(source: string): string;
+//# sourceMappingURL=markdown.d.ts.map

package/dist/markdown.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"markdown.d.ts","sourceRoot":"","sources":["../src/markdown.ts"],"names":[],"mappings":"AAgBA,4FAA4F;AAC5F,wBAAgB,qBAAqB,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,CAE5D"}

package/dist/markdown.js

@@ -0,0 +1,18 @@
+import { escapeHtml } from '@contentbit/html';
+import { Marked } from 'marked';
+// marked passes raw HTML through verbatim; every other contentbit target
+// escapes by default, and content often comes from CMS users rather than
+// trusted committers. Escaping the html tokens (block and inline) keeps the
+// default pipeline XSS-safe; pass your own renderMarkdown to opt into raw
+// HTML for trusted content.
+const md = new Marked({
+    renderer: {
+        html({ text }) {
+            return escapeHtml(text);
+        },
+    },
+});
+/** Default prose pipeline: marked with GFM (its default), raw HTML escaped, synchronous. */
+export function defaultRenderMarkdown(source) {
+    return md.parse(source, { async: false });
+}

package/dist/render-block.d.ts

@@ -0,0 +1,21 @@
+import type { ContentNode, ValidatedBlockNode } from '@contentbit/core';
+import type { HtmlBlockRenderer } from '@contentbit/html';
+export interface RenderBlockOptions {
+    classPrefix: string;
+    renderMarkdown: (md: string) => string;
+    renderers: Record<string, HtmlBlockRenderer>;
+}
+export interface BlockShell {
+    /** HTML fragments; childSlots[i] renders between parts[i] and parts[i + 1]. */
+    parts: string[];
+    /** Node groups handed back to Astro for recursive rendering, in output order. */
+    childSlots: ContentNode[][];
+}
+/**
+ * Render one validated block through its string renderer, capturing every
+ * ctx.renderNodes() call as a placeholder so nested content can recurse
+ * through Astro (where component overrides apply). Returns null when no
+ * renderer is registered.
+ */
+export declare function renderBlockShell(node: ValidatedBlockNode<unknown>, opts: RenderBlockOptions): BlockShell | null;
+//# sourceMappingURL=render-block.d.ts.map

package/dist/render-block.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"render-block.d.ts","sourceRoot":"","sources":["../src/render-block.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,WAAW,EAAE,kBAAkB,EAAE,MAAM,kBAAkB,CAAA;AACvE,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,kBAAkB,CAAA;AAIzD,MAAM,WAAW,kBAAkB;IACjC,WAAW,EAAE,MAAM,CAAA;IACnB,cAAc,EAAE,CAAC,EAAE,EAAE,MAAM,KAAK,MAAM,CAAA;IACtC,SAAS,EAAE,MAAM,CAAC,MAAM,EAAE,iBAAiB,CAAC,CAAA;CAC7C;AAED,MAAM,WAAW,UAAU;IACzB,+EAA+E;IAC/E,KAAK,EAAE,MAAM,EAAE,CAAA;IACf,iFAAiF;IACjF,UAAU,EAAE,WAAW,EAAE,EAAE,CAAA;CAC5B;AAOD;;;;;GAKG;AACH,wBAAgB,gBAAgB,CAC9B,IAAI,EAAE,kBAAkB,CAAC,OAAO,CAAC,EACjC,IAAI,EAAE,kBAAkB,GACvB,UAAU,GAAG,IAAI,CA2BnB"}

package/dist/render-block.js

@@ -0,0 +1,39 @@
+import { escapeHtml } from '@contentbit/html';
+// NUL is impossible in renderer output, so it cannot collide with real HTML.
+const slotToken = (i) => `\u0000cb:${i}\u0000`;
+// oxlint-disable-next-line no-control-regex -- NUL is the one byte that cannot appear in renderer output
+const SLOT_RE = /\u0000cb:(\d+)\u0000/g;
+/**
+ * Render one validated block through its string renderer, capturing every
+ * ctx.renderNodes() call as a placeholder so nested content can recurse
+ * through Astro (where component overrides apply). Returns null when no
+ * renderer is registered.
+ */
+export function renderBlockShell(node, opts) {
+    const renderer = opts.renderers[node.name];
+    if (!renderer)
+        return null;
+    const slots = [];
+    const html = renderer(node, {
+        cls: (name) => `${opts.classPrefix}${name}`,
+        escape: escapeHtml,
+        renderMarkdown: opts.renderMarkdown,
+        renderNodes(nodes) {
+            slots.push(nodes);
+            return slotToken(slots.length - 1);
+        },
+    });
+    const parts = [];
+    const childSlots = [];
+    let last = 0;
+    for (const m of html.matchAll(SLOT_RE)) {
+        const slot = slots[Number(m[1])];
+        if (slot === undefined)
+            continue; // token-looking text in real content: leave it literal
+        parts.push(html.slice(last, m.index));
+        childSlots.push(slot);
+        last = m.index + m[0].length;
+    }
+    parts.push(html.slice(last));
+    return { parts, childSlots };
+}

package/package.json

@@ -0,0 +1,57 @@
+{
+  "name": "@contentbit/astro",
+  "version": "0.1.0",
+  "description": "Astro renderer for Content Blocks: .astro components for rendering validated documents, with per-block component overrides.",
+  "keywords": [
+    "astro",
+    "astro-component",
+    "content-blocks",
+    "markdown",
+    "renderer",
+    "withastro"
+  ],
+  "homepage": "https://contentbit.dev",
+  "bugs": "https://github.com/agonist/contentbit/issues",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/agonist/contentbit.git",
+    "directory": "packages/astro"
+  },
+  "files": [
+    "dist",
+    "components"
+  ],
+  "type": "module",
+  "sideEffects": false,
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    },
+    "./components": "./components/index.ts"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.build.json",
+    "test": "pnpm build && vitest run",
+    "test:watch": "vitest"
+  },
+  "dependencies": {
+    "@contentbit/blocks": "workspace:*",
+    "@contentbit/core": "workspace:*",
+    "@contentbit/html": "workspace:*",
+    "marked": "^18.0.5"
+  },
+  "devDependencies": {
+    "@types/node": "^25.9.2",
+    "astro": "^6.4.6",
+    "typescript": "^5.9.3",
+    "vitest": "^4.0.17"
+  },
+  "peerDependencies": {
+    "astro": "^5.0.0 || ^6.0.0"
+  }
+}