` with
+ pass-through attributes.
+- [x] 3.4 `packages/vue/test/editor-ssr.test.ts` (node):
+ `renderToString(createSSRApp(...))` yields the container `
`.
+
+## 4. Docs
+
+- [x] 4.1 `README.md` / `README.zh.md`: "Server-side rendering & SSG"
+ section under API Reference with a Next.js App Router example.
+- [x] 4.2 `packages/core/README.md`: API section for the two functions.
+- [x] 4.3 `docs/ROADMAP.md` / `docs/ROADMAP.zh.md`: new Core Editor row
+ linking this change.
+
+## 5. Verification
+
+- [x] 5.1 `pnpm typecheck`, `pnpm test` and `pnpm build` pass locally.
diff --git a/packages/core/README.md b/packages/core/README.md
index 267f274e..278247bb 100644
--- a/packages/core/README.md
+++ b/packages/core/README.md
@@ -74,3 +74,28 @@ Multiple ranges in `setSelections` require `multiCursor: true` — without the f
## Other config highlights
See the `EditorConfig` type for the full surface: `livePreview`, `plugins`, `theme` / `setTheme`, `locale`, `readOnly`, `tabSize`, `direction`, `indentGuides`, `parseDelayMs`, `slashMenuLimit`, `onChange` / `onFocus` / `onBlur` / `onAssetUpload`.
+
+## Headless HTML rendering (SSR / SSG)
+
+`editor.exportHTML()` requires a mounted editor. The same pipeline is available
+without a DOM for server-side rendering, static-site builds and scripts:
+
+```ts
+import { createHtmlRenderer, renderMarkdownToHtml } from "@floatboat/nexus-core";
+import { createGfmPreset } from "@floatboat/nexus-preset-gfm";
+
+renderMarkdownToHtml("# Hello", { plugins: [createGfmPreset()] });
+// => "
Hello
"
+
+const renderer = createHtmlRenderer({ plugins: [createGfmPreset()] }); // build once
+renderer.render(markdownA);
+renderer.render(markdownB);
+```
+
+- `plugins` — the `NexusPlugin[]` you pass to `createEditor()`; only their
+ `remarkPlugins` participate. Same plugins ⇒ same HTML as `exportHTML()`.
+- `transform?: (tree: Root) => Root` — optional mdast hook applied after the
+ remark plugins, before HTML conversion.
+- Raw HTML nodes are dropped (remark-rehype default), so output is safe to embed.
+- Live-preview widgets (mermaid, syntax highlighting, KaTeX) are not part of
+ this pipeline; they render in the browser once the editor hydrates.
diff --git a/packages/core/src/editor.ts b/packages/core/src/editor.ts
index 4d356ea2..158b290f 100644
--- a/packages/core/src/editor.ts
+++ b/packages/core/src/editor.ts
@@ -9,9 +9,7 @@ import { indentWithTab, undo as cmUndo, redo as cmRedo } from "@codemirror/comma
import { closeBrackets } from "@codemirror/autocomplete";
import type { Root } from "mdast";
import type { Heading } from "mdast";
-import rehypeStringify from "rehype-stringify";
import remarkParse from "remark-parse";
-import remarkRehype from "remark-rehype";
import { unified } from "unified";
import { EventEmitter } from "./event-emitter";
@@ -49,6 +47,7 @@ import type {
SetDocumentOptions,
TocEntry,
} from "./types";
+import { createHtmlRenderer, type HtmlRenderer } from "./render-html";
import { createWidgetExtension } from "./widget-extension";
const FLOATBOAT_MARKDOWN_DEBUG_STORAGE_KEY = "floatboat:markdown-debug";
@@ -139,22 +138,6 @@ function lezerAstFromAnywhere(
return lezerStringToMdast(fallbackMarkdown);
}
-function markdownToHtml(
- markdown: string,
- plugins: NexusPlugin[],
- applyDynamicTransforms: (tree: Root) => Root,
-): string {
- const processor = unified().use(remarkParse);
- for (const plugin of plugins) {
- for (const rp of plugin.remarkPlugins ?? []) {
- processor.use(rp);
- }
- }
- processor.use(() => (tree) => applyDynamicTransforms(tree as Root));
- processor.use(remarkRehype).use(rehypeStringify);
- return String(processor.processSync(markdown));
-}
-
function extractToc(ast: Root): TocEntry[] {
const entries: TocEntry[] = [];
for (const node of ast.children) {
@@ -245,6 +228,9 @@ function createTransformProcessor(plugins: NexusPlugin[]): { runSync(tree: Root)
export function createEditor(config: EditorConfig): EditorAPI {
const plugins = config.plugins ?? [];
+ // Built lazily on first exportHTML() and reused afterwards: hosts that never
+ // export do not pay for the pipeline, hosts that export often pay once.
+ let htmlRenderer: HtmlRenderer | null = null;
debugNexus("create", {
initialLength: (config.initialValue ?? "").length,
pluginNames: plugins.map((plugin) => plugin.name),
@@ -787,11 +773,13 @@ export function createEditor(config: EditorConfig): EditorAPI {
return extractToc(currentAst);
},
exportHTML() {
- return markdownToHtml(
- view.state.doc.toString(),
- plugins,
- (tree) => applyMarkdownTransformSnapshots(view.state, tree),
- );
+ if (!htmlRenderer) {
+ htmlRenderer = createHtmlRenderer({
+ plugins,
+ transform: (tree) => applyMarkdownTransformSnapshots(view.state, tree),
+ });
+ }
+ return htmlRenderer.render(view.state.doc.toString());
},
setTheme(theme: NexusTheme) {
if (destroyed) return;
diff --git a/packages/core/src/index.ts b/packages/core/src/index.ts
index 11b2a643..47ff20f4 100644
--- a/packages/core/src/index.ts
+++ b/packages/core/src/index.ts
@@ -23,6 +23,12 @@ export {
widgetDefinitionSnapshotExtension,
} from "./markdown-contributions";
export { markdownAutoPair } from "./markdown-autopair";
+export {
+ createHtmlRenderer,
+ renderMarkdownToHtml,
+ type HtmlRenderer,
+ type HtmlRendererOptions,
+} from "./render-html";
export { markdownFold, markdownFoldService } from "./markdown-fold";
export { markdownKeymap, handleMarkdownEnter } from "./markdown-keymap";
export {
diff --git a/packages/core/src/render-html.ts b/packages/core/src/render-html.ts
new file mode 100644
index 00000000..d623caf8
--- /dev/null
+++ b/packages/core/src/render-html.ts
@@ -0,0 +1,75 @@
+import type { Root } from "mdast";
+import rehypeStringify from "rehype-stringify";
+import remarkParse from "remark-parse";
+import remarkRehype from "remark-rehype";
+import { unified } from "unified";
+
+import type { NexusPlugin } from "./types";
+
+/**
+ * Options shared by {@link createHtmlRenderer} and {@link renderMarkdownToHtml}.
+ */
+export interface HtmlRendererOptions {
+ /**
+ * Plugins whose `remarkPlugins` take part in the render pipeline. Pass the
+ * same list you give `createEditor()` so server-rendered HTML matches what
+ * `editor.exportHTML()` produces in the browser.
+ */
+ plugins?: NexusPlugin[];
+ /**
+ * Optional mdast transform applied after all remark plugins and before the
+ * tree is converted to HTML. The editor uses this hook to apply dynamic
+ * (runtime-contributed) transforms; hosts can use it to inject their own.
+ */
+ transform?: (tree: Root) => Root;
+}
+
+/**
+ * A reusable Markdown → HTML pipeline. Build it once and call `render()` for
+ * every document — the unified processor is resolved and frozen a single time,
+ * which matters when a static-site build renders hundreds of pages.
+ */
+export interface HtmlRenderer {
+ render(markdown: string): string;
+}
+
+/**
+ * Create a DOM-free Markdown → HTML renderer.
+ *
+ * It runs the exact pipeline behind `editor.exportHTML()` (remark-parse →
+ * plugin remark transforms → remark-rehype → rehype-stringify) but does not
+ * need a CodeMirror view, a container element, or a `document` global, so it
+ * can be used in Node.js for server-side rendering (SSR), static-site
+ * generation (SSG), CLIs and build scripts.
+ *
+ * Raw HTML nodes in the source are dropped (remark-rehype default), so the
+ * output is safe to embed without an extra sanitizer.
+ */
+export function createHtmlRenderer(options: HtmlRendererOptions = {}): HtmlRenderer {
+ const { plugins = [], transform } = options;
+ const processor = unified().use(remarkParse);
+ for (const plugin of plugins) {
+ for (const remarkPlugin of plugin.remarkPlugins ?? []) {
+ processor.use(remarkPlugin);
+ }
+ }
+ if (transform) {
+ processor.use(() => (tree) => transform(tree as Root));
+ }
+ processor.use(remarkRehype).use(rehypeStringify);
+ processor.freeze();
+
+ return {
+ render(markdown) {
+ return String(processor.processSync(markdown));
+ },
+ };
+}
+
+/**
+ * One-shot convenience wrapper around {@link createHtmlRenderer}. Prefer the
+ * factory when rendering many documents with the same plugin set.
+ */
+export function renderMarkdownToHtml(markdown: string, options?: HtmlRendererOptions): string {
+ return createHtmlRenderer(options).render(markdown);
+}
diff --git a/packages/core/test/render-html-editor.test.ts b/packages/core/test/render-html-editor.test.ts
new file mode 100644
index 00000000..f1f3f872
--- /dev/null
+++ b/packages/core/test/render-html-editor.test.ts
@@ -0,0 +1,36 @@
+// Default (jsdom) environment: compares the headless renderer with the
+// browser-side `editor.exportHTML()` so server and client output never drift.
+
+import { describe, expect, it } from "vitest";
+import { createGfmPreset } from "@floatboat/nexus-preset-gfm";
+import { createEditor, renderMarkdownToHtml } from "../src/index";
+
+describe("renderMarkdownToHtml vs editor.exportHTML()", () => {
+ it("produces identical HTML for the same document and plugins", () => {
+ const markdown = [
+ "# Title",
+ "",
+ "Some *emphasis*, `code` and a [link](https://example.com).",
+ "",
+ "| a | b |",
+ "|---|---|",
+ "| 1 | 2 |",
+ "",
+ "- [ ] todo",
+ "- [x] done",
+ ].join("\n");
+ const plugins = [createGfmPreset()];
+ const container = document.createElement("div");
+ const editor = createEditor({ container, initialValue: markdown, plugins });
+
+ try {
+ const fromEditor = editor.exportHTML();
+ const headless = renderMarkdownToHtml(markdown, { plugins });
+
+ expect(fromEditor).toContain("
");
+ expect(headless).toBe(fromEditor);
+ } finally {
+ editor.destroy();
+ }
+ });
+});
diff --git a/packages/core/test/render-html.test.ts b/packages/core/test/render-html.test.ts
new file mode 100644
index 00000000..4cd63544
--- /dev/null
+++ b/packages/core/test/render-html.test.ts
@@ -0,0 +1,75 @@
+// @vitest-environment node
+//
+// Runs WITHOUT jsdom on purpose: this file proves the HTML renderer works in a
+// plain Node.js process (SSR / SSG / build scripts), where `document` and
+// `window` do not exist.
+
+import { describe, expect, it } from "vitest";
+import { createGfmPreset } from "@floatboat/nexus-preset-gfm";
+import { createHtmlRenderer, renderMarkdownToHtml } from "../src/index";
+
+describe("renderMarkdownToHtml (headless)", () => {
+ it("runs in an environment without a DOM", () => {
+ expect(typeof document).toBe("undefined");
+ expect(typeof window).toBe("undefined");
+ });
+
+ it("renders basic Markdown to HTML without a DOM", () => {
+ const html = renderMarkdownToHtml("# Hello\n\nSome **bold** text.");
+
+ expect(html).toContain("Hello
");
+ expect(html).toContain("bold");
+ });
+
+ it("returns an empty string for an empty document", () => {
+ expect(renderMarkdownToHtml("")).toBe("");
+ });
+
+ it("honours remark plugins contributed by NexusPlugin instances", () => {
+ const table = "| a | b |\n|---|---|\n| 1 | 2 |";
+
+ expect(renderMarkdownToHtml(table)).not.toContain("");
+ expect(renderMarkdownToHtml(table, { plugins: [createGfmPreset()] })).toContain("");
+ });
+
+ it("does not pass raw HTML through by default", () => {
+ const html = renderMarkdownToHtml("before\n\n\n\nafter");
+
+ expect(html).not.toContain("before");
+ expect(html).toContain("after
");
+ });
+
+ it("applies an optional mdast transform before HTML conversion", () => {
+ const html = renderMarkdownToHtml("# Title", {
+ transform: (tree) => {
+ for (const node of tree.children) {
+ if (node.type === "heading") node.depth = 2;
+ }
+ return tree;
+ },
+ });
+
+ expect(html).toContain("Title
");
+ expect(html).not.toContain("");
+ });
+});
+
+describe("createHtmlRenderer", () => {
+ it("can render many documents with one pipeline", () => {
+ const renderer = createHtmlRenderer({ plugins: [createGfmPreset()] });
+
+ expect(renderer.render("~~gone~~")).toContain("gone");
+ expect(renderer.render("# Second")).toContain("Second
");
+ expect(renderer.render("# Second")).not.toContain("");
+ });
+
+ it("produces the same output as the one-shot helper", () => {
+ const markdown = "- [ ] todo\n- [x] done";
+ const plugins = [createGfmPreset()];
+
+ expect(createHtmlRenderer({ plugins }).render(markdown)).toBe(
+ renderMarkdownToHtml(markdown, { plugins }),
+ );
+ });
+});
diff --git a/packages/react/test/editor-ssr.test.tsx b/packages/react/test/editor-ssr.test.tsx
new file mode 100644
index 00000000..a64a09b6
--- /dev/null
+++ b/packages/react/test/editor-ssr.test.tsx
@@ -0,0 +1,22 @@
+// @vitest-environment node
+//
+// Guards the SSR contract of `@floatboat/nexus-react`: rendering on
+// the server (Next.js, Remix, ...) must produce the container markup without
+// touching `document` or `window`. The CodeMirror instance is created only
+// inside an effect, which never runs during server rendering.
+
+import { renderToString } from "react-dom/server";
+import { describe, expect, it } from "vitest";
+import { Editor } from "../src/index";
+
+describe(" server-side rendering", () => {
+ it("renders the container element without a DOM", () => {
+ expect(typeof document).toBe("undefined");
+
+ const html = renderToString(
+ ,
+ );
+
+ expect(html).toBe('');
+ });
+});
diff --git a/packages/vue/test/editor-ssr.test.ts b/packages/vue/test/editor-ssr.test.ts
new file mode 100644
index 00000000..396c2caa
--- /dev/null
+++ b/packages/vue/test/editor-ssr.test.ts
@@ -0,0 +1,24 @@
+// @vitest-environment node
+//
+// Guards the SSR contract of `@floatboat/nexus-vue`: rendering on
+// the server (Nuxt, ...) must produce the container markup without touching
+// `document` or `window`. The CodeMirror instance is created only in
+// `onMounted`, which never runs during server rendering.
+
+import { createSSRApp, h } from "vue";
+import { renderToString } from "vue/server-renderer";
+import { describe, expect, it } from "vitest";
+import { Editor } from "../src/index";
+
+describe(" server-side rendering", () => {
+ it("renders the container element without a DOM", async () => {
+ expect(typeof document).toBe("undefined");
+
+ const app = createSSRApp({
+ render: () => h(Editor, { initialValue: "# Hello", class: "nexus-editor" }),
+ });
+ const html = await renderToString(app);
+
+ expect(html).toBe('');
+ });
+});