@k11k/better-blocks-astro-renderer 0.2.0 → 0.4.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,57 @@ 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.
+
+### Callouts (Admonitions)
+
+Block-level `callout` nodes render GitHub-style alerts in five variants &mdash; `note`, `tip`, `important`, `warning`, and `caution`. Each renders as an `<aside role="note">` with a colored left border, a title row (icon + label), and the nested block children (paragraphs, lists, links, etc.). If a `title` is set on the node it is used; otherwise the localized variant label is shown.
+
+Colors come from a small **scoped `<style>`** that ships with the component (still zero client-side JavaScript), and the default palette **adapts to dark mode automatically** via `@media (prefers-color-scheme: dark)`. The accent for each variant is driven by a `--bb-callout-accent` custom property on the `.bb-callout-{variant}` element, so you can retheme colors from your own CSS without replacing the markup:
+
+```css
+/* Recolor a single variant, or override per color scheme */
+.bb-callout-note {
+  --bb-callout-accent: #2563eb;
+}
+```
+
+To replace the markup entirely, override the `callout` block. It receives `variant` and `title`; the nested children arrive via `<slot />`:
+
+```astro
+---
+import { BlocksRenderer } from '@k11k/better-blocks-astro-renderer';
+import MyCallout from '../components/MyCallout.astro';
+const { blocks } = Astro.props;
+---
+
+<BlocksRenderer content={blocks} blocks={{ callout: MyCallout }} />
+```
+
 ## 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               |
+| `callout` (admonition)          | `<aside>`            | Better Blocks               |
 
 ### Block properties
 
@@ -145,6 +184,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 +258,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 +309,7 @@ import type {
   TableHeaderCellNode,
   MediaEmbedNode,
   MathNode,
+  DiagramNode,
   TextAlign,
   CustomBlocksConfig,
   CustomModifiersConfig,
@@ -327,6 +370,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,9 @@ export type {
   TableHeaderCellNode,
   MediaEmbedNode,
   MathNode,
+  DiagramNode,
+  CalloutNode,
+  CalloutVariant,
   TextAlign,
   StyleValue,
   CustomBlocksConfig,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@k11k/better-blocks-astro-renderer",
-  "version": "0.2.0",
+  "version": "0.4.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,8 @@ 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 Callout from './Callout.astro';
 import { getBlockStyle, getPlainText } from './utils';
 
 interface Props {
@@ -154,3 +156,7 @@ const EmbedComp = blocks?.['media-embed'] as any;
 }
 
 {block.type === 'math' && <Math node={block} blocks={blocks} />}
+
+{block.type === 'diagram' && <Diagram node={block} blocks={blocks} />}
+
+{block.type === 'callout' && <Callout node={block} blocks={blocks} modifiers={modifiers} />}

package/src/Callout.astro

@@ -0,0 +1,135 @@
+---
+import type {
+  CalloutNode,
+  CalloutVariant,
+  CustomBlocksConfig,
+  CustomModifiersConfig,
+} from './types';
+import Block from './Block.astro';
+
+interface Props {
+  node: CalloutNode;
+  blocks?: CustomBlocksConfig;
+  modifiers?: CustomModifiersConfig;
+}
+
+const { node, blocks, modifiers } = Astro.props;
+
+// GitHub-style alert metadata: default label and octicon path. Accent colors
+// live in the scoped <style> below so they can adapt to dark mode.
+const VARIANTS: Record<CalloutVariant, { label: string; icon: string }> = {
+  note: {
+    label: 'Note',
+    icon: 'M0 8a8 8 0 1 1 16 0A8 8 0 0 1 0 8Zm8-6.5a6.5 6.5 0 1 0 0 13 6.5 6.5 0 0 0 0-13ZM6.5 7.75A.75.75 0 0 1 7.25 7h1a.75.75 0 0 1 .75.75v2.75h.25a.75.75 0 0 1 0 1.5h-2a.75.75 0 0 1 0-1.5h.25v-2h-.25a.75.75 0 0 1-.75-.75ZM8 6a1 1 0 1 1 0-2 1 1 0 0 1 0 2Z',
+  },
+  tip: {
+    label: 'Tip',
+    icon: 'M8 1.5c-2.363 0-4 1.69-4 3.75 0 .984.424 1.625.984 2.304l.214.253c.223.264.47.556.673.848.284.411.537.896.621 1.49a.75.75 0 0 1-1.484.211c-.04-.282-.163-.547-.37-.847a8.456 8.456 0 0 0-.542-.68c-.084-.1-.173-.205-.268-.32C3.201 7.75 2.5 6.766 2.5 5.25 2.5 2.31 4.863 0 8 0s5.5 2.31 5.5 5.25c0 1.516-.701 2.5-1.328 3.259-.095.115-.184.22-.268.319-.207.245-.383.453-.541.681-.208.3-.33.565-.37.847a.751.751 0 0 1-1.485-.212c.084-.593.337-1.078.621-1.489.203-.292.45-.584.673-.848.075-.088.147-.173.213-.253.561-.679.985-1.32.985-2.304 0-2.06-1.637-3.75-4-3.75ZM5.75 12h4.5a.75.75 0 0 1 0 1.5h-4.5a.75.75 0 0 1 0-1.5ZM6 15.25a.75.75 0 0 1 .75-.75h2.5a.75.75 0 0 1 0 1.5h-2.5a.75.75 0 0 1-.75-.75Z',
+  },
+  important: {
+    label: 'Important',
+    icon: 'M0 1.75C0 .784.784 0 1.75 0h12.5C15.216 0 16 .784 16 1.75v9.5A1.75 1.75 0 0 1 14.25 13H8.06l-2.573 2.573A1.458 1.458 0 0 1 3 14.543V13H1.75A1.75 1.75 0 0 1 0 11.25Zm1.75-.25a.25.25 0 0 0-.25.25v9.5c0 .138.112.25.25.25h2a.75.75 0 0 1 .75.75v2.19l2.72-2.72a.749.749 0 0 1 .53-.22h6.5a.25.25 0 0 0 .25-.25v-9.5a.25.25 0 0 0-.25-.25Zm7 2.25v2.5a.75.75 0 0 1-1.5 0v-2.5a.75.75 0 0 1 1.5 0ZM9 9a1 1 0 1 1-2 0 1 1 0 0 1 2 0Z',
+  },
+  warning: {
+    label: 'Warning',
+    icon: 'M6.457 1.047c.659-1.234 2.427-1.234 3.086 0l6.082 11.378A1.75 1.75 0 0 1 14.082 15H1.918a1.75 1.75 0 0 1-1.543-2.575Zm1.763.707a.25.25 0 0 0-.44 0L1.698 13.132a.25.25 0 0 0 .22.368h12.164a.25.25 0 0 0 .22-.368Zm.53 3.996v2.5a.75.75 0 0 1-1.5 0v-2.5a.75.75 0 0 1 1.5 0ZM9 11a1 1 0 1 1-2 0 1 1 0 0 1 2 0Z',
+  },
+  caution: {
+    label: 'Caution',
+    icon: 'M4.47.22A.749.749 0 0 1 5 0h6c.199 0 .39.079.53.22l4.25 4.25c.141.14.22.331.22.53v6a.749.749 0 0 1-.22.53l-4.25 4.25A.749.749 0 0 1 11 16H5a.749.749 0 0 1-.53-.22L.22 11.53A.749.749 0 0 1 0 11V5c0-.199.079-.39.22-.53Zm.84 1.28L1.5 5.31v5.38l3.81 3.81h5.38l3.81-3.81V5.31L10.69 1.5ZM8 4a.75.75 0 0 1 .75.75v3.5a.75.75 0 0 1-1.5 0v-3.5A.75.75 0 0 1 8 4Zm0 8a1 1 0 1 1 0-2 1 1 0 0 1 0 2Z',
+  },
+};
+
+const variant: CalloutVariant = VARIANTS[node.variant] ? node.variant : 'note';
+const meta = VARIANTS[variant];
+const title = node.title?.trim() ? node.title : meta.label;
+const CalloutComp = blocks?.callout as any;
+---
+
+{
+  CalloutComp ? (
+    <CalloutComp variant={variant} title={node.title}>
+      {node.children.map((child) => (
+        <Block block={child} blocks={blocks} modifiers={modifiers} />
+      ))}
+    </CalloutComp>
+  ) : (
+    <aside class={`bb-callout bb-callout-${variant}`} role="note">
+      <p class="bb-callout-title">
+        <svg class="bb-callout-icon" viewBox="0 0 16 16" aria-hidden="true">
+          <path d={meta.icon} />
+        </svg>
+        {title}
+      </p>
+      <div class="bb-callout-body">
+        {node.children.map((child) => (
+          <Block block={child} blocks={blocks} modifiers={modifiers} />
+        ))}
+      </div>
+    </aside>
+  )
+}
+
+<style>
+  .bb-callout {
+    border-left: 0.25rem solid var(--bb-callout-accent, #0969da);
+    padding: 0.5rem 1rem;
+    margin: 1rem 0;
+  }
+  .bb-callout-title {
+    display: flex;
+    align-items: center;
+    gap: 0.5rem;
+    margin: 0 0 0.25rem;
+    font-weight: 600;
+    color: var(--bb-callout-accent, #0969da);
+  }
+  .bb-callout-icon {
+    width: 16px;
+    height: 16px;
+    flex: none;
+    fill: currentColor;
+  }
+  .bb-callout-body > :first-child {
+    margin-top: 0;
+  }
+  .bb-callout-body > :last-child {
+    margin-bottom: 0;
+  }
+
+  /* Light-mode accents (GitHub palette) */
+  .bb-callout-note {
+    --bb-callout-accent: #0969da;
+  }
+  .bb-callout-tip {
+    --bb-callout-accent: #1a7f37;
+  }
+  .bb-callout-important {
+    --bb-callout-accent: #8250df;
+  }
+  .bb-callout-warning {
+    --bb-callout-accent: #9a6700;
+  }
+  .bb-callout-caution {
+    --bb-callout-accent: #cf222e;
+  }
+
+  /* Dark-mode accents adapt automatically */
+  @media (prefers-color-scheme: dark) {
+    .bb-callout-note {
+      --bb-callout-accent: #4493f8;
+    }
+    .bb-callout-tip {
+      --bb-callout-accent: #3fb950;
+    }
+    .bb-callout-important {
+      --bb-callout-accent: #ab7df8;
+    }
+    .bb-callout-warning {
+      --bb-callout-accent: #d29922;
+    }
+    .bb-callout-caution {
+      --bb-callout-accent: #f85149;
+    }
+  }
+</style>

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,22 @@ export type MediaEmbedNode = {
   children: [{ type: 'text'; text: '' }];
 };
 
+export type DiagramNode = {
+  type: 'diagram';
+  format: 'mermaid';
+  value: string;
+  children: [{ type: 'text'; text: '' }];
+};
+
+export type CalloutVariant = 'note' | 'tip' | 'important' | 'warning' | 'caution';
+
+export type CalloutNode = {
+  type: 'callout';
+  variant: CalloutVariant;
+  title?: string;
+  children: BlockNode[];
+};
+
 export type BlockNode =
   | ParagraphNode
   | HeadingNode
@@ -138,7 +154,9 @@ export type BlockNode =
   | HorizontalLineNode
   | TableNode
   | MediaEmbedNode
-  | MathNode;
+  | MathNode
+  | DiagramNode
+  | CalloutNode;
 
 export type BlocksContent = BlockNode[];
 
@@ -176,6 +194,8 @@ 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' }`
+ * - `callout` — `{ variant: CalloutVariant; title?: string }` (children via `<slot />`)
  */
 export type CustomBlocksConfig = Partial<{
   paragraph: AstroComponentFactory;
@@ -193,6 +213,8 @@ export type CustomBlocksConfig = Partial<{
   'table-header-cell': AstroComponentFactory;
   'media-embed': AstroComponentFactory;
   math: AstroComponentFactory;
+  diagram: AstroComponentFactory;
+  callout: AstroComponentFactory;
 }>;
 
 /**