@sillsdev/docu-notion 0.17.0-alpha.4 → 1.0.0-alpha.2

package/README.md

@@ -4,6 +4,24 @@ docu-notion lets you use Notion as your editor for [Docusaurus](https://docusaur
 
 Example Site: https://sillsdev.github.io/docu-notion-sample-site/
 
+# Docusaurus 3 Output
+
+docu-notion emits Docusaurus v3-compatible markdown by default.
+
+The default output changed in these ways:
+
+- Heading anchors are emitted with Docusaurus v3's MDX-comment syntax, for example `# Heading {/* #my-explicit-id */}`, instead of Docusaurus v2's `{#...}` syntax.
+- `⚠️` callouts now emit `:::warning[Caution]` instead of the deprecated `:::caution` syntax.
+- Callouts with unrecognized emojis now emit `:::note[emoji]` instead of using the emoji itself as a custom admonition keyword.
+- Named Notion callout icons that are not returned by the API as emoji are ignored and fall back to a plain `:::note` admonition.
+- docu-notion now warns when a generated page contains more than one Markdown H1, and the warning lists the H1 headings it found.
+
+If you need the previous output, pass `--docusaurus-v2`. This restores the legacy heading ID syntax, the `:::caution` output, and the raw-emoji admonition fallback.
+
+If you use `--docusaurus-v2` on Docusaurus v3, keep the `markdown.mdx1Compat.headingIds` and `markdown.mdx1Compat.admonitions` compatibility options enabled. They are on by default in Docusaurus v3, but some sites turn them off during migration.
+
+When upgrading an existing Docusaurus site to v3, it is also worth running `npx docusaurus-mdx-checker` on the site to catch MDX v3 issues in any hand-written docs or custom plugin output.
+
 # Instructions
 
 ## 1. Set up your documentation site
@@ -122,19 +140,20 @@ Usage: `docu-notion -n <token> -r <root> [options]`
 
 Options:
 
-| flag                                  | required? | description                                                                                                                                                                                                        |
-| ------------------------------------- | --------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
-| `-n, --notion-token <string>`           | required  | notion api token, which looks like `secret_3bc1b50XFYb15123RHF243x43450XFY33250XFYa343`                                                                                                                            |
-| `-r, --root-page <string>`              | required  | The 31 character ID of the page which is the root of your docs page in notion. The code will look like `9120ec9960244ead80fa2ef4bc1bba25`. This page must have a child page named 'Outline'                        |
-| `-m, --markdown-output-path <string>`   |           | Root of the hierarchy for md files. WARNING: node-pull-mdx will delete files from this directory. Note also that if it finds localized images, it will create an i18n/ directory as a sibling. (default: `./docs`) |
-| `-t, --status-tag <string>`             |           | Database pages without a Notion page property 'status' matching this will be ignored. Use '\*' to ignore status altogether. (default: `Publish`)                                                                   |
-| `--locales <codes>`                     |           | Comma-separated list of iso 639-2 codes, the same list as in docusaurus.config.js, minus the primary (i.e. 'en'). This is needed for image localization. (default: `[]`)                                             |
-| `-l, --log-level <level>`               |           | Log level (choices: `info`, `verbose`, `debug`)                                                                                                                                                                    |
-| `-i, --img-output-path <string>`        |           | Path to directory where images will be stored. If this is not included, images will be placed in the same directory as the document that uses them, which then allows for localization of screenshots.             |
-| `-p, --img-prefix-in-markdown <string>` |           | When referencing an image from markdown, prefix with this path instead of the full img-output-path. Should be used only in conjunction with --img-output-path.                                                     |
-| `--require-slugs`                       |           | If set, docu-notion will fail if any pages it would otherwise publish are missing a slug in Notion. |
+| flag                                    | required? | description                                                                                                                                                                                                                                                                                                         |
+| --------------------------------------- | --------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `-n, --notion-token <string>`           | required  | notion api token, which looks like `secret_3bc1b50XFYb15123RHF243x43450XFY33250XFYa343`                                                                                                                                                                                                                             |
+| `-r, --root-page <string>`              | required  | The 31 character ID of the page which is the root of your docs page in notion. The code will look like `9120ec9960244ead80fa2ef4bc1bba25`. This page must have a child page named 'Outline'                                                                                                                         |
+| `-m, --markdown-output-path <string>`   |           | Root of the hierarchy for md files. WARNING: node-pull-mdx will delete files from this directory. Note also that if it finds localized images, it will create an i18n/ directory as a sibling. (default: `./docs`)                                                                                                  |
+| `-t, --status-tag <string>`             |           | Database pages without a Notion page property 'status' matching this will be ignored. Use '\*' to ignore status altogether. (default: `Publish`)                                                                                                                                                                    |
+| `--locales <codes>`                     |           | Comma-separated list of iso 639-2 codes, the same list as in docusaurus.config.js, minus the primary (i.e. 'en'). This is needed for image localization. (default: `[]`)                                                                                                                                            |
+| `-l, --log-level <level>`               |           | Log level (choices: `info`, `verbose`, `debug`)                                                                                                                                                                                                                                                                     |
+| `-i, --img-output-path <string>`        |           | Path to directory where images will be stored. If this is not included, images will be placed in the same directory as the document that uses them, which then allows for localization of screenshots.                                                                                                              |
+| `-p, --img-prefix-in-markdown <string>` |           | When referencing an image from markdown, prefix with this path instead of the full img-output-path. Should be used only in conjunction with --img-output-path.                                                                                                                                                      |
+| `--require-slugs`                       |           | If set, docu-notion will fail if any pages it would otherwise publish are missing a slug in Notion.                                                                                                                                                                                                                 |
+| `--docusaurus-v2`                       |           | Emit Docusaurus v2-compatible markdown instead of the default Docusaurus v3-compatible output. This preserves legacy heading IDs, `:::caution`, and raw-emoji admonition keywords.                                                                                                                                  |
 | `--image-file-name-format <format>`     |           | choices:<ul><li>`default`: {page slug (if any)}.{image block ID}</li><li>`content-hash`: Use a hash of the image content.</li><li>`legacy`: Use the legacy (before v0.16) method of determining file names. Set this to maintain backward compatibility.</li></ul>All formats will use the original file extension. |
-| `-h, --help`                            |           | display help for command                              |
+| `-h, --help`                            |           | display help for command                                                                                                                                                                                                                                                                                            |
 
 # Plugins
 
@@ -142,16 +161,19 @@ If your project needs some processing that docu-notion doesn't already provide,
 
 # Callouts ➜ Admonitions
 
-To map Notion callouts to Docusaurus admonitions, ensure the icon is for the type you want.
+To map Notion callouts to Docusaurus admonitions, ensure the icon is an emoji for the type you want.
 
 - ℹ️ ➜ note
 - 📝➜ note
 - 💡➜ tip
 - ❗➜ info
-- ⚠️➜ caution
+- ⚠️➜ warning[Caution]
 - 🔥➜ danger
+- unknown emoji ➜ note[emoji]
+
+If a Notion callout uses a named Notion icon instead of an emoji, docu-notion does not try to synthesize an equivalent symbol from the icon name or color. Those callouts fall back to a plain `:::note` admonition.
 
-The default admonition type, if no matching icon is found, is "note".
+The default admonition type, if no matching icon is found, is "note". Use `--docusaurus-v2` to keep the legacy `⚠️ ➜ caution` behavior and the old raw-emoji fallback.
 
 # Known Workarounds
 

package/dist/latex.spec.js

@@ -49,6 +49,7 @@ test("Latex Rendering", () => __awaiter(void 0, void 0, void 0, function* () {
             imgOutputPath: "",
             imgPrefixInMarkdown: "",
             statusTag: "",
+            docusaurusV2: false,
         },
         pages: pages,
         counts: counts, // review will this get copied or pointed to?

package/dist/plugins/CalloutTransformer.js

@@ -10,14 +10,14 @@ var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, ge
 };
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.standardCalloutTransformer = void 0;
-// In Notion, you can make a callout and change its emoji. We map 5 of these
-// to the 5 Docusaurus admonition styles.
+// In Notion, you can make a callout and change its emoji. We map common callout
+// emojis to the built-in Docusaurus admonition styles.
 // This is mostly a copy of the callout code from notion-to-md. The change is to output docusaurus
 // admonitions instead of emulating a callout with markdown > syntax.
 // Note: I haven't yet tested this with any emoji except "💡"/"tip", nor the case where the
 // callout has-children. Not even sure what that would mean, since the document I was testing
 // with has quite complex markup inside the callout, but still takes the no-children branch.
-function notionCalloutToAdmonition(notionToMarkdown, getBlockChildren, block) {
+function notionCalloutToAdmonition(context, block) {
     return __awaiter(this, void 0, void 0, function* () {
         // In this case typescript is not able to index the types properly, hence ignoring the error
         // @ts-ignore
@@ -28,7 +28,7 @@ function notionCalloutToAdmonition(notionToMarkdown, getBlockChildren, block) {
         blockContent.map((content) => {
             const annotations = content.annotations;
             let plain_text = content.plain_text;
-            plain_text = notionToMarkdown.annotatePlainText(plain_text, annotations);
+            plain_text = context.notionToMarkdown.annotatePlainText(plain_text, annotations);
             if (content["href"])
                 plain_text = `[${plain_text}](${content["href"]})`;
             parsedData += plain_text;
@@ -36,17 +36,17 @@ function notionCalloutToAdmonition(notionToMarkdown, getBlockChildren, block) {
         let callout_string = "";
         const { id, has_children } = block;
         if (!has_children) {
-            const result1 = callout(parsedData, icon);
+            const result1 = callout(parsedData, icon, context.options);
             return result1;
         }
-        const callout_children_object = yield getBlockChildren(id);
+        const callout_children_object = yield context.getBlockChildren(id);
         // // parse children blocks to md object
-        const callout_children = yield notionToMarkdown.blocksToMarkdown(callout_children_object);
+        const callout_children = yield context.notionToMarkdown.blocksToMarkdown(callout_children_object);
         callout_string += `${parsedData}\n`;
         callout_children.map(child => {
             callout_string += `${child.parent}\n\n`;
         });
-        const result = callout(callout_string.trim(), icon);
+        const result = callout(callout_string.trim(), icon, context.options);
         return result;
     });
 }
@@ -55,34 +55,46 @@ const calloutsToAdmonitions = {
     "📝": "note",
     "💡": "tip",
     "❗": "info",
-    "⚠️": "caution",
+    "⚠️": "warning",
     "🔥": "danger",
 };
 // This is the main change from the notion-to-md code.
-function callout(text, icon) {
-    var _a;
+function callout(text, icon, options) {
+    var _a, _b, _c;
     let emoji;
     if ((icon === null || icon === void 0 ? void 0 : icon.type) === "emoji") {
         emoji = icon.emoji;
     }
+    const docusaurusV2 = (_a = options.docusaurusV2) !== null && _a !== void 0 ? _a : false;
     let docusaurusAdmonition = "note";
+    let admonitionTitle = "";
     if (emoji) {
+        if (docusaurusV2) {
+            docusaurusAdmonition =
+                (_b = calloutsToAdmonitions[emoji]) !== null && _b !== void 0 ? _b : emoji;
+            if (docusaurusAdmonition === "warning") {
+                docusaurusAdmonition = "caution";
+            }
+            return `:::${docusaurusAdmonition}\n\n${text}\n\n:::\n\n`;
+        }
         // the keyof typeof magic persuades typescript that it really is OK to use emoji as a key into calloutsToAdmonitions
         docusaurusAdmonition =
-            (_a = calloutsToAdmonitions[emoji]) !== null && _a !== void 0 ? _a : 
-            // For Notion callouts with other emojis, pass them through using hte emoji as the name.
-            // For this to work on a Docusaurus site, it will need to define that time on the remark-admonitions options in the docusaurus.config.js.
-            // See https://github.com/elviswolcott/remark-admonitions and https://docusaurus.io/docs/using-plugins#using-presets.
-            emoji;
+            (_c = calloutsToAdmonitions[emoji]) !== null && _c !== void 0 ? _c : "note";
+        if (emoji === "⚠️") {
+            admonitionTitle = "[Caution]";
+        }
+        else if (!(emoji in calloutsToAdmonitions)) {
+            admonitionTitle = `[${emoji}]`;
+        }
     }
-    return `:::${docusaurusAdmonition}\n\n${text}\n\n:::\n\n`;
+    return `:::${docusaurusAdmonition}${admonitionTitle}\n\n${text}\n\n:::\n\n`;
 }
 exports.standardCalloutTransformer = {
     name: "standardCalloutTransformer",
     notionToMarkdownTransforms: [
         {
             type: "callout",
-            getStringFromBlock: (context, block) => notionCalloutToAdmonition(context.notionToMarkdown, context.getBlockChildren, block),
+            getStringFromBlock: (context, block) => notionCalloutToAdmonition(context, block),
         },
     ],
 };

package/dist/plugins/CalloutTransformer.spec.js

@@ -116,7 +116,7 @@ test("external link inside callout, bold preserved", () => __awaiter(void 0, voi
             },
         },
     ]);
-    expect(results.trim()).toBe(`:::caution
+    expect(results.trim()).toBe(`:::warning[Caution]
 
 Callouts inline [**great page**](https://github.com).
 
@@ -191,9 +191,46 @@ test("internal link inside callout, bold preserved", () => __awaiter(void 0, voi
             },
         },
     ], [slugTargetPage]);
-    expect(results.trim()).toBe(`:::caution
+    expect(results.trim()).toBe(`:::warning[Caution]
 
 Callouts inline [**great page**](/hello-world#456) the end.
 
 :::`);
 }));
+test("unknown emoji callout falls back to note with title in docusaurus v3 mode", () => __awaiter(void 0, void 0, void 0, function* () {
+    const config = { plugins: [CalloutTransformer_1.standardCalloutTransformer] };
+    block.callout.icon.emoji = "🧪";
+    const results = yield (0, pluginTestRun_1.blocksToMarkdown)(config, [
+        block,
+    ]);
+    expect(results.trim()).toBe(`:::note[🧪]
+
+This is the callout
+
+:::`);
+}));
+test("named notion icon callout falls back to plain note in docusaurus v3 mode", () => __awaiter(void 0, void 0, void 0, function* () {
+    const config = { plugins: [CalloutTransformer_1.standardCalloutTransformer] };
+    block.callout.icon = {
+        type: "icon",
+        icon: { name: "airplane", color: "purple" },
+    };
+    const results = yield (0, pluginTestRun_1.blocksToMarkdown)(config, [
+        block,
+    ]);
+    expect(results.trim()).toBe(`:::note
+
+This is the callout
+
+:::`);
+}));
+test("docusaurus-v2 flag keeps legacy callout syntax", () => __awaiter(void 0, void 0, void 0, function* () {
+    const config = { plugins: [CalloutTransformer_1.standardCalloutTransformer] };
+    block.callout.icon.emoji = "⚠️";
+    const results = yield (0, pluginTestRun_1.blocksToMarkdown)(config, [block], undefined, undefined, undefined, { docusaurusV2: true });
+    expect(results.trim()).toBe(`:::caution
+
+This is the callout
+
+:::`);
+}));

package/dist/plugins/HeadingTranformer.spec.js

@@ -11,36 +11,124 @@ var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, ge
 Object.defineProperty(exports, "__esModule", { value: true });
 const pluginTestRun_1 = require("./pluginTestRun");
 const HeadingTransformer_1 = require("./HeadingTransformer");
+function makeHeadingBlock(headingBlockId, text, type = "heading_1") {
+    return {
+        object: "block",
+        id: headingBlockId,
+        type,
+        [type]: {
+            rich_text: [
+                {
+                    type: "text",
+                    text: { content: text, link: null },
+                    annotations: {
+                        bold: false,
+                        italic: false,
+                        strikethrough: false,
+                        underline: false,
+                        code: false,
+                        color: "default",
+                    },
+                    plain_text: text,
+                    href: null,
+                },
+            ],
+            is_toggleable: false,
+            color: "default",
+        },
+    };
+}
+function makeCodeBlock(text, language = "") {
+    return {
+        object: "block",
+        id: "33333333-3333-3333-3333-333333333333",
+        type: "code",
+        code: {
+            caption: [],
+            rich_text: [
+                {
+                    type: "text",
+                    text: { content: text, link: null },
+                    annotations: {
+                        bold: false,
+                        italic: false,
+                        strikethrough: false,
+                        underline: false,
+                        code: false,
+                        color: "default",
+                    },
+                    plain_text: text,
+                    href: null,
+                },
+            ],
+            language,
+        },
+    };
+}
 test("Adds anchor to headings", () => __awaiter(void 0, void 0, void 0, function* () {
     //setLogLevel("verbose");
     const headingBlockId = "86f746f4-1c79-4ba1-a2f6-a1d59c2f9d23";
     const config = { plugins: [HeadingTransformer_1.standardHeadingTransformer] };
     const result = yield (0, pluginTestRun_1.blocksToMarkdown)(config, [
-        {
-            object: "block",
-            id: headingBlockId,
-            type: "heading_1",
-            heading_1: {
-                rich_text: [
-                    {
-                        type: "text",
-                        text: { content: "Heading One", link: null },
-                        annotations: {
-                            bold: false,
-                            italic: false,
-                            strikethrough: false,
-                            underline: false,
-                            code: false,
-                            color: "default",
-                        },
-                        plain_text: "Heading One",
-                        href: null,
-                    },
-                ],
-                is_toggleable: false,
-                color: "default",
-            },
-        },
+        makeHeadingBlock(headingBlockId, "Heading One"),
     ]);
+    expect(result.trim()).toBe(`# Heading One {/* #${headingBlockId.replaceAll("-", "")} */}`);
+}));
+test("Adds anchor to H4 headings", () => __awaiter(void 0, void 0, void 0, function* () {
+    const headingBlockId = "86f746f4-1c79-4ba1-a2f6-a1d59c2f9d23";
+    const config = { plugins: [HeadingTransformer_1.standardHeadingTransformer] };
+    const result = yield (0, pluginTestRun_1.blocksToMarkdown)(config, [
+        makeHeadingBlock(headingBlockId, "Heading Four", "heading_4"),
+    ]);
+    expect(result.trim()).toBe(`#### Heading Four {/* #${headingBlockId.replaceAll("-", "")} */}`);
+}));
+test("docusaurus-v2 flag keeps legacy heading id syntax", () => __awaiter(void 0, void 0, void 0, function* () {
+    const headingBlockId = "86f746f4-1c79-4ba1-a2f6-a1d59c2f9d23";
+    const config = { plugins: [HeadingTransformer_1.standardHeadingTransformer] };
+    const result = yield (0, pluginTestRun_1.blocksToMarkdown)(config, [makeHeadingBlock(headingBlockId, "Heading One")], undefined, undefined, undefined, { docusaurusV2: true });
     expect(result.trim()).toBe(`# Heading One {#${headingBlockId.replaceAll("-", "")}}`);
 }));
+test("warns when more than one H1 is generated for a page", () => __awaiter(void 0, void 0, void 0, function* () {
+    const consoleLogSpy = vi
+        .spyOn(console, "log")
+        .mockImplementation(() => undefined);
+    try {
+        yield (0, pluginTestRun_1.blocksToMarkdown)({ plugins: [HeadingTransformer_1.standardHeadingTransformer] }, [
+            makeHeadingBlock("11111111-1111-1111-1111-111111111111", "Heading One"),
+            makeHeadingBlock("22222222-2222-2222-2222-222222222222", "Heading Two"),
+        ]);
+    }
+    finally {
+        expect(consoleLogSpy.mock.calls.some(call => String(call[0]).includes('contains 2 H1 headings. Docusaurus pages should have at most one H1. H1 headings: "Heading One", "Heading Two".'))).toBe(true);
+        consoleLogSpy.mockRestore();
+    }
+}));
+test("does not warn when multiple markdown-style H1 lines appear inside a code block", () => __awaiter(void 0, void 0, void 0, function* () {
+    const consoleLogSpy = vi
+        .spyOn(console, "log")
+        .mockImplementation(() => undefined);
+    try {
+        yield (0, pluginTestRun_1.blocksToMarkdown)({ plugins: [HeadingTransformer_1.standardHeadingTransformer] }, [
+            makeCodeBlock("# Not a heading\n# Still not a heading", "markdown"),
+        ]);
+    }
+    finally {
+        expect(consoleLogSpy.mock.calls.some(call => String(call[0]).includes("H1 headings"))).toBe(false);
+        consoleLogSpy.mockRestore();
+    }
+}));
+test("does not count markdown-style H1 lines inside code blocks toward the page H1 warning", () => __awaiter(void 0, void 0, void 0, function* () {
+    const consoleLogSpy = vi
+        .spyOn(console, "log")
+        .mockImplementation(() => undefined);
+    try {
+        yield (0, pluginTestRun_1.blocksToMarkdown)({ plugins: [HeadingTransformer_1.standardHeadingTransformer] }, [
+            makeHeadingBlock("11111111-1111-1111-1111-111111111111", "Heading One"),
+            makeCodeBlock("# Not a heading", "markdown"),
+        ]);
+    }
+    finally {
+        expect(consoleLogSpy.mock.calls.some(call => String(call[0]).includes("H1 headings"))).toBe(false);
+        consoleLogSpy.mockRestore();
+    }
+}));

package/dist/plugins/HeadingTransformer.js

@@ -11,23 +11,50 @@ var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, ge
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.standardHeadingTransformer = void 0;
 const log_1 = require("../log");
+function renderHeadingText(context, block, type) {
+    // Work around notion-to-md only shipping built-in heading renderers for
+    // heading_1 through heading_3. For heading_4 and above we still reuse its
+    // inline annotation logic, but we assemble the heading markdown ourselves.
+    const headingBlock = block[type];
+    const blockContent = (headingBlock === null || headingBlock === void 0 ? void 0 : headingBlock.text) || (headingBlock === null || headingBlock === void 0 ? void 0 : headingBlock.rich_text) || [];
+    return blockContent
+        .map((content) => {
+        if (content.type === "equation" && content.equation) {
+            return `$${content.equation.expression}$`;
+        }
+        let plainText = context.notionToMarkdown.annotatePlainText(content.plain_text, content.annotations);
+        if (content.href) {
+            plainText = `[${plainText}](${content.href})`;
+        }
+        return plainText;
+    })
+        .join("");
+}
 // Makes links to headings work in docusaurus
 // https://github.com/sillsdev/docu-notion/issues/20
-function headingTransformer(notionToMarkdown, block) {
+function headingTransformer(context, block) {
     return __awaiter(this, void 0, void 0, function* () {
         // First, remove the prefix we added to the heading type
-        block.type = block.type.replace("DN_", "");
-        const markdown = yield notionToMarkdown.blockToMarkdown(block);
+        const type = block.type.replace("DN_", "");
+        block.type = type;
+        const headingLevel = Number(type.replace("heading_", ""));
+        const markdown = headingLevel <= 3
+            ? yield context.notionToMarkdown.blockToMarkdown(block)
+            // notion-to-md 3.1.1 falls through on heading_4+ and crashes trying to
+            // read block[type].text, so render those levels locally.
+            : `${"#".repeat(headingLevel)} ${renderHeadingText(context, block, type)}`;
         (0, log_1.logDebug)("headingTransformer, markdown of a heading before adding id", markdown);
-        // To make heading links work in docusaurus, we append an id. E.g.
-        //  ### Hello World {#my-explicit-id}
-        // See https://docusaurus.io/docs/markdown-features/toc#heading-ids.
+        // To make heading links work in Docusaurus, we add a stable block-id anchor.
+        // Docusaurus v2 uses explicit heading IDs, while the v3 default can use the
+        // MDX comment syntax at the end of the heading.
         // For some reason, inline links come in without the dashes, so we have to strip
         // dashes here to match them.
         //console.log("block.id", block.id)
         const blockIdWithoutDashes = block.id.replaceAll("-", "");
         // Finally, append the block id so that it can be the target of a link.
-        return `${markdown} {#${blockIdWithoutDashes}}`;
+        if (context.options.docusaurusV2)
+            return `${markdown} {#${blockIdWithoutDashes}}`;
+        return `${markdown} {/* #${blockIdWithoutDashes} */}`;
     });
 }
 exports.standardHeadingTransformer = {
@@ -49,15 +76,21 @@ exports.standardHeadingTransformer = {
     notionToMarkdownTransforms: [
         {
             type: "DN_heading_1",
-            getStringFromBlock: (context, block) => headingTransformer(context.notionToMarkdown, block),
+            getStringFromBlock: (context, block) => headingTransformer(context, block),
         },
         {
             type: "DN_heading_2",
-            getStringFromBlock: (context, block) => headingTransformer(context.notionToMarkdown, block),
+            getStringFromBlock: (context, block) => headingTransformer(context, block),
         },
         {
             type: "DN_heading_3",
-            getStringFromBlock: (context, block) => headingTransformer(context.notionToMarkdown, block),
+            getStringFromBlock: (context, block) => headingTransformer(context, block),
+        },
+        {
+            type: "DN_heading_4",
+            // Keep this explicit so H4 blocks take the local workaround path instead
+            // of being handed back to notion-to-md's unsupported default branch.
+            getStringFromBlock: (context, block) => headingTransformer(context, block),
         },
     ],
 };

package/dist/plugins/internalLinks.spec.js

@@ -559,7 +559,7 @@ test("internal link inside callout", () => __awaiter(void 0, void 0, void 0, fun
             color: "gray_background",
         },
     }, targetPage);
-    expect(results.trim()).toBe(`:::caution
+    expect(results.trim()).toBe(`:::warning[Caution]
 
 Callouts inline [great page](/hello-world).
 

package/dist/plugins/pluginTestRun.d.ts

@@ -1,11 +1,12 @@
 import { NotionPage } from "../NotionPage";
 import { IDocuNotionConfig } from "../config/configuration";
+import { DocuNotionOptions } from "../pull";
 import { NotionBlock } from "../types";
 export declare const kTemporaryTestDirectory = "tempTestFileDir";
-export declare function blocksToMarkdown(config: IDocuNotionConfig, blocks: NotionBlock[], pages?: NotionPage[], children?: NotionBlock[], validApiKey?: string): Promise<string>;
+export declare function blocksToMarkdown(config: IDocuNotionConfig, blocks: NotionBlock[], pages?: NotionPage[], children?: NotionBlock[], validApiKey?: string, optionsOverrides?: Partial<DocuNotionOptions>): Promise<string>;
 export declare function makeSamplePageObject(options: {
     slug?: string;
     name?: string;
     id?: string;
 }): NotionPage;
-export declare function oneBlockToMarkdown(config: IDocuNotionConfig, block: Record<string, unknown>, targetPage?: NotionPage, targetPage2?: NotionPage): Promise<string>;
+export declare function oneBlockToMarkdown(config: IDocuNotionConfig, block: Record<string, unknown>, targetPage?: NotionPage, targetPage2?: NotionPage, optionsOverrides?: Partial<DocuNotionOptions>): Promise<string>;

package/dist/plugins/pluginTestRun.js

@@ -26,7 +26,7 @@ function blocksToMarkdown(config, blocks, pages,
 //   - These children will apply to each block in blocks. (could enhance but not needed yet)
 //   - If you are passing in children, it is probably because your parent block has has_children=true.
 //     In that case, notion-to-md will make an API call... you'll need to set any validApiKey.
-children, validApiKey) {
+children, validApiKey, optionsOverrides) {
     return __awaiter(this, void 0, void 0, function* () {
         const notionClient = new client_1.Client({
             auth: validApiKey || "unused",
@@ -59,15 +59,7 @@ children, validApiKey) {
                 slug: "not yet",
             },
             layoutStrategy: new HierarchicalNamedLayoutStrategy_1.HierarchicalNamedLayoutStrategy(),
-            options: {
-                notionToken: "",
-                rootPage: "",
-                locales: [],
-                markdownOutputPath: "",
-                imgOutputPath: "",
-                imgPrefixInMarkdown: "",
-                statusTag: "",
-            },
+            options: Object.assign({ notionToken: "", rootPage: "", locales: [], markdownOutputPath: "", imgOutputPath: "", imgPrefixInMarkdown: "", statusTag: "", docusaurusV2: false }, optionsOverrides),
             pages: pages !== null && pages !== void 0 ? pages : [],
             counts: {
                 output_normally: 0,
@@ -228,7 +220,7 @@ function makeSamplePageObject(options) {
     // console.log(p.matchesLinkId);
     return p;
 }
-function oneBlockToMarkdown(config, block, targetPage, targetPage2) {
+function oneBlockToMarkdown(config, block, targetPage, targetPage2, optionsOverrides) {
     return __awaiter(this, void 0, void 0, function* () {
         // just in case someone expects these other properties that aren't normally relevant,
         // we merge the given block properties into an actual, full block
@@ -260,6 +252,8 @@ function oneBlockToMarkdown(config, block, targetPage, targetPage2) {
             slug: "dummy2",
             name: "Dummy2",
         });
-        return yield blocksToMarkdown(config, [fullBlock], targetPage ? [dummyPage1, targetPage, targetPage2 !== null && targetPage2 !== void 0 ? targetPage2 : dummyPage2] : undefined);
+        return yield blocksToMarkdown(config, [fullBlock], targetPage
+            ? [dummyPage1, targetPage, targetPage2 !== null && targetPage2 !== void 0 ? targetPage2 : dummyPage2]
+            : undefined, undefined, undefined, optionsOverrides);
     });
 }

package/dist/pull.d.ts

@@ -11,7 +11,11 @@ export type DocuNotionOptions = {
     statusTag: string;
     requireSlugs?: boolean;
     imageFileNameFormat?: ImageFileNameFormat;
+    docusaurusV2?: boolean;
 };
+export declare function getOptionsForLogging<T extends {
+    notionToken: string;
+}>(options: T): T;
 export declare function notionPull(options: DocuNotionOptions): Promise<void>;
 export declare function executeWithRateLimitAndRetries<T>(label: string, asyncFunction: () => Promise<T>): Promise<T>;
 export declare function initNotionClient(notionToken: string): Client;

package/dist/pull.js

@@ -42,6 +42,7 @@ var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, ge
     });
 };
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.getOptionsForLogging = getOptionsForLogging;
 exports.notionPull = notionPull;
 exports.executeWithRateLimitAndRetries = executeWithRateLimitAndRetries;
 exports.initNotionClient = initNotionClient;
@@ -59,6 +60,9 @@ const limiter_1 = require("limiter");
 const process_1 = require("process");
 const configuration_1 = require("./config/configuration");
 const internalLinks_1 = require("./plugins/internalLinks");
+function getOptionsForLogging(options) {
+    return Object.assign(Object.assign({}, options), { notionToken: options.notionToken.substring(0, 10) + "..." });
+}
 const kNotionApiVersion = "2026-03-11";
 let layoutStrategy;
 let notionToMarkdown;
@@ -73,11 +77,7 @@ const counts = {
 function notionPull(options) {
     return __awaiter(this, void 0, void 0, function* () {
         // It's helpful when troubleshooting CI secrets and environment variables to see what options actually made it to docu-notion.
-        // eslint-disable-next-line @typescript-eslint/no-unsafe-call
-        const optionsForLogging = Object.assign({}, options);
-        // Just show the first few letters of the notion token, which start with "secret" anyhow.
-        optionsForLogging.notionToken =
-            optionsForLogging.notionToken.substring(0, 10) + "...";
+        const optionsForLogging = getOptionsForLogging(options);
         const config = yield (0, configuration_1.loadConfigAsync)();
         (0, log_1.verbose)(`Options:${JSON.stringify(optionsForLogging, null, 2)}`);
         yield (0, images_1.initImageHandling)(options.imgPrefixInMarkdown || options.imgOutputPath || "", options.imgOutputPath || "", options.locales);

package/dist/run.js

@@ -73,13 +73,15 @@ function run() {
             .option("-i, --img-output-path  <string>", "Path to directory where images will be stored. If this is not included, images will be placed in the same directory as the document that uses them, which then allows for localization of screenshots.")
             .option("-p, --img-prefix-in-markdown <string>", "When referencing an image from markdown, prefix with this path instead of the full img-output-path. Should be used only in conjunction with --img-output-path.")
             .option("--require-slugs", "If set, docu-notion will fail if any pages it would otherwise publish are missing a slug in Notion.", false)
+            .option("--docusaurus-v2", "Emit Docusaurus v2-compatible markdown. By default docu-notion emits Docusaurus v3-compatible output.", false)
             .addOption(new commander_1.Option("--image-file-name-format <format>", "format:\n- default: {page slug (if any)}.{image block ID}\n- content-hash: Use a hash of the image content.\n- legacy: Use the legacy (before v0.16) method of determining file names. Set this to maintain backward compatibility.\nAll formats will use the original file extension.")
             .choices(["default", "content-hash", "legacy"])
             .default("default"));
         commander_1.program.showHelpAfterError();
         commander_1.program.parse();
-        (0, log_1.setLogLevel)(commander_1.program.opts().logLevel);
-        console.log(JSON.stringify(commander_1.program.opts()));
+        const parsedOptions = commander_1.program.opts();
+        (0, log_1.setLogLevel)(parsedOptions.logLevel);
+        console.log(JSON.stringify((0, pull_1.getOptionsForLogging)(parsedOptions)));
         // copy in the this version of the css needed to make columns (and maybe other things?) work
         let pathToCss = "";
         try {
@@ -90,10 +92,10 @@ function run() {
             pathToCss = "./src/css/docu-notion-styles.css";
         }
         // make any missing parts of the path exist
-        fs.ensureDirSync(commander_1.program.opts().cssOutputDirectory);
-        fs.copyFileSync(pathToCss, path_1.default.join(commander_1.program.opts().cssOutputDirectory, "docu-notion-styles.css"));
+        fs.ensureDirSync(parsedOptions.cssOutputDirectory);
+        fs.copyFileSync(pathToCss, path_1.default.join(parsedOptions.cssOutputDirectory, "docu-notion-styles.css"));
         // pull and convert
-        yield (0, pull_1.notionPull)(commander_1.program.opts()).then(() => console.log("docu-notion Finished."));
+        yield (0, pull_1.notionPull)(parsedOptions).then(() => console.log("docu-notion Finished."));
     });
 }
 function parseLocales(value) {

package/dist/transform.js

@@ -45,6 +45,13 @@ function getMarkdownFromNotionBlocks(context, config, blocks) {
         //console.log("markdown after link fixes", markdown);
         // simple regex-based tweaks. These are usually related to docusaurus
         const body = yield doTransformsOnMarkdown(context, config, markdown);
+        const h1Headings = getMarkdownH1Headings(body);
+        if (h1Headings.length > 1) {
+            const pageLabel = context.pageInfo.slug || "(unknown page)";
+            (0, log_1.warning)(`[docu-notion] Generated page "${pageLabel}" contains ${h1Headings.length} H1 headings. Docusaurus pages should have at most one H1. H1 headings: ${h1Headings
+                .map(heading => `"${heading}"`)
+                .join(", ")}.`);
+        }
         // console.log("markdown after regex fixes", markdown);
         // console.log("body after regex", body);
         const uniqueImports = [...new Set(context.imports)];
@@ -53,6 +60,30 @@ function getMarkdownFromNotionBlocks(context, config, blocks) {
         return `${imports}\n${body}`;
     });
 }
+function getMarkdownH1Headings(body) {
+    const headings = [];
+    let activeFenceMarker;
+    for (const line of body.split(/\r?\n/)) {
+        const trimmedLine = line.trimStart();
+        if (trimmedLine.startsWith("```")) {
+            activeFenceMarker = activeFenceMarker === "```" ? undefined : "```";
+            continue;
+        }
+        if (trimmedLine.startsWith("~~~")) {
+            activeFenceMarker = activeFenceMarker === "~~~" ? undefined : "~~~";
+            continue;
+        }
+        if (activeFenceMarker || !/^#\s+/.test(line)) {
+            continue;
+        }
+        headings.push(line
+            .replace(/^#\s+/, "")
+            .replace(/\s+\{\/\*\s*#.*?\*\/\}\s*$/, "")
+            .replace(/\s+\{#.*?\}\s*$/, "")
+            .trim());
+    }
+    return headings;
+}
 // operations on notion blocks before they are converted to markdown
 function doNotionBlockTransforms(blocks, config) {
     for (const block of blocks) {

package/package.json

@@ -90,5 +90,5 @@
   "volta": {
     "node": "22.21.0"
   },
-  "version": "0.17.0-alpha.4"
+  "version": "1.0.0-alpha.2"
 }