@k11k/better-blocks-astro-renderer 0.2.0 → 0.3.0

package/README.md

@@ -12,6 +12,9 @@
   <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>
+  <a href="https://buymeacoffee.com/k11k">
+    <img alt="Buy Me a Coffee" src="https://img.shields.io/badge/Buy%20Me%20a%20Coffee-support-FFDD00?logo=buymeacoffee&logoColor=black" />
+  </a>
 </p>
 
 <p align="center">
@@ -31,7 +34,8 @@
 7. [Custom Renderers](#custom-renderers)
 8. [TypeScript](#typescript)
 9. [Contributing](#contributing)
-10. [License](#license)
+10. [Support this project](#support-this-project)
+11. [License](#license)
 
 ---
 
@@ -110,22 +114,31 @@ 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.
 
+### Diagrams (Mermaid)
+
+[Mermaid](https://mermaid.js.org/) diagram blocks (`{ type: 'diagram', format: 'mermaid' }`) are **pre-rendered to inline SVG on the server** using [`beautiful-mermaid`](https://www.npmjs.com/package/beautiful-mermaid) — a pure-Node renderer that needs **no headless browser** (no Puppeteer, no Chromium download). Like math, rendering happens during SSR and static builds with **zero client-side JavaScript** and no hydration step.
+
+Supported diagram types — **flowchart, sequence, state, class, ER, and xychart** — render to a `<div class="mermaid-diagram">` wrapping the generated SVG. Diagram types `beautiful-mermaid` does not implement yet (gantt, pie, mindmap, gitGraph, …) and any source that fails to parse fall back gracefully to the raw definition in a `<pre class="mermaid-source">`, so content is never lost.
+
+`beautiful-mermaid` ships as a dependency of this package, so no extra install or stylesheet is required.
+
 ## 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                           | 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               |
+| `diagram` (mermaid)             | `<div>` (inline SVG) | Better Blocks               |
 
 ### Block properties
 
@@ -145,6 +158,8 @@ import 'katex/dist/katex.min.css';
 | `originalUrl` | media-embed               | Original user-provided URL                            |
 | `format`      | math                      | `inline` (`<span>`) or `block` (`<div>`)              |
 | `value`       | math                      | LaTeX source rendered with KaTeX                      |
+| `format`      | diagram                   | `mermaid` (the only supported diagram format)         |
+| `value`       | diagram                   | Mermaid source, pre-rendered to SVG on the server     |
 
 ## Supported Modifiers
 
@@ -217,6 +232,7 @@ The props each custom block component receives:
 | `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  |
+| `diagram`                                                  | `{ code; format }` (no slot) — bring your own diagram engine  |
 
 ### Custom modifier renderers
 
@@ -267,6 +283,7 @@ import type {
   TableHeaderCellNode,
   MediaEmbedNode,
   MathNode,
+  DiagramNode,
   TextAlign,
   CustomBlocksConfig,
   CustomModifiersConfig,
@@ -327,6 +344,16 @@ yarn lint        # Check formatting
 - [@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
 
+## Support this project
+
+This package is built and maintained in my free time, and it's free for everyone. If it has saved you time on a project, you can help keep it caffeinated and actively developed:
+
+<a href="https://buymeacoffee.com/k11k">
+  <img alt="Buy Me a Coffee" src="https://img.shields.io/badge/Buy%20Me%20a%20Coffee-support-FFDD00?logo=buymeacoffee&logoColor=black&style=for-the-badge" />
+</a>
+
+Every coffee goes toward fixing bugs, reviewing PRs, writing docs, and shipping the features you ask for. Thank you! &#9749;
+
 ## License
 
 [MIT License](LICENSE) &copy; [k11k-labs](https://github.com/k11k-labs)

package/index.ts

@@ -21,6 +21,7 @@ export type {
   TableHeaderCellNode,
   MediaEmbedNode,
   MathNode,
+  DiagramNode,
   TextAlign,
   StyleValue,
   CustomBlocksConfig,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@k11k/better-blocks-astro-renderer",
-  "version": "0.2.0",
+  "version": "0.3.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",
@@ -30,6 +30,7 @@
     "*.{js,jsx,ts,tsx,astro,json,md,yml,yaml,css}": "prettier --write"
   },
   "dependencies": {
+    "beautiful-mermaid": "^1.1.3",
     "katex": "^0.16.11"
   },
   "peerDependencies": {
@@ -65,6 +66,8 @@
     "katex",
     "latex",
     "math",
+    "mermaid",
+    "diagram",
     "cms",
     "headless-cms"
   ],

package/src/Block.astro

@@ -4,6 +4,7 @@ import Inline from './Inline.astro';
 import List from './List.astro';
 import Table from './Table.astro';
 import Math from './Math.astro';
+import Diagram from './Diagram.astro';
 import { getBlockStyle, getPlainText } from './utils';
 
 interface Props {
@@ -154,3 +155,5 @@ const EmbedComp = blocks?.['media-embed'] as any;
 }
 
 {block.type === 'math' && <Math node={block} blocks={blocks} />}
+
+{block.type === 'diagram' && <Diagram node={block} blocks={blocks} />}

package/src/Diagram.astro

@@ -0,0 +1,40 @@
+---
+import { renderMermaidSVG } from 'beautiful-mermaid';
+import type { CustomBlocksConfig, DiagramNode } from './types';
+
+interface Props {
+  node: DiagramNode;
+  blocks?: CustomBlocksConfig;
+}
+
+const { node, blocks } = Astro.props;
+
+const source = node.value ?? '';
+const format = node.format ?? 'mermaid';
+const DiagramComp = blocks?.diagram;
+
+// beautiful-mermaid renders Mermaid to an SVG string synchronously on the
+// server — no browser, no client-side hydration. It throws on empty or invalid
+// input and on unsupported diagram types (gantt, pie, mindmap, gitGraph, …); in
+// that case we fall back to the raw source in a <pre> so content is never lost.
+let svg: string | null = null;
+if (!DiagramComp && source) {
+  try {
+    const out = renderMermaidSVG(source);
+    svg = typeof out === 'string' && out.includes('<svg') ? out : null;
+  } catch {
+    svg = null;
+  }
+}
+const Custom = DiagramComp as any;
+---
+
+{
+  Custom ? (
+    <Custom code={source} format={format} />
+  ) : svg !== null ? (
+    <div class="mermaid-diagram" set:html={svg} />
+  ) : (
+    <pre class="mermaid-source">{source}</pre>
+  )
+}

package/src/types.ts

@@ -128,6 +128,13 @@ export type MediaEmbedNode = {
   children: [{ type: 'text'; text: '' }];
 };
 
+export type DiagramNode = {
+  type: 'diagram';
+  format: 'mermaid';
+  value: string;
+  children: [{ type: 'text'; text: '' }];
+};
+
 export type BlockNode =
   | ParagraphNode
   | HeadingNode
@@ -138,7 +145,8 @@ export type BlockNode =
   | HorizontalLineNode
   | TableNode
   | MediaEmbedNode
-  | MathNode;
+  | MathNode
+  | DiagramNode;
 
 export type BlocksContent = BlockNode[];
 
@@ -176,6 +184,7 @@ export type AstroComponentFactory = (...args: any[]) => any;
  * - `table` / `table-row` / `table-cell` / `table-header-cell` — children via `<slot />`
  * - `media-embed` — `{ url: string; originalUrl?: string }`
  * - `math` — `{ formula: string; inline: boolean }`
+ * - `diagram` — `{ code: string; format: 'mermaid' }`
  */
 export type CustomBlocksConfig = Partial<{
   paragraph: AstroComponentFactory;
@@ -193,6 +202,7 @@ export type CustomBlocksConfig = Partial<{
   'table-header-cell': AstroComponentFactory;
   'media-embed': AstroComponentFactory;
   math: AstroComponentFactory;
+  diagram: AstroComponentFactory;
 }>;
 
 /**