notion-to-md

Install the package using npm to start converting Notion pages to Markdown.

npm install notion-to-md

You can control how child pages are handled via the config object passed to the NotionToMarkdown constructor.

• separateChildPage: If set to true, toMarkdownString returns an object where the main content is in the parent property and child page contents are included as separate properties in the same object. (Default: false)
• parseChildPages: If set to false, child pages will not be parsed. (Default: true)

To use the library, instantiate the NotionToMarkdown class by passing a NotionToMarkdownOptions object. You must provide an instance of the @notionhq/client Client.

Available configuration options in config:

• separateChildPage (boolean, default: false): If true, child pages are returned as separate entries in the resulting Markdown object. If false, the child page title is rendered as a heading within the parent's content.
• convertImagesToBase64 (boolean, default: false): Whether to convert images to Base64 strings.
• parseChildPages (boolean, default: true): Whether to parse the content of child pages.

To convert a full Notion page to a Markdown string, use pageToMarkdown to fetch the blocks and then toMarkdownString to convert those blocks into a string.

Note: Since v2.7.0, toMarkdownString returns an object containing the markdown content of child pages rather than just a single string. Use the .parent property to access the main page content.

const { Client } = require("@notionhq/client");
const { NotionToMarkdown } = require("notion-to-md");

const notion = new Client({
  auth: "your integration token",
});

const n2m = new NotionToMarkdown({ notionClient: notion });

(async () => {
  const mdblocks = await n2m.pageToMarkdown("target_page_id");
  const mdString = n2m.toMarkdownString(mdblocks);
  console.log(mdString.parent);
})();

Use pageToMarkdown to convert a Notion page into a structured Markdown object (a list of blocks with nesting). The second argument allows you to specify the depth or a limit (e.g., 2).

const { Client } = require("@notionhq/client");
const { NotionToMarkdown } = require("notion-to-md");

const notion = new Client({
  auth: "your integration token",
});

const n2m = new NotionToMarkdown({ notionClient: notion });

(async () => {
  // The second argument specifies depth/limit
  const x = await n2m.pageToMarkdown("target_page_id", 2);
  console.log(x);
})();

Use blockToMarkdown to convert a single Notion block into its corresponding Markdown string. Note that nesting is ignored when using this method.

const { NotionToMarkdown } = require("notion-to-md");

const n2m = new NotionToMarkdown({ notionClient: notion });

const result = n2m.blockToMarkdown(block);
console.log(result);

If you already have a list of blocks (for example, retrieved via notion.blocks.children.list), you can convert them directly using blocksToMarkdown.

const { Client } = require("@notionhq/client");
const { NotionToMarkdown } = require("notion-to-md");

const notion = new Client({
  auth: "your integration token",
});

const n2m = new NotionToMarkdown({ notionClient: notion });

(async () => {
  const { results } = await notion.blocks.children.list({
    block_id,
  });

  const x = await n2m.blocksToMarkdown(results);
  console.log(x);
})();

The ConfigurationOptions object allows you to fine-tune how Notion blocks are converted to Markdown:

• separateChildPage (boolean, optional): If true, child pages are handled as separate entities.
• convertImagesToBase64 (boolean, optional): If true, images are converted to Base64 strings.
• parseChildPages (boolean, optional): If true, the converter will attempt to parse the content of child pages.

export type ConfigurationOptions = {
  separateChildPage?: boolean;
  convertImagesToBase64?: boolean;
  parseChildPages?: boolean;
};

Once you have an array of MdBlock objects (e.g., from pageToMarkdown), use toMarkdownString(mdBlocks, pageIdentifier?, nestingLevel?) to convert them into a human-readable Markdown string.

• mdBlocks: The array of MdBlock objects to convert.
• pageIdentifier: (Optional) A key used in the returned MdStringObject to identify the content of a specific page. Defaults to "parent".
• nestingLevel: (Optional) Defines the maximum depth of nesting for indentation. Defaults to 0.

The method returns an MdStringObject, which is a mapping of page identifiers to their respective Markdown strings. If separateChildPage was enabled in the configuration, this object will contain entries for the parent and all child pages.