@k11k/better-blocks-astro-renderer 0.2.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 k11k-labs
+
+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,332 @@
+<h1 align="center">Better Blocks Astro Renderer</h1>
+
+<p align="center">Native Astro renderer for Strapi v5 Blocks content — supports all standard blocks plus Better Blocks features: color, highlight, text alignment, nested lists, to-do lists, tables, media embeds, image captions, and more. Zero client-side JavaScript.</p>
+
+<p align="center">
+  <a href="https://www.npmjs.com/package/@k11k/better-blocks-astro-renderer">
+    <img alt="npm version" src="https://img.shields.io/npm/v/@k11k/better-blocks-astro-renderer.svg" />
+  </a>
+  <a href="https://www.npmjs.com/package/@k11k/better-blocks-astro-renderer">
+    <img alt="npm downloads" src="https://img.shields.io/npm/dm/@k11k/better-blocks-astro-renderer.svg" />
+  </a>
+  <a href="https://github.com/k11k-labs/better-blocks-astro-renderer/blob/main/LICENSE">
+    <img alt="license" src="https://img.shields.io/npm/l/@k11k/better-blocks-astro-renderer.svg" />
+  </a>
+</p>
+
+<p align="center">
+  <img src="./docs/playground-showcase.png" alt="Strapi editor (left) and rendered output (right)" width="800" />
+</p>
+
+---
+
+## Table of Contents
+
+1. [Why?](#why)
+2. [Compatibility](#compatibility)
+3. [Installation](#installation)
+4. [Usage](#usage)
+5. [Supported Blocks](#supported-blocks)
+6. [Supported Modifiers](#supported-modifiers)
+7. [Custom Renderers](#custom-renderers)
+8. [TypeScript](#typescript)
+9. [Contributing](#contributing)
+10. [License](#license)
+
+---
+
+## Why?
+
+The official Strapi blocks renderers are built for React. If your site is built with [Astro](https://astro.build/), you _can_ render Strapi blocks through the [`@astrojs/react`](https://docs.astro.build/en/guides/integrations-guide/react/) integration — but that pulls React into your build for what is purely presentational content.
+
+This package is a **native Astro renderer**. It renders Strapi v5 Blocks content — including every feature the [Better Blocks](https://github.com/k11k-labs/strapi-plugin-better-blocks) plugin adds (color marks, text alignment, to-do lists, tables, media embeds, and more) — using plain `.astro` components. The output is **static HTML with zero client-side JavaScript**, and math is rendered to a string on the server (see [Math (KaTeX)](#math-katex)).
+
+It is a **drop-in renderer** that handles all Better Blocks features out of the box — no configuration needed.
+
+## Compatibility
+
+| Strapi Version | Renderer Version | Astro Version |
+| -------------- | ---------------- | ------------- |
+| v5.x           | v0.x             | &ge; 4        |
+
+## Installation
+
+```bash
+# Using yarn
+yarn add @k11k/better-blocks-astro-renderer
+
+# Using npm
+npm install @k11k/better-blocks-astro-renderer
+```
+
+**Peer dependencies:** `astro >= 4`
+
+## Usage
+
+```astro
+---
+import { BlocksRenderer } from '@k11k/better-blocks-astro-renderer';
+
+const { blocks } = Astro.props;
+---
+
+<BlocksRenderer content={blocks} />
+```
+
+That's it. All Better Blocks features — colors, tables, to-do lists, media embeds, alignment, and more — work automatically, and the component renders to static HTML (no hydration, no client directive).
+
+A typical page that fetches from Strapi:
+
+```astro
+---
+import { BlocksRenderer, type BlocksContent } from '@k11k/better-blocks-astro-renderer';
+// Import the KaTeX stylesheet once (e.g. in a shared layout) so math displays correctly.
+import 'katex/dist/katex.min.css';
+
+const res = await fetch('https://your-strapi.example.com/api/articles?status=published');
+const { data } = await res.json();
+---
+
+{
+  data.map((article: { content: BlocksContent }) => (
+    <article>
+      <BlocksRenderer content={article.content} />
+    </article>
+  ))
+}
+```
+
+### Math (KaTeX)
+
+Math nodes are rendered with [KaTeX](https://katex.org/) — inline math becomes a `<span class="katex-inline">` and block math a `<div class="katex-block">`. Rendering happens via `katex.renderToString` on the server, so it works during SSR and static builds with **no client-side hydration step**.
+
+KaTeX needs its stylesheet to display correctly. Import it **once** in your app (for example in a shared layout):
+
+```astro
+---
+import 'katex/dist/katex.min.css';
+---
+```
+
+`katex` ships as a dependency of this package, so the stylesheet resolves without a separate install. If KaTeX fails to parse a formula, the renderer falls back to the raw LaTeX source instead of crashing.
+
+## Supported Blocks
+
+| Block                           | Default element     | Source                      |
+| ------------------------------- | ------------------- | --------------------------- |
+| `paragraph`                     | `<p>`               | Strapi core                 |
+| `heading` (1&ndash;6)           | `<h1>`&ndash;`<h6>` | Strapi core                 |
+| `list` (ordered/unordered/todo) | `<ol>` / `<ul>`     | Strapi core + Better Blocks |
+| `list-item`                     | `<li>`              | Strapi core                 |
+| `link`                          | `<a>`               | Strapi core                 |
+| `quote`                         | `<blockquote>`      | Strapi core                 |
+| `code`                          | `<pre><code>`       | Strapi core                 |
+| `image`                         | `<figure><img>`     | Strapi core                 |
+| `horizontal-line`               | `<hr>`              | Better Blocks               |
+| `table`                         | `<table>`           | Better Blocks               |
+| `media-embed`                   | `<iframe>` (16:9)   | Better Blocks               |
+| `math` (inline/block)           | `<span>` / `<div>`  | Better Blocks               |
+
+### Block properties
+
+| Property      | Applies to                | Description                                           |
+| ------------- | ------------------------- | ----------------------------------------------------- |
+| `textAlign`   | paragraph, heading, quote | Text alignment (`left`, `center`, `right`, `justify`) |
+| `lineHeight`  | paragraph, heading, quote | CSS line-height value (e.g. `1.5`, `2.0`)             |
+| `indent`      | paragraph, heading, quote | Block indentation level (`marginLeft: N * 2rem`)      |
+| `indentLevel` | list                      | Cycling list-style-type per nesting depth             |
+| `format`      | list                      | `ordered`, `unordered`, or `todo`                     |
+| `checked`     | list-item (in todo lists) | Checkbox state (`true`/`false`)                       |
+| `target`      | link                      | `_blank` for new-tab links                            |
+| `rel`         | link                      | `noopener noreferrer` for new-tab links               |
+| `caption`     | image                     | Text displayed below the image                        |
+| `imageAlign`  | image                     | Image alignment (`left`, `center`, `right`)           |
+| `url`         | media-embed               | Embed URL (YouTube/Vimeo iframe src)                  |
+| `originalUrl` | media-embed               | Original user-provided URL                            |
+| `format`      | math                      | `inline` (`<span>`) or `block` (`<div>`)              |
+| `value`       | math                      | LaTeX source rendered with KaTeX                      |
+
+## Supported Modifiers
+
+| Modifier          | Default element                   | Source        |
+| ----------------- | --------------------------------- | ------------- |
+| `bold`            | `<strong>`                        | Strapi core   |
+| `italic`          | `<em>`                            | Strapi core   |
+| `underline`       | `<span>`                          | Strapi core   |
+| `strikethrough`   | `<del>`                           | Strapi core   |
+| `code`            | `<code>`                          | Strapi core   |
+| `uppercase`       | `<span style="text-transform">`   | Better Blocks |
+| `superscript`     | `<sup>`                           | Better Blocks |
+| `subscript`       | `<sub>`                           | Better Blocks |
+| `color`           | `<span style="color">`            | Better Blocks |
+| `backgroundColor` | `<span style="background-color">` | Better Blocks |
+| `fontFamily`      | `<span style="font-family">`      | Better Blocks |
+| `fontSize`        | `<span style="font-size">`        | Better Blocks |
+
+## Custom Renderers
+
+Override any block type or text modifier with your own Astro component. Pass a map of type → component via the `blocks` and `modifiers` props. Each custom component receives its props through `Astro.props` and its inner content through the default `<slot />`.
+
+### Custom block renderers
+
+```astro
+---
+import { BlocksRenderer } from '@k11k/better-blocks-astro-renderer';
+import MyParagraph from '../components/MyParagraph.astro';
+import MyImage from '../components/MyImage.astro';
+import MyTable from '../components/MyTable.astro';
+
+const { blocks } = Astro.props;
+---
+
+<BlocksRenderer
+  content={blocks}
+  blocks={{
+    paragraph: MyParagraph,
+    image: MyImage,
+    table: MyTable,
+  }}
+/>
+```
+
+```astro
+---
+// src/components/MyImage.astro
+const { image, caption, imageAlign } = Astro.props;
+---
+
+<figure style={{ textAlign: imageAlign }}>
+  <img src={image.url} alt={image.alternativeText || ''} loading="lazy" />
+  {caption && <figcaption>{caption}</figcaption>}
+</figure>
+```
+
+The props each custom block component receives:
+
+| Block                                                      | Props (plus `<slot />` for children where applicable)         |
+| ---------------------------------------------------------- | ------------------------------------------------------------- |
+| `paragraph`                                                | `{ style?}`                                                   |
+| `heading`                                                  | `{ level: 1–6; style? }`                                      |
+| `list`                                                     | `{ format: 'ordered' \| 'unordered' \| 'todo'; indentLevel }` |
+| `list-item`                                                | `{ checked? }`                                                |
+| `link`                                                     | `{ url; target?; rel? }`                                      |
+| `quote`                                                    | `{ style? }`                                                  |
+| `code`                                                     | `{ plainText }` (also via `<slot />`)                         |
+| `image`                                                    | `{ image; caption?; imageAlign? }` (no slot)                  |
+| `horizontal-line`                                          | _none_                                                        |
+| `table` / `table-row` / `table-cell` / `table-header-cell` | children via `<slot />`                                       |
+| `media-embed`                                              | `{ url; originalUrl? }` (no slot)                             |
+| `math`                                                     | `{ formula; inline }` (no slot) — bring your own math engine  |
+
+### Custom modifier renderers
+
+```astro
+---
+import { BlocksRenderer } from '@k11k/better-blocks-astro-renderer';
+import Highlight from '../components/Highlight.astro';
+
+const { blocks } = Astro.props;
+---
+
+<BlocksRenderer content={blocks} modifiers={{ backgroundColor: Highlight }} />
+```
+
+```astro
+---
+// src/components/Highlight.astro
+const { backgroundColor } = Astro.props;
+---
+
+<mark style={{ backgroundColor }}><slot /></mark>
+```
+
+The color/size/font modifiers receive a value prop (`color`, `backgroundColor`, `fontFamily`, `fontSize`); the rest receive only their `<slot />`.
+
+## TypeScript
+
+All types are exported:
+
+```ts
+import type {
+  BlocksContent,
+  BlocksRendererProps,
+  BlockNode,
+  TextNode,
+  LinkNode,
+  ListNode,
+  ListItemNode,
+  ParagraphNode,
+  HeadingNode,
+  QuoteNode,
+  CodeNode,
+  ImageNode,
+  HorizontalLineNode,
+  TableNode,
+  TableRowNode,
+  TableCellNode,
+  TableHeaderCellNode,
+  MediaEmbedNode,
+  MathNode,
+  TextAlign,
+  CustomBlocksConfig,
+  CustomModifiersConfig,
+} from '@k11k/better-blocks-astro-renderer';
+```
+
+## Contributing
+
+Contributions are welcome! The easiest way to get started is with Docker:
+
+```bash
+# Clone the repository
+git clone https://github.com/k11k-labs/better-blocks-astro-renderer.git
+cd better-blocks-astro-renderer
+
+# Start the playground with Docker
+cd playground
+docker compose up
+```
+
+This will start a Strapi v5 instance with the Better Blocks plugin and an Astro app that renders the content — all pre-configured with a showcase article.
+
+- **Strapi admin:** http://localhost:1337/admin (login: `admin@example.com` / `admin12#`)
+- **Astro app:** http://localhost:4321
+
+### Development workflow
+
+1. Edit the `.astro` components in `src/`
+2. The Astro app picks up the change automatically — there is no build step
+
+### Without Docker
+
+```bash
+# Install dependencies (no build step — the renderer ships .astro source)
+yarn install
+
+# Start Strapi
+cd playground/strapi && cp .env.example .env && npm install && npm run dev
+
+# Start the Astro app (in another terminal)
+cd playground/astro-app && npm install && npm run dev
+```
+
+### Running tests
+
+```bash
+yarn test        # Run tests (Astro container API + Vitest)
+yarn test:ts     # Type check (astro check)
+yarn lint        # Check formatting
+```
+
+## Community & Support
+
+- [GitHub Issues](https://github.com/k11k-labs/better-blocks-astro-renderer/issues) &mdash; Bug reports and feature requests
+
+## Related
+
+- [@k11k/better-blocks-react-renderer](https://github.com/k11k-labs/better-blocks-react-renderer) &mdash; React renderer with the same Better Blocks support
+- [@k11k/strapi-plugin-better-blocks](https://github.com/k11k-labs/strapi-plugin-better-blocks) &mdash; Strapi plugin that extends the Blocks editor with colors, tables, to-do lists, media embeds, and more
+
+## License
+
+[MIT License](LICENSE) &copy; [k11k-labs](https://github.com/k11k-labs)

package/env.d.ts

@@ -0,0 +1 @@
+/// <reference types="astro/client" />

package/index.ts

@@ -0,0 +1,29 @@
+export { default as BlocksRenderer } from './src/BlocksRenderer.astro';
+
+export type {
+  BlocksContent,
+  BlocksRendererProps,
+  BlockNode,
+  TextNode,
+  LinkNode,
+  InlineNode,
+  ParagraphNode,
+  HeadingNode,
+  ListNode,
+  ListItemNode,
+  QuoteNode,
+  CodeNode,
+  ImageNode,
+  HorizontalLineNode,
+  TableNode,
+  TableRowNode,
+  TableCellNode,
+  TableHeaderCellNode,
+  MediaEmbedNode,
+  MathNode,
+  TextAlign,
+  StyleValue,
+  CustomBlocksConfig,
+  CustomModifiersConfig,
+  AstroComponentFactory,
+} from './src/types';

package/package.json

@@ -0,0 +1,86 @@
+{
+  "name": "@k11k/better-blocks-astro-renderer",
+  "version": "0.2.0",
+  "description": "Astro renderer for Strapi v5 Blocks content with full Better Blocks plugin support — colors, tables, to-do lists, media embeds, alignment, and more. Native Astro components, zero client-side JavaScript.",
+  "type": "module",
+  "types": "./index.ts",
+  "exports": {
+    ".": {
+      "types": "./index.ts",
+      "default": "./index.ts"
+    },
+    "./BlocksRenderer.astro": "./src/BlocksRenderer.astro",
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "src",
+    "index.ts",
+    "env.d.ts"
+  ],
+  "scripts": {
+    "build": "astro check",
+    "lint": "prettier --check .",
+    "format": "prettier --write .",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "test:ts": "astro check",
+    "prepare": "husky || true"
+  },
+  "lint-staged": {
+    "*.{js,jsx,ts,tsx,astro,json,md,yml,yaml,css}": "prettier --write"
+  },
+  "dependencies": {
+    "katex": "^0.16.11"
+  },
+  "peerDependencies": {
+    "astro": ">=4.0.0"
+  },
+  "devDependencies": {
+    "@astrojs/check": "^0.9.4",
+    "@changesets/changelog-github": "^0.6.0",
+    "@changesets/cli": "^2.30.0",
+    "@types/katex": "^0.16.7",
+    "astro": "^5.0.0",
+    "husky": "^9.1.7",
+    "linkedom": "^0.18.12",
+    "lint-staged": "^16.3.3",
+    "prettier": "^3.4.2",
+    "prettier-plugin-astro": "^0.14.1",
+    "typescript": "^5.7.2",
+    "vitest": "^3.0.0"
+  },
+  "keywords": [
+    "strapi",
+    "strapi-v5",
+    "blocks",
+    "blocks-renderer",
+    "astro",
+    "renderer",
+    "rich-text",
+    "better-blocks",
+    "color",
+    "highlight",
+    "text-color",
+    "background-color",
+    "katex",
+    "latex",
+    "math",
+    "cms",
+    "headless-cms"
+  ],
+  "license": "MIT",
+  "author": "k11k-labs",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/k11k-labs/better-blocks-astro-renderer.git"
+  },
+  "bugs": {
+    "url": "https://github.com/k11k-labs/better-blocks-astro-renderer/issues"
+  },
+  "homepage": "https://github.com/k11k-labs/better-blocks-astro-renderer#readme",
+  "engines": {
+    "node": ">=20.0.0 <=24.x.x",
+    "npm": ">=6.0.0"
+  },
+  "packageManager": "yarn@1.22.22"
+}

package/src/Block.astro

@@ -0,0 +1,156 @@
+---
+import type { BlockNode, CustomBlocksConfig, CustomModifiersConfig } from './types';
+import Inline from './Inline.astro';
+import List from './List.astro';
+import Table from './Table.astro';
+import Math from './Math.astro';
+import { getBlockStyle, getPlainText } from './utils';
+
+interface Props {
+  block: BlockNode;
+  blocks?: CustomBlocksConfig;
+  modifiers?: CustomModifiersConfig;
+}
+
+const { block, blocks, modifiers } = Astro.props;
+
+const ParagraphComp = blocks?.paragraph as any;
+const HeadingComp = blocks?.heading as any;
+const QuoteComp = blocks?.quote as any;
+const CodeComp = blocks?.code as any;
+const ImageComp = blocks?.image as any;
+const HrComp = blocks?.['horizontal-line'] as any;
+const EmbedComp = blocks?.['media-embed'] as any;
+---
+
+{
+  block.type === 'paragraph' && (
+    <Fragment>
+      {(() => {
+        const style = getBlockStyle(block);
+        return ParagraphComp ? (
+          <ParagraphComp style={style}>
+            <Inline nodes={block.children} blocks={blocks} modifiers={modifiers} />
+          </ParagraphComp>
+        ) : (
+          <p style={style}>
+            <Inline nodes={block.children} blocks={blocks} modifiers={modifiers} />
+          </p>
+        );
+      })()}
+    </Fragment>
+  )
+}
+
+{
+  block.type === 'heading' && (
+    <Fragment>
+      {(() => {
+        const style = getBlockStyle(block);
+        const HeadingTag = `h${block.level}` as any;
+        return HeadingComp ? (
+          <HeadingComp level={block.level} style={style}>
+            <Inline nodes={block.children} blocks={blocks} modifiers={modifiers} />
+          </HeadingComp>
+        ) : (
+          <HeadingTag style={style}>
+            <Inline nodes={block.children} blocks={blocks} modifiers={modifiers} />
+          </HeadingTag>
+        );
+      })()}
+    </Fragment>
+  )
+}
+
+{block.type === 'list' && <List node={block} blocks={blocks} modifiers={modifiers} />}
+
+{
+  block.type === 'quote' && (
+    <Fragment>
+      {(() => {
+        const style = getBlockStyle(block);
+        return QuoteComp ? (
+          <QuoteComp style={style}>
+            <Inline nodes={block.children} blocks={blocks} modifiers={modifiers} />
+          </QuoteComp>
+        ) : (
+          <blockquote style={style}>
+            <Inline nodes={block.children} blocks={blocks} modifiers={modifiers} />
+          </blockquote>
+        );
+      })()}
+    </Fragment>
+  )
+}
+
+{
+  block.type === 'code' && (
+    <Fragment>
+      {(() => {
+        const plainText = getPlainText(block.children);
+        return CodeComp ? (
+          <CodeComp plainText={plainText}>{plainText}</CodeComp>
+        ) : (
+          <pre>
+            <code>{plainText}</code>
+          </pre>
+        );
+      })()}
+    </Fragment>
+  )
+}
+
+{
+  block.type === 'image' && (
+    <Fragment>
+      {(() => {
+        const align = block.imageAlign || 'center';
+        return ImageComp ? (
+          <ImageComp image={block.image} caption={block.caption} imageAlign={block.imageAlign} />
+        ) : (
+          <figure style={{ textAlign: align }}>
+            <img
+              src={block.image.url}
+              alt={block.image.alternativeText || ''}
+              width={block.image.width}
+              height={block.image.height}
+            />
+            {block.caption && <figcaption>{block.caption}</figcaption>}
+          </figure>
+        );
+      })()}
+    </Fragment>
+  )
+}
+
+{block.type === 'horizontal-line' && <Fragment>{HrComp ? <HrComp /> : <hr />}</Fragment>}
+
+{block.type === 'table' && <Table node={block} blocks={blocks} modifiers={modifiers} />}
+
+{
+  block.type === 'media-embed' && (
+    <Fragment>
+      {EmbedComp ? (
+        <EmbedComp url={block.url} originalUrl={block.originalUrl} />
+      ) : (
+        <div style={{ position: 'relative', paddingBottom: '56.25%', height: '0' }}>
+          <iframe
+            src={block.url}
+            style={{
+              position: 'absolute',
+              top: '0',
+              left: '0',
+              width: '100%',
+              height: '100%',
+              border: '0',
+            }}
+            allowfullscreen
+            title="Embedded media"
+          />
+        </div>
+      )}
+    </Fragment>
+  )
+}
+
+{block.type === 'math' && <Math node={block} blocks={blocks} />}

package/src/BlocksRenderer.astro

@@ -0,0 +1,11 @@
+---
+import type { BlocksRendererProps } from './types';
+import Block from './Block.astro';
+
+type Props = BlocksRendererProps;
+
+const { content, blocks, modifiers } = Astro.props;
+const isValid = Array.isArray(content) && content.length > 0;
+---
+
+{isValid && content.map((block) => <Block block={block} blocks={blocks} modifiers={modifiers} />)}

package/src/Inline.astro

@@ -0,0 +1,41 @@
+---
+import type { CustomBlocksConfig, CustomModifiersConfig, InlineNode } from './types';
+import Text from './Text.astro';
+import Math from './Math.astro';
+
+interface Props {
+  nodes: InlineNode[];
+  blocks?: CustomBlocksConfig;
+  modifiers?: CustomModifiersConfig;
+}
+
+const { nodes, blocks, modifiers } = Astro.props;
+const LinkComp = blocks?.link as any;
+---
+
+{
+  nodes.map((child) => {
+    if (child.type === 'text') {
+      return <Text node={child} modifiers={modifiers} />;
+    }
+    if (child.type === 'math') {
+      return <Math node={child} blocks={blocks} />;
+    }
+    if (child.type === 'link') {
+      return LinkComp ? (
+        <LinkComp url={child.url} target={child.target} rel={child.rel}>
+          {child.children.map((textNode) => (
+            <Text node={textNode} modifiers={modifiers} />
+          ))}
+        </LinkComp>
+      ) : (
+        <a href={child.url} target={child.target} rel={child.rel}>
+          {child.children.map((textNode) => (
+            <Text node={textNode} modifiers={modifiers} />
+          ))}
+        </a>
+      );
+    }
+    return null;
+  })
+}

package/src/List.astro

@@ -0,0 +1,49 @@
+---
+import type { CustomBlocksConfig, CustomModifiersConfig, ListNode, StyleValue } from './types';
+import ListItem from './ListItem.astro';
+import { getListStyleType } from './utils';
+
+interface Props {
+  node: ListNode;
+  blocks?: CustomBlocksConfig;
+  modifiers?: CustomModifiersConfig;
+}
+
+const { node, blocks, modifiers } = Astro.props;
+const indentLevel = node.indentLevel || 0;
+const isTodo = node.format === 'todo';
+const ListComp = blocks?.list as any;
+
+// Pick the wrapper element + props; the children map is identical across all
+// cases, so render it once as slot content.
+let Wrapper: unknown;
+let wrapperProps: Record<string, unknown> = {};
+if (ListComp) {
+  Wrapper = ListComp;
+  wrapperProps = { format: node.format, indentLevel };
+} else if (isTodo) {
+  Wrapper = 'ul';
+  const style: StyleValue = {
+    listStyle: 'none',
+    paddingLeft: indentLevel > 0 ? '1.5em' : '0',
+  };
+  wrapperProps = { style };
+} else {
+  Wrapper = node.format === 'ordered' ? 'ol' : 'ul';
+  const listStyleType = getListStyleType(node.format as 'ordered' | 'unordered', indentLevel);
+  wrapperProps = { style: { listStyleType } satisfies StyleValue };
+}
+const Tag = Wrapper as any;
+---
+
+<Tag {...wrapperProps}>
+  {
+    node.children.map((child) =>
+      child.type === 'list-item' ? (
+        <ListItem node={child} isTodo={isTodo} blocks={blocks} modifiers={modifiers} />
+      ) : (
+        <Astro.self node={child} blocks={blocks} modifiers={modifiers} />
+      )
+    )
+  }
+</Tag>

package/src/ListItem.astro

@@ -0,0 +1,34 @@
+---
+import type { CustomBlocksConfig, CustomModifiersConfig, ListItemNode } from './types';
+import Inline from './Inline.astro';
+
+interface Props {
+  node: ListItemNode;
+  isTodo: boolean;
+  blocks?: CustomBlocksConfig;
+  modifiers?: CustomModifiersConfig;
+}
+
+const { node, isTodo, blocks, modifiers } = Astro.props;
+const ListItemComp = blocks?.['list-item'] as any;
+const checked = node.checked ?? false;
+---
+
+{
+  ListItemComp ? (
+    <ListItemComp checked={isTodo ? node.checked : undefined}>
+      <Inline nodes={node.children} blocks={blocks} modifiers={modifiers} />
+    </ListItemComp>
+  ) : isTodo ? (
+    <li style={{ listStyle: 'none' }}>
+      <input type="checkbox" checked={checked} readonly style={{ marginRight: '0.5em' }} />
+      <span style={checked ? { textDecoration: 'line-through', opacity: '0.6' } : undefined}>
+        <Inline nodes={node.children} blocks={blocks} modifiers={modifiers} />
+      </span>
+    </li>
+  ) : (
+    <li>
+      <Inline nodes={node.children} blocks={blocks} modifiers={modifiers} />
+    </li>
+  )
+}

package/src/Math.astro

@@ -0,0 +1,42 @@
+---
+import katex from 'katex';
+import type { CustomBlocksConfig, MathNode } from './types';
+
+interface Props {
+  node: MathNode;
+  blocks?: CustomBlocksConfig;
+}
+
+const { node, blocks } = Astro.props;
+
+const isBlock = node.format === 'block';
+const formula = node.value ?? '';
+const MathComp = blocks?.math;
+
+const Tag = isBlock ? 'div' : 'span';
+const className = isBlock ? 'katex-block' : 'katex-inline';
+
+// KaTeX renders to an HTML string on the server (no client hydration needed).
+// With `throwOnError: false` it renders parse errors inline instead of throwing;
+// the try/catch is a last-resort guard that falls back to the raw LaTeX source.
+let html: string | null = null;
+if (!MathComp) {
+  try {
+    html = katex.renderToString(formula, { displayMode: isBlock, throwOnError: false });
+  } catch {
+    html = null;
+  }
+}
+const Wrapper = Tag as any;
+const Custom = MathComp as any;
+---
+
+{
+  Custom ? (
+    <Custom formula={formula} inline={!isBlock} />
+  ) : html !== null ? (
+    <Wrapper class={className} set:html={html} />
+  ) : (
+    <Wrapper class={className}>{formula}</Wrapper>
+  )
+}

package/src/Table.astro

@@ -0,0 +1,45 @@
+---
+import type { CustomBlocksConfig, CustomModifiersConfig, TableNode } from './types';
+import Inline from './Inline.astro';
+
+interface Props {
+  node: TableNode;
+  blocks?: CustomBlocksConfig;
+  modifiers?: CustomModifiersConfig;
+}
+
+const { node, blocks, modifiers } = Astro.props;
+const TableComp = blocks?.table as any;
+const RowComp = blocks?.['table-row'] as any;
+const CellComp = blocks?.['table-cell'] as any;
+const HeaderCellComp = blocks?.['table-header-cell'] as any;
+---
+
+{
+  (() => {
+    const rows = node.children.map((row) => {
+      const cells = row.children.map((cell) => {
+        const isHeader = cell.type === 'table-header-cell';
+        const content = <Inline nodes={cell.children} blocks={blocks} modifiers={modifiers} />;
+
+        if (isHeader && HeaderCellComp) {
+          return <HeaderCellComp>{content}</HeaderCellComp>;
+        }
+        if (!isHeader && CellComp) {
+          return <CellComp>{content}</CellComp>;
+        }
+        const CellTag = isHeader ? 'th' : 'td';
+        return <CellTag>{content}</CellTag>;
+      });
+      return RowComp ? <RowComp>{cells}</RowComp> : <tr>{cells}</tr>;
+    });
+
+    return TableComp ? (
+      <TableComp>{rows}</TableComp>
+    ) : (
+      <table>
+        <tbody>{rows}</tbody>
+      </table>
+    );
+  })()
+}

package/src/Text.astro

@@ -0,0 +1,45 @@
+---
+import type { CustomModifiersConfig, TextNode } from './types';
+import { buildTextMarks, getDefaultMarkRender, getModifierProps, type Mark } from './utils';
+
+interface Props {
+  node: TextNode;
+  modifiers?: CustomModifiersConfig;
+  /** Remaining marks to apply, outer → inner. Built from `node` on first call. */
+  marks?: Mark[];
+}
+
+const { node, modifiers, marks } = Astro.props;
+const activeMarks = marks ?? buildTextMarks(node);
+const hasMarks = activeMarks.length > 0;
+
+const [current, ...rest] = activeMarks;
+
+// Choose the wrapper for the outermost remaining mark: a custom modifier
+// component if one is configured, otherwise the default HTML element. The inner
+// content recurses through the remaining marks via `Astro.self`.
+let Tag: unknown = null;
+let tagProps: Record<string, unknown> = {};
+if (hasMarks) {
+  const Custom = modifiers?.[current.name as keyof CustomModifiersConfig];
+  if (Custom) {
+    Tag = Custom;
+    tagProps = getModifierProps(current);
+  } else {
+    const { tag, style } = getDefaultMarkRender(current);
+    Tag = tag;
+    tagProps = style ? { style } : {};
+  }
+}
+const Wrapper = Tag as any;
+---
+
+{
+  hasMarks ? (
+    <Wrapper {...tagProps}>
+      <Astro.self node={node} modifiers={modifiers} marks={rest} />
+    </Wrapper>
+  ) : (
+    node.text
+  )
+}

package/src/types.ts

@@ -0,0 +1,229 @@
+// ── Text & Inline Nodes ──────────────────────────────────────────────
+
+export type TextNode = {
+  type: 'text';
+  text: string;
+  bold?: boolean;
+  italic?: boolean;
+  underline?: boolean;
+  strikethrough?: boolean;
+  code?: boolean;
+  uppercase?: boolean;
+  superscript?: boolean;
+  subscript?: boolean;
+  color?: string;
+  backgroundColor?: string;
+  fontFamily?: string;
+  fontSize?: string;
+};
+
+export type LinkNode = {
+  type: 'link';
+  url: string;
+  target?: '_blank' | '_self';
+  rel?: string;
+  children: TextNode[];
+};
+
+export type MathNode = {
+  type: 'math';
+  format: 'inline' | 'block';
+  value: string;
+  children: [{ type: 'text'; text: '' }];
+};
+
+export type InlineNode = TextNode | LinkNode | MathNode;
+
+// ── Text Alignment ──────────────────────────────────────────────────
+
+export type TextAlign = 'left' | 'center' | 'right' | 'justify';
+
+// ── Block Nodes ──────────────────────────────────────────────────────
+
+export type ListItemNode = {
+  type: 'list-item';
+  checked?: boolean;
+  children: InlineNode[];
+};
+
+export type ParagraphNode = {
+  type: 'paragraph';
+  textAlign?: TextAlign;
+  lineHeight?: string;
+  indent?: number;
+  children: InlineNode[];
+};
+
+export type HeadingNode = {
+  type: 'heading';
+  level: 1 | 2 | 3 | 4 | 5 | 6;
+  textAlign?: TextAlign;
+  lineHeight?: string;
+  indent?: number;
+  children: InlineNode[];
+};
+
+export type ListNode = {
+  type: 'list';
+  format: 'ordered' | 'unordered' | 'todo';
+  indentLevel?: number;
+  children: (ListItemNode | ListNode)[];
+};
+
+export type QuoteNode = {
+  type: 'quote';
+  textAlign?: TextAlign;
+  lineHeight?: string;
+  indent?: number;
+  children: InlineNode[];
+};
+
+export type CodeNode = {
+  type: 'code';
+  children: InlineNode[];
+};
+
+export type ImageNode = {
+  type: 'image';
+  image: {
+    url: string;
+    alternativeText?: string | null;
+    width?: number;
+    height?: number;
+  };
+  caption?: string;
+  imageAlign?: 'left' | 'center' | 'right';
+  children: [{ type: 'text'; text: '' }];
+};
+
+export type HorizontalLineNode = {
+  type: 'horizontal-line';
+  children: [{ type: 'text'; text: '' }];
+};
+
+export type TableCellNode = {
+  type: 'table-cell';
+  children: InlineNode[];
+};
+
+export type TableHeaderCellNode = {
+  type: 'table-header-cell';
+  children: InlineNode[];
+};
+
+export type TableRowNode = {
+  type: 'table-row';
+  children: (TableCellNode | TableHeaderCellNode)[];
+};
+
+export type TableNode = {
+  type: 'table';
+  children: TableRowNode[];
+};
+
+export type MediaEmbedNode = {
+  type: 'media-embed';
+  url: string;
+  originalUrl?: string;
+  children: [{ type: 'text'; text: '' }];
+};
+
+export type BlockNode =
+  | ParagraphNode
+  | HeadingNode
+  | ListNode
+  | QuoteNode
+  | CodeNode
+  | ImageNode
+  | HorizontalLineNode
+  | TableNode
+  | MediaEmbedNode
+  | MathNode;
+
+export type BlocksContent = BlockNode[];
+
+// ── Style ────────────────────────────────────────────────────────────
+
+/**
+ * Inline style value accepted by Astro elements — either a CSS string or a
+ * record of property/value pairs (Astro serializes the object to a string).
+ */
+export type StyleValue = string | Record<string, string | number | undefined>;
+
+// ── Custom Renderers Config ──────────────────────────────────────────
+
+/**
+ * Any Astro component — the default export of a `.astro` file (or any
+ * framework component Astro can render). Custom renderers receive their props
+ * via `Astro.props` and their inner content via the default `<slot />`.
+ */
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+export type AstroComponentFactory = (...args: any[]) => any;
+
+/**
+ * Map of block type → custom Astro component. Each component receives the props
+ * documented below plus, where applicable, its rendered children via `<slot />`.
+ *
+ * - `paragraph` — `{ style?: StyleValue }`
+ * - `heading` — `{ level: 1 | 2 | 3 | 4 | 5 | 6; style?: StyleValue }`
+ * - `list` — `{ format: 'ordered' | 'unordered' | 'todo'; indentLevel: number }`
+ * - `list-item` — `{ checked?: boolean }`
+ * - `link` — `{ url: string; target?: string; rel?: string }`
+ * - `quote` — `{ style?: StyleValue }`
+ * - `code` — `{ plainText: string }` (also available via `<slot />`)
+ * - `image` — `{ image; caption?: string; imageAlign?: 'left' | 'center' | 'right' }`
+ * - `horizontal-line` — no props
+ * - `table` / `table-row` / `table-cell` / `table-header-cell` — children via `<slot />`
+ * - `media-embed` — `{ url: string; originalUrl?: string }`
+ * - `math` — `{ formula: string; inline: boolean }`
+ */
+export type CustomBlocksConfig = Partial<{
+  paragraph: AstroComponentFactory;
+  heading: AstroComponentFactory;
+  list: AstroComponentFactory;
+  'list-item': AstroComponentFactory;
+  link: AstroComponentFactory;
+  quote: AstroComponentFactory;
+  code: AstroComponentFactory;
+  image: AstroComponentFactory;
+  'horizontal-line': AstroComponentFactory;
+  table: AstroComponentFactory;
+  'table-row': AstroComponentFactory;
+  'table-cell': AstroComponentFactory;
+  'table-header-cell': AstroComponentFactory;
+  'media-embed': AstroComponentFactory;
+  math: AstroComponentFactory;
+}>;
+
+/**
+ * Map of text modifier (mark) → custom Astro component. Each component receives
+ * its inner content via the default `<slot />`. The color/size/font modifiers
+ * additionally receive a value prop:
+ *
+ * - `color` — `{ color: string }`
+ * - `backgroundColor` — `{ backgroundColor: string }`
+ * - `fontFamily` — `{ fontFamily: string }`
+ * - `fontSize` — `{ fontSize: string }`
+ */
+export type CustomModifiersConfig = Partial<{
+  bold: AstroComponentFactory;
+  italic: AstroComponentFactory;
+  underline: AstroComponentFactory;
+  strikethrough: AstroComponentFactory;
+  code: AstroComponentFactory;
+  uppercase: AstroComponentFactory;
+  superscript: AstroComponentFactory;
+  subscript: AstroComponentFactory;
+  color: AstroComponentFactory;
+  backgroundColor: AstroComponentFactory;
+  fontFamily: AstroComponentFactory;
+  fontSize: AstroComponentFactory;
+}>;
+
+// ── Component Props ──────────────────────────────────────────────────
+
+export type BlocksRendererProps = {
+  content: BlocksContent;
+  blocks?: CustomBlocksConfig;
+  modifiers?: CustomModifiersConfig;
+};

package/src/utils.ts

@@ -0,0 +1,112 @@
+import type { InlineNode, StyleValue, TextNode } from './types';
+
+// ── Block Style ──────────────────────────────────────────────────────
+
+/**
+ * Builds the inline style object for a block that supports alignment,
+ * line-height, and indentation. Returns `undefined` when no style applies so
+ * the element renders without a `style` attribute.
+ */
+export function getBlockStyle(block: {
+  textAlign?: string;
+  lineHeight?: string;
+  indent?: number;
+}): StyleValue | undefined {
+  const style: Record<string, string> = {};
+  if (block.textAlign) style.textAlign = block.textAlign;
+  if (block.lineHeight) style.lineHeight = block.lineHeight;
+  if (block.indent) style.marginLeft = `${block.indent * 2}rem`;
+  return Object.keys(style).length > 0 ? style : undefined;
+}
+
+// ── Plain Text Extraction ────────────────────────────────────────────
+
+export function getPlainText(children: InlineNode[]): string {
+  return children
+    .map((child) => {
+      if (child.type === 'text') return child.text;
+      if (child.type === 'link') return child.children.map((t) => t.text).join('');
+      return '';
+    })
+    .join('');
+}
+
+// ── List Style Cycling ───────────────────────────────────────────────
+
+const orderedStyles = ['decimal', 'lower-alpha', 'upper-roman'];
+const unorderedStyles = ['disc', 'circle', 'square'];
+
+export function getListStyleType(format: 'ordered' | 'unordered', indentLevel: number): string {
+  const styles = format === 'ordered' ? orderedStyles : unorderedStyles;
+  return styles[indentLevel % styles.length];
+}
+
+// ── Text Modifiers (Marks) ───────────────────────────────────────────
+
+export type Mark = { name: string; value?: string };
+
+/**
+ * Returns the active marks for a text node in outer → inner order. This mirrors
+ * the React renderer, which applies modifiers inside-out (`fontSize` ends up the
+ * outermost wrapper and `code` the innermost), so the visual nesting matches.
+ */
+export function buildTextMarks(node: TextNode): Mark[] {
+  const marks: Mark[] = [];
+  if (node.fontSize) marks.push({ name: 'fontSize', value: node.fontSize });
+  if (node.fontFamily) marks.push({ name: 'fontFamily', value: node.fontFamily });
+  if (node.backgroundColor) marks.push({ name: 'backgroundColor', value: node.backgroundColor });
+  if (node.color) marks.push({ name: 'color', value: node.color });
+  if (node.bold) marks.push({ name: 'bold' });
+  if (node.italic) marks.push({ name: 'italic' });
+  if (node.uppercase) marks.push({ name: 'uppercase' });
+  if (node.underline) marks.push({ name: 'underline' });
+  if (node.strikethrough) marks.push({ name: 'strikethrough' });
+  if (node.superscript) marks.push({ name: 'superscript' });
+  if (node.subscript) marks.push({ name: 'subscript' });
+  if (node.code) marks.push({ name: 'code' });
+  return marks;
+}
+
+/**
+ * The default HTML tag and inline style used to render a given mark when no
+ * custom modifier component is supplied.
+ */
+export function getDefaultMarkRender(mark: Mark): { tag: string; style?: StyleValue } {
+  switch (mark.name) {
+    case 'code':
+      return { tag: 'code' };
+    case 'subscript':
+      return { tag: 'sub' };
+    case 'superscript':
+      return { tag: 'sup' };
+    case 'strikethrough':
+      return { tag: 'del' };
+    case 'underline':
+      return { tag: 'span', style: { textDecoration: 'underline' } };
+    case 'uppercase':
+      return { tag: 'span', style: { textTransform: 'uppercase' } };
+    case 'italic':
+      return { tag: 'em' };
+    case 'bold':
+      return { tag: 'strong' };
+    case 'color':
+      return { tag: 'span', style: { color: mark.value } };
+    case 'backgroundColor':
+      return { tag: 'span', style: { backgroundColor: mark.value } };
+    case 'fontFamily':
+      return { tag: 'span', style: { fontFamily: mark.value } };
+    case 'fontSize':
+      return { tag: 'span', style: { fontSize: mark.value } };
+    default:
+      return { tag: 'span' };
+  }
+}
+
+/**
+ * The prop object passed to a custom modifier component for a given mark. Value
+ * marks (color/background/font) forward their value; boolean marks pass nothing.
+ */
+export function getModifierProps(mark: Mark): Record<string, string> {
+  if (mark.value === undefined) return {};
+  return { [mark.name]: mark.value };
+}