feat: math block

docs/content/docs/features/blocks/code-blocks.mdx

@@ -34,7 +34,6 @@ type CodeBlockOptions = {
       aliases?: string[];
     }
   >;
-  createHighlighter?: () => Promise<HighlighterGeneric<any, any>>;
 };
 ```
 
@@ -44,15 +43,36 @@ type CodeBlockOptions = {
 
 `supportedLanguages:` The syntax highlighting languages supported by the code block, which is an empty array by default.
 
-`createHighlighter:` The [Shiki highliter](https://shiki.style/guide/load-theme) to use for syntax highlighting.
+**Syntax Highlighting**
 
-BlockNote also provides a generic set of options for syntax highlighting in the `@blocknote/code-block` package, which support a wide range of languages:
+Syntax highlighting is handled by a separate editor extension that you add to the editor's `extensions` (not configured on the code block itself), so it can highlight any block that declares a language — the code block, and blocks like the math block. When the extension isn't added, those blocks render as plain text.
+
+The extension is configured with a Shiki highlighter:
 
 ```ts
-import { createCodeBlockSpec } from "@blocknote/core";
-import { codeBlockOptions } from "@blocknote/code-block";
+type SyntaxHighlightingOptions = {
+  createHighlighter: () => Promise<HighlighterGeneric<any, any>>;
+};
+```
+
+`createHighlighter:` The [Shiki highlighter](https://shiki.style/guide/load-theme) to use for syntax highlighting.
+
+Which blocks get highlighted (and as which language) is decided by each block's spec via its `meta.highlight` callback — the code block highlights as its `language` prop, the math block always as `latex` — so you don't configure this on the extension.
 
-const codeBlock = createCodeBlockSpec(codeBlockOptions);
+BlockNote provides a generic, ready-to-use highlighter in the `@blocknote/code-block` package, which supports a wide range of languages. It's exported as a pre-configured `syntaxHighlighter` extension, alongside the code block options:
+
+```ts
+import { createCodeBlockSpec } from "@blocknote/core";
+import { codeBlockOptions, syntaxHighlighter } from "@blocknote/code-block";
+
+const editor = useCreateBlockNote({
+  extensions: [syntaxHighlighter],
+  schema: BlockNoteSchema.create().extend({
+    blockSpecs: {
+      codeBlock: createCodeBlockSpec(codeBlockOptions),
+    },
+  }),
+});
 ```
 
 See [this example](/examples/theming/code-block) to see it in action.
@@ -88,10 +108,22 @@ This will generate a `shiki.bundle.ts` file that you can use to create a syntax
 Like this:
 
 ```ts
+import { SyntaxHighlightingExtension } from "@blocknote/core";
 import { createHighlighter } from "./shiki.bundle.js";
 
+// Build a syntax highlighter extension from your custom Shiki bundle, then add
+// it to the editor's `extensions`.
+const syntaxHighlighter = SyntaxHighlightingExtension({
+  createHighlighter: () =>
+    createHighlighter({
+      themes: ["light-plus", "dark-plus"],
+      langs: [],
+    }),
+});
+
 export default function App() {
   const editor = useCreateBlockNote({
+    extensions: [syntaxHighlighter],
     schema: BlockNoteSchema.create().extend({
       blockSpecs: {
         codeBlock: createCodeBlockSpec({
@@ -103,11 +135,6 @@ export default function App() {
               aliases: ["ts"],
             },
           },
-          createHighlighter: () =>
-            createHighlighter({
-              themes: ["light-plus", "dark-plus"],
-              langs: [],
-            }),
         }),
       },
     }),

docs/package.json

@@ -48,7 +48,7 @@
     "@polar-sh/sdk": "^0.42.2",
     "@react-email/components": "^1.0.4",
     "@react-email/render": "^2.0.4",
-    "@react-pdf/renderer": "^4.3.0",
+    "@react-pdf/renderer": "^4.5.1",
     "@sentry/nextjs": "^10.34.0",
     "@shikijs/core": "^4",
     "@shikijs/engine-javascript": "^4",
@@ -96,7 +96,13 @@
     "tailwind-merge": "^3.4.0",
     "y-partykit": "^0.0.25",
     "yjs": "^13.6.27",
-    "zod": "^4.3.5"
+    "zod": "^4.3.5",
+    "@blocknote/math-block": "workspace:*",
+    "mermaid": "^11.0.0",
+    "@blocknote/diagram-block": "workspace:*",
+    "docx": "^9.6.1",
+    "@react-pdf/math": "^2.0.1",
+    "katex": "^0.16.11"
   },
   "devDependencies": {
     "@blocknote/code-block": "workspace:*",

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/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

@@ -2,11 +2,16 @@
   "playground": true,
   "docs": true,
   "author": "yousefed",
-  "tags": ["Interoperability"],
+  "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"
   },
   "pro": true
 }

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

@@ -20,9 +20,12 @@
     "@mantine/hooks": "^9.0.2",
     "react": "^19.2.3",
     "react-dom": "^19.2.3",
-    "@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"
   },
   "devDependencies": {
     "@types/react": "^19.2.3",

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,8 @@ import {
   PDFExporter,
   pdfDefaultSchemaMappings,
 } from "@blocknote/xl-pdf-exporter";
+import { diagramBlockMapping } from "@blocknote/xl-pdf-exporter/diagram-block";
+import { mathBlockMapping } from "@blocknote/xl-pdf-exporter/math-block";
 import { pdf, PDFViewer } from "@react-pdf/renderer";
 import { JSX, useEffect, useMemo, useReducer, useState } from "react";
 
@@ -38,7 +45,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: {
+        math: createReactMathBlockSpec(),
+        diagram: createReactDiagramBlockSpec(),
+      },
+      inlineContentSpecs: {
+        inlineMath: createReactInlineMathSpec(),
+      },
+    }),
     dropCursor: multiColumnDropCursor,
     dictionary: {
       ...locales.en,
@@ -330,6 +346,31 @@ export default function App() {
   console.log("Hello World", message);
 };`,
       },
+      {
+        type: "math",
+        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: "inlineMath",
+            content: "e^{i\\pi} + 1 = 0",
+          },
+        ],
+      },
       {
         type: "columnList",
         children: [
@@ -402,7 +443,16 @@ 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.
+        math: mathBlockMapping,
+      },
+    });
     const pdfDocument = await exporter.toReactPDFDocument(editor.document);
     setPDFDocument(pdfDocument);
     forceRerender();

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

@@ -2,10 +2,15 @@
   "playground": true,
   "docs": true,
   "author": "yousefed",
-  "tags": [""],
+  "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/package.json

@@ -20,8 +20,11 @@
     "@mantine/hooks": "^9.0.2",
     "react": "^19.2.3",
     "react-dom": "^19.2.3",
+    "@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"
   },
   "devDependencies": {
     "@types/react": "^19.2.3",