feat(core): source-with-preview, syntax highlighting & exporter images

Core primitives that the math and diagram blocks are built on.

- De-duplicate and order extensions by key in `ExtensionManager`, and stop
  `editor.getExtension` from erasing extension instance types.
- Make syntax highlighting a user-provided singleton extension; code blocks
  and other blocks configure a shared highlighter instead of owning one.
- Add `SourceBlockWithPreview` / `SourceInlineContentWithPreview` extensions
  and their React counterparts: a reusable source/preview block and inline
  content pattern with popup editing, keyboard and selection handling.
- Support converting between plain and styled text in `updateBlock`, and add
  inline content boundary editing.
- Give exporters a typed `ExportImage` contract and dictionary-backed i18n so
  they never hardcode language strings.

Author: nperez0111

examples/04-theming/06-code-block/src/App.tsx

@@ -3,12 +3,16 @@ import "@blocknote/core/fonts/inter.css";
 import { BlockNoteView } from "@blocknote/mantine";
 import "@blocknote/mantine/style.css";
 import { useCreateBlockNote } from "@blocknote/react";
-// This packages some of the most used languages in on-demand bundle
-import { codeBlockOptions } from "@blocknote/code-block";
+// This packages some of the most used languages in on-demand bundle, and a
+// ready-to-use syntax highlighter extension configured with them.
+import { codeBlockOptions, syntaxHighlighter } from "@blocknote/code-block";
 
 export default function App() {
   // Creates a new editor instance.
   const editor = useCreateBlockNote({
+    // Adding the syntax highlighter extension enables syntax highlighting for
+    // the code block. Without it, code renders as plain text.
+    extensions: [syntaxHighlighter],
     schema: BlockNoteSchema.create().extend({
       blockSpecs: {
         codeBlock: createCodeBlockSpec(codeBlockOptions),

examples/04-theming/07-custom-code-block/.bnexample.json

@@ -5,10 +5,10 @@
   "tags": ["Basic"],
   "dependencies": {
     "@blocknote/code-block": "latest",
-    "@shikijs/core": "^4",
-    "@shikijs/engine-javascript": "^4",
-    "@shikijs/langs-precompiled": "^4",
-    "@shikijs/themes": "^4",
-    "@shikijs/types": "^4"
+    "@shikijs/core": "^4.4.3",
+    "@shikijs/engine-javascript": "^4.4.3",
+    "@shikijs/langs-precompiled": "^4.4.3",
+    "@shikijs/themes": "^4.4.3",
+    "@shikijs/types": "^4.4.3"
   }
 }

examples/04-theming/07-custom-code-block/src/App.tsx

@@ -1,14 +1,31 @@
-import { BlockNoteSchema, createCodeBlockSpec } from "@blocknote/core";
+import {
+  BlockNoteSchema,
+  createCodeBlockSpec,
+  SyntaxHighlightingExtension,
+} from "@blocknote/core";
 import "@blocknote/core/fonts/inter.css";
 import { BlockNoteView } from "@blocknote/mantine";
 import "@blocknote/mantine/style.css";
 import { useCreateBlockNote } from "@blocknote/react";
 // Bundle created from `npx shiki-codegen --langs typescript,javascript,react --themes light-plus,dark-plus --engine javascript --precompiled ./shiki.bundle.ts`
 import { createHighlighter } from "./shiki.bundle";
 
+// Syntax highlighting is a separate extension, configured with a highlighter.
+// Here we build one from our own custom Shiki bundle (with `dark-plus` /
+// `light-plus` themes) and pass it to the editor's `extensions` below.
+const syntaxHighlighter = SyntaxHighlightingExtension({
+  // This creates a highlighter, it can be asynchronous to load it afterwards
+  createHighlighter: () =>
+    createHighlighter({
+      themes: ["dark-plus", "light-plus"],
+      langs: [],
+    }),
+});
+
 export default function App() {
   // Creates a new editor instance.
   const editor = useCreateBlockNote({
+    extensions: [syntaxHighlighter],
     schema: BlockNoteSchema.create().extend({
       blockSpecs: {
         codeBlock: createCodeBlockSpec({
@@ -27,12 +44,6 @@ export default function App() {
               name: "Vue",
             },
           },
-          // This creates a highlighter, it can be asynchronous to load it afterwards
-          createHighlighter: () =>
-            createHighlighter({
-              themes: ["dark-plus", "light-plus"],
-              langs: [],
-            }),
         }),
       },
     }),

examples/05-interoperability/05-converting-blocks-to-pdf/.bnexample.json

@@ -4,9 +4,13 @@
   "author": "yousefed",
   "tags": ["Interoperability"],
   "dependencies": {
-    "@blocknote/xl-pdf-exporter": "latest",
+    "@blocknote/diagram-block": "latest",
+    "@blocknote/math-block": "latest",
     "@blocknote/xl-multi-column": "latest",
-    "@react-pdf/renderer": "^4.3.0"
+    "@blocknote/xl-pdf-exporter": "latest",
+    "@react-pdf/math": "^2.0.1",
+    "@react-pdf/renderer": "^4.5.1",
+    "mathjax-full": "^3.2.2"
   },
   "pro": true
 }

examples/05-interoperability/05-converting-blocks-to-pdf/src/App.tsx

@@ -8,6 +8,11 @@ import "@blocknote/core/fonts/inter.css";
 import * as locales from "@blocknote/core/locales";
 import { BlockNoteView } from "@blocknote/mantine";
 import "@blocknote/mantine/style.css";
+import { createReactDiagramBlockSpec } from "@blocknote/diagram-block";
+import {
+  createReactInlineMathSpec,
+  createReactMathBlockSpec,
+} from "@blocknote/math-block";
 import {
   SuggestionMenuController,
   getDefaultReactSlashMenuItems,
@@ -24,6 +29,11 @@ import {
   PDFExporter,
   pdfDefaultSchemaMappings,
 } from "@blocknote/xl-pdf-exporter";
+import { diagramBlockMapping } from "@blocknote/diagram-block/pdf-exporter";
+import {
+  inlineMathMapping,
+  mathBlockMapping,
+} from "@blocknote/math-block/pdf-exporter";
 import { pdf, PDFViewer } from "@react-pdf/renderer";
 import { JSX, useEffect, useMemo, useReducer, useState } from "react";
 
@@ -38,7 +48,16 @@ export default function App() {
   // Creates a new editor instance.
   const editor = useCreateBlockNote({
     // Adds support for page breaks & multi-column blocks.
-    schema: withMultiColumn(withPageBreak(BlockNoteSchema.create())),
+    // Adds support for math & diagram blocks.
+    schema: withMultiColumn(withPageBreak(BlockNoteSchema.create())).extend({
+      blockSpecs: {
+        mathBlock: createReactMathBlockSpec(),
+        diagram: createReactDiagramBlockSpec(),
+      },
+      inlineContentSpecs: {
+        math: createReactInlineMathSpec(),
+      },
+    }),
     dropCursor: multiColumnDropCursor,
     dictionary: {
       ...locales.en,
@@ -330,6 +349,31 @@ export default function App() {
   console.log("Hello World", message);
 };`,
       },
+      {
+        type: "mathBlock",
+        content: "a^2 = \\sqrt{b^2 + c^2}",
+      },
+      {
+        type: "diagram",
+        content: `graph TD
+  A[Start] --> B{Works?}
+  B -->|Yes| C[Ship it]
+  B -->|No| A`,
+      },
+      {
+        type: "paragraph",
+        content: [
+          {
+            type: "text",
+            text: "Inline math: ",
+            styles: {},
+          },
+          {
+            type: "math",
+            content: "e^{i\\pi} + 1 = 0",
+          },
+        ],
+      },
       {
         type: "columnList",
         children: [
@@ -402,7 +446,21 @@ export default function App() {
 
   // Exports the editor document to PDF whenever it changes.
   const onChange = async () => {
-    const exporter = new PDFExporter(editor.schema, pdfDefaultSchemaMappings);
+    const exporter = new PDFExporter(editor.schema, {
+      ...pdfDefaultSchemaMappings,
+      blockMapping: {
+        ...pdfDefaultSchemaMappings.blockMapping,
+        // Embeds diagrams as images instead of their Mermaid source.
+        diagram: diagramBlockMapping,
+        // Renders math blocks as formulas instead of their LaTeX source.
+        mathBlock: mathBlockMapping,
+      },
+      inlineContentMapping: {
+        ...pdfDefaultSchemaMappings.inlineContentMapping,
+        // Renders inline math as formula images instead of its LaTeX source.
+        math: inlineMathMapping,
+      },
+    });
     const pdfDocument = await exporter.toReactPDFDocument(editor.document);
     setPDFDocument(pdfDocument);
     forceRerender();

examples/05-interoperability/06-converting-blocks-to-docx/.bnexample.json

@@ -4,8 +4,11 @@
   "author": "yousefed",
   "tags": [""],
   "dependencies": {
+    "@blocknote/diagram-block": "latest",
+    "@blocknote/math-block": "latest",
     "@blocknote/xl-docx-exporter": "latest",
-    "@blocknote/xl-multi-column": "latest"
+    "@blocknote/xl-multi-column": "latest",
+    "katex": "^0.16.11"
   },
   "pro": true
 }

examples/05-interoperability/06-converting-blocks-to-docx/src/App.tsx

@@ -8,6 +8,11 @@ import "@blocknote/core/fonts/inter.css";
 import * as locales from "@blocknote/core/locales";
 import { BlockNoteView } from "@blocknote/mantine";
 import "@blocknote/mantine/style.css";
+import {
+  createReactInlineMathSpec,
+  createReactMathBlockSpec,
+} from "@blocknote/math-block";
+import { createReactDiagramBlockSpec } from "@blocknote/diagram-block";
 import {
   SuggestionMenuController,
   getDefaultReactSlashMenuItems,
@@ -18,6 +23,11 @@ import {
   DOCXExporter,
   docxDefaultSchemaMappings,
 } from "@blocknote/xl-docx-exporter";
+import { diagramBlockMapping } from "@blocknote/diagram-block/docx-exporter";
+import {
+  inlineMathMapping,
+  mathBlockMapping,
+} from "@blocknote/math-block/docx-exporter";
 import {
   getMultiColumnSlashMenuItems,
   multiColumnDropCursor,
@@ -32,7 +42,16 @@ export default function App() {
   // Creates a new editor instance.
   const editor = useCreateBlockNote({
     // Adds support for page breaks & multi-column blocks.
-    schema: withMultiColumn(withPageBreak(BlockNoteSchema.create())),
+    // Adds support for math & diagram blocks.
+    schema: withMultiColumn(withPageBreak(BlockNoteSchema.create())).extend({
+      blockSpecs: {
+        mathBlock: createReactMathBlockSpec(),
+        diagram: createReactDiagramBlockSpec(),
+      },
+      inlineContentSpecs: {
+        math: createReactInlineMathSpec(),
+      },
+    }),
     dropCursor: multiColumnDropCursor,
     dictionary: {
       ...locales.en,
@@ -324,6 +343,31 @@ export default function App() {
   console.log("Hello World", message);
 };`,
       },
+      {
+        type: "mathBlock",
+        content: "a^2 = \\sqrt{b^2 + c^2}",
+      },
+      {
+        type: "diagram",
+        content: `graph TD
+  A[Start] --> B{Works?}
+  B -->|Yes| C[Ship it]
+  B -->|No| A`,
+      },
+      {
+        type: "paragraph",
+        content: [
+          {
+            type: "text",
+            text: "Inline math: ",
+            styles: {},
+          },
+          {
+            type: "math",
+            content: "e^{i\\pi} + 1 = 0",
+          },
+        ],
+      },
 
       {
         type: "columnList",
@@ -396,7 +440,23 @@ export default function App() {
 
   // Exports the editor content to DOCX and downloads it.
   const onDownloadClick = async () => {
-    const exporter = new DOCXExporter(editor.schema, docxDefaultSchemaMappings);
+    const exporter = new DOCXExporter(editor.schema, {
+      ...docxDefaultSchemaMappings,
+      blockMapping: {
+        ...docxDefaultSchemaMappings.blockMapping,
+        // Embeds diagrams as images instead of their Mermaid source.
+        diagram: diagramBlockMapping,
+        // Renders math blocks as native equations instead of their LaTeX
+        // source.
+        mathBlock: mathBlockMapping,
+      },
+      inlineContentMapping: {
+        ...docxDefaultSchemaMappings.inlineContentMapping,
+        // Renders inline math as native equations instead of its LaTeX
+        // source.
+        math: inlineMathMapping,
+      },
+    });
     const blob = await exporter.toBlob(editor.document);
 
     const link = document.createElement("a");

examples/05-interoperability/07-converting-blocks-to-odt/.bnexample.json

@@ -4,8 +4,11 @@
   "author": "areknawo",
   "tags": [""],
   "dependencies": {
+    "@blocknote/diagram-block": "latest",
+    "@blocknote/math-block": "latest",
+    "@blocknote/xl-multi-column": "latest",
     "@blocknote/xl-odt-exporter": "latest",
-    "@blocknote/xl-multi-column": "latest"
+    "katex": "^0.16.11"
   },
   "pro": true
 }