feat: server-side processing

docs/pages/docs/editor-api/_meta.json

@@ -1,6 +1,7 @@
 {
- "manipulating-blocks":"",
- "manipulating-inline-content":"",
- "cursor-selections":"",
- "converting-blocks":""
+ "manipulating-blocks": "",
+ "manipulating-inline-content": "",
+ "cursor-selections": "",
+ "converting-blocks": "",
+ "server-processing": ""
 }

docs/pages/docs/editor-api/converting-blocks.mdx

@@ -63,9 +63,30 @@ Tries to create `Block` and `InlineContent` objects based on Markdown syntax, th
 
 <Example name="interoperability/converting-blocks-from-md" />
 
-## HTML
+## Export HTML (for static rendering)
 
-The editor exposes functions to convert Blocks to and from HTML. Converting Blocks to HTML will lose some information such as the nesting of nodes in order to export a simple HTML structure.
+Use `blocksToFullHTML` to export the entire document with all structure, styles and formatting.
+The exported HTML is the same as BlockNote would use to render the editor, and includes all structure for nested blocks.
+
+For example, you an use this for static rendering documents that have been created in the editor.
+Make sure to include the same stylesheets when you want to render the output HTML ([see example](/examples/backend/rendering-static-documents)).
+
+```typescript
+blocksToFullHTML(blocks?: Block[]): string;
+
+// Usage
+const HTMLFromBlocks = editor.blocksToFullHTML(blocks);
+```
+
+`blocks:` The blocks to convert. If not provided, the entire document (all top-level blocks) is used.
+
+`returns:` The blocks, exported to an HTML string.
+
+## HTML (for interoperability)
+
+The editor exposes functions to convert Blocks to and from HTML for interoperability with other applications.
+
+Converting Blocks to HTML this way will lose some information such as the nesting of nodes in order to export a simple HTML structure.
 
 ### Converting Blocks to HTML
 

docs/pages/docs/editor-api/server-processing.mdx

@@ -0,0 +1,59 @@
+---
+title: Server-side processing
+description: Use `ServerBlockNoteEditor` to process Blocks on the server.
+imageTitle: Server-side processing
+path: /docs/server-side-processing
+---
+
+import { Example } from "@/components/example";
+import { Callout } from "nextra/components";
+
+# Server-side processing
+
+While you can use the `BlockNoteEditor` on the client side,
+you can also use `ServerBlockNoteEditor` from `@blocknote/server-util` to process BlockNote documents on the server.
+
+For example, use the following code to convert a BlockNote document to HTML on the server:
+
+```tsx
+import { ServerBlockNoteEditor } from "@blocknote/server-util";
+
+const editor = ServerBlockNoteEditor.create();
+const html = await editor.blocksToFullHTML(blocks);
+```
+
+`ServerBlockNoteEditor.create` takes the same BlockNoteEditorOptions as `useCreateBlockNote` and `BlockNoteEditor.create` ([see docs](/docs/editor-basics/setup)),
+so you can pass the same configuration (for example, your custom schema) to your server-side BlockNote editor as on the client.
+
+## Functions for converting blocks
+
+`ServerBlockNoteEditor` exposes the same functions for [converting blocks as the client side editor](/docs/converting-blocks):
+
+- `blocksToFullHTML`
+- `blocksToHTMLLossy` and `tryParseHTMLToBlocks`
+- `blocksToMarkdownLossy` and `tryParseMarkdownToBlocks`
+
+## Yjs processing
+
+Additionally, `ServerBlockNoteEditor` provides functions for processing Yjs documents in case you use Yjs collaboration:
+
+- `yDocToBlocks` or `yXmlFragmentToBlocks`: use this to convert a Yjs document or XML Fragment to BlockNote blocks
+- `blocksToYDoc` or `blocksToYXmlFragment`: use this to convert a BlockNote document (blocks) to a Yjs document or XML Fragment
+
+## React compatibility
+
+If you use [custom schemas in React](/docs/custom-schemas), you can use the same schema on the server side.
+Functions like `blocksToFullHTML` will use your custom React rendering functions to export blocks to HTML, similar to how these functions work on the client.
+However, it could be that your React components require access to a React context (e.g. a theme or localization context).
+
+For these use-cases, we provide a function `withReactContext` that allows you to pass a React context to the server-side editor.
+This example exports a BlockNote document to HTML within a React context `YourContext`, so that even Custom Blocks built in React that require `YourContext` will be exported correctly:
+
+```tsx
+const html = await editor.withReactContext(
+ ({ children }) => (
+ <YourContext.Provider value={true}>{children}</YourContext.Provider>
+ ),
+ async () => editor.blocksToFullHTML(blocks),
+);
+```

examples/02-backend/04-rendering-static-documents/.bnexample.json

@@ -0,0 +1,9 @@
+{
+ "playground": true,
+ "docs": true,
+ "author": "yousefed",
+ "tags": ["server"],
+ "dependencies": {
+ "@blocknote/server-util": "latest"
+ }
+}

examples/02-backend/04-rendering-static-documents/App.tsx

@@ -0,0 +1,60 @@
+import "@blocknote/core/fonts/inter.css";
+import "@blocknote/core/style.css";
+
+/**
+ On Server Side, you can use the ServerBlockNoteEditor to render BlockNote documents to HTML. e.g.:
+
+ import { ServerBlockNoteEditor } from "@blocknote/server-util";
+
+ const editor = ServerBlockNoteEditor.create();
+ const html = await editor.blocksToFullHTML(document);
+
+You can then use render this HTML as a static page or send it to the client. Make sure to include the editor stylesheets:
+
+ import "@blocknote/core/fonts/inter.css";
+ import "@blocknote/core/style.css";
+
+This example has the HTML hard-coded, but shows at least how the document will be rendered when the appropriate style sheets are loaded.
+ */
+
+export default function App() {
+ // This HTML is generated by the ServerBlockNoteEditor.blocksToFullHTML method
+ const html = `<div class="bn-block-group" data-node-type="blockGroup">
+ <div class="bn-block-outer" data-node-type="blockOuter" data-id="1" data-text-color="yellow" data-background-color="blue">
+ <div class="bn-block" data-node-type="blockContainer" data-id="1" data-text-color="yellow" data-background-color="blue">
+ <div class="bn-block-content" data-content-type="heading" data-text-alignment="right" data-level="2">
+ <h2 class="bn-inline-content">
+ <strong><u>Heading </u></strong><em><s>2</s></em>
+ </h2>
+ </div>
+ <div class="bn-block-group" data-node-type="blockGroup">
+ <div class="bn-block-outer" data-node-type="blockOuter" data-id="2" data-background-color="red">
+ <div class="bn-block" data-node-type="blockContainer" data-id="2" data-background-color="red">
+ <div class="bn-block-content" data-content-type="paragraph">
+ <p class="bn-inline-content">Paragraph</p>
+ </div>
+ </div>
+ </div>
+ <div class="bn-block-outer" data-node-type="blockOuter" data-id="3">
+ <div class="bn-block" data-node-type="blockContainer" data-id="3">
+ <div class="bn-block-content" data-content-type="bulletListItem">
+ <p class="bn-inline-content">list item</p>
+ </div>
+ </div>
+ </div>
+ </div>
+ </div>
+ </div>
+</div>
+`;
+
+ // Renders the editor instance using a React component.
+ return (
+ <div className="bn-container">
+ <div
+ className=" bn-default-styles"
+ dangerouslySetInnerHTML={{ __html: html }}
+ />
+ </div>
+ );
+}

examples/02-backend/04-rendering-static-documents/README.md

@@ -0,0 +1,7 @@
+# Rendering static documents
+
+This example shows how you can use HTML exported using the `blocksToFullHTML` and render it as a static document (a view-only document, without the editor). You can use this for example if you use BlockNote to edit blog posts in a CMS, but want to display non-editable static, published pages to end-users.
+
+**Relevant Docs:**
+
+- [Server-side processing](/docs/editor-api/server-processing)

examples/02-backend/04-rendering-static-documents/index.html

@@ -0,0 +1,14 @@
+<html lang="en">
+ <head>
+ <script>
+ <!-- AUTO-GENERATED FILE, DO NOT EDIT DIRECTLY -->
+ </script>
+ <meta charset="UTF-8" />
+ <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+ <title>Rendering static documents</title>
+ </head>
+ <body>
+ <div id="root"></div>
+ <script type="module" src="./main.tsx"></script>
+ </body>
+</html>

examples/02-backend/04-rendering-static-documents/main.tsx

@@ -0,0 +1,11 @@
+// AUTO-GENERATED FILE, DO NOT EDIT DIRECTLY
+import React from "react";
+import { createRoot } from "react-dom/client";
+import App from "./App";
+
+const root = createRoot(document.getElementById("root")!);
+root.render(
+ <React.StrictMode>
+ <App />
+ </React.StrictMode>
+);

examples/02-backend/04-rendering-static-documents/package.json

@@ -0,0 +1,38 @@
+{
+ "name": "@blocknote/example-rendering-static-documents",
+ "description": "AUTO-GENERATED FILE, DO NOT EDIT DIRECTLY",
+ "private": true,
+ "version": "0.12.4",
+ "scripts": {
+ "start": "vite",
+ "dev": "vite",
+ "build": "tsc && vite build",
+ "preview": "vite preview",
+ "lint": "eslint . --max-warnings 0"
+ },
+ "dependencies": {
+ "@blocknote/core": "latest",
+ "@blocknote/react": "latest",
+ "@blocknote/ariakit": "latest",
+ "@blocknote/mantine": "latest",
+ "@blocknote/shadcn": "latest",
+ "react": "^18.3.1",
+ "react-dom": "^18.3.1",
+ "@blocknote/server-util": "latest"
+ },
+ "devDependencies": {
+ "@types/react": "^18.0.25",
+ "@types/react-dom": "^18.0.9",
+ "@vitejs/plugin-react": "^4.0.4",
+ "eslint": "^8.10.0",
+ "vite": "^4.4.8"
+ },
+ "eslintConfig": {
+ "extends": [
+ "../../../.eslintrc.js"
+ ]
+ },
+ "eslintIgnore": [
+ "dist"
+ ]
+}

examples/02-backend/04-rendering-static-documents/tsconfig.json

@@ -0,0 +1,36 @@
+{
+ "__comment": "AUTO-GENERATED FILE, DO NOT EDIT DIRECTLY",
+ "compilerOptions": {
+ "target": "ESNext",
+ "useDefineForClassFields": true,
+ "lib": [
+ "DOM",
+ "DOM.Iterable",
+ "ESNext"
+ ],
+ "allowJs": false,
+ "skipLibCheck": true,
+ "esModuleInterop": false,
+ "allowSyntheticDefaultImports": true,
+ "strict": true,
+ "forceConsistentCasingInFileNames": true,
+ "module": "ESNext",
+ "moduleResolution": "Node",
+ "resolveJsonModule": true,
+ "isolatedModules": true,
+ "noEmit": true,
+ "jsx": "react-jsx",
+ "composite": true
+ },
+ "include": [
+ "."
+ ],
+ "__ADD_FOR_LOCAL_DEV_references": [
+ {
+ "path": "../../../packages/core/"
+ },
+ {
+ "path": "../../../packages/react/"
+ }
+ ]
+}

examples/02-backend/04-rendering-static-documents/vite.config.ts

@@ -0,0 +1,32 @@
+// AUTO-GENERATED FILE, DO NOT EDIT DIRECTLY
+import react from "@vitejs/plugin-react";
+import * as fs from "fs";
+import * as path from "path";
+import { defineConfig } from "vite";
+// import eslintPlugin from "vite-plugin-eslint";
+// https://vitejs.dev/config/
+export default defineConfig((conf) => ({
+ plugins: [react()],
+ optimizeDeps: {},
+ build: {
+ sourcemap: true,
+ },
+ resolve: {
+ alias:
+ conf.command === "build" ||
+ !fs.existsSync(path.resolve(__dirname, "../../packages/core/src"))
+ ? {}
+ : ({
+ // Comment out the lines below to load a built version of blocknote
+ // or, keep as is to load live from sources with live reload working
+ "@blocknote/core": path.resolve(
+ __dirname,
+ "../../packages/core/src/"
+ ),
+ "@blocknote/react": path.resolve(
+ __dirname,
+ "../../packages/react/src/"
+ ),
+ } as any),
+ },
+}));