💡 For better readability and detailed instructions headover to the wiki

Notion to Markdown

Convert notion pages, block and list of blocks to markdown (supports nesting) using notion-sdk-js

Note: Before getting started, create an integration and find the token.

Todo

• heading
• images
• quotes
• links
• bullets
• todo
• inline code
• code block
• strikethrough, underline, bold, italic
• nested blocks
• embeds, bookmarks, videos, files (converted to links)
• Simple tables
• toggle
• divider
• equation block (converted to code blocks)
• convert returned markdown object to string (toMarkdownString())
• typescript support
• add tests

Install

1$ npm install notion-to-md

Usage

Note: Details on methods can be found in API section

converting markdown objects to markdown string

This is how the notion page looks for this example:

1const { Client } = require("@notionhq/client");
2const { NotionToMarkdown } = require("notion-to-md");
3// or
4// import {NotionToMarkdown} from "notion-to-md";
5
6const notion = new Client({
7  auth: "your integration token",
8});
9
10// passing notion client to the option
11const n2m = new NotionToMarkdown({ notionClient: notion });
12
13(async () => {
14  const mdblocks = await n2m.pageToMarkdown("target_page_id");
15  const mdString = n2m.toMarkdownString(mdblocks);
16
17  //writing to file
18  fs.writeFile("test.md", mdString, (err) => {
19    console.log(err);
20  });
21})();

Output:

converting page to markdown object

Example notion page:

1const { Client } = require("@notionhq/client");
2const { NotionToMarkdown } = require("notion-to-md");
3
4const notion = new Client({
5  auth: "your integration token",
6});
7
8// passing notion client to the option
9const n2m = new NotionToMarkdown({ notionClient: notion });
10
11(async () => {
12  // notice second argument, totalPage.
13  const x = await n2m.pageToMarkdown("target_page_id", 2);
14  console.log(x);
15})();

Output:

1[
2  {
3    "parent": "# heading 1",
4    "children": []
5  },
6  {
7    "parent": "- bullet 1",
8    "children": [
9      {
10        "parent": "- bullet 1.1",
11        "children": []
12      },
13      {
14        "parent": "- bullet 1.2",
15        "children": []
16      }
17    ]
18  },
19  {
20    "parent": "- bullet 2",
21    "children": []
22  },
23  {
24    "parent": "- [ ] check box 1",
25    "children": [
26      {
27        "parent": "- [x] check box 1.2",
28        "children": []
29      },
30      {
31        "parent": "- [ ] check box 1.3",
32        "children": []
33      }
34    ]
35  },
36  {
37    "parent": "- [ ] checkbox 2",
38    "children": []
39  }
40]

converting list of blocks to markdown object

same notion page as before

1const { Client } = require("@notionhq/client");
2const { NotionToMarkdown } = require("notion-to-md");
3
4const notion = new Client({
5  auth: "your integration token",
6});
7
8// passing notion client to the option
9const n2m = new NotionToMarkdown({ notionClient: notion });
10
11(async () => {
12  // get all blocks in the page
13  const { results } = await notion.blocks.children.list({
14    block_id,
15  });
16
17  //convert to markdown
18  const x = await n2m.blocksToMarkdown(results);
19  console.log(x);
20})();

Output: same as before

Converting a single block to markdown string

• only takes a single notion block and returns corresponding markdown string
• nesting is ignored
• depends on @notionhq/client

1const { NotionToMarkdown } = require("notion-to-md");
2
3// passing notion client to the option
4const n2m = new NotionToMarkdown({ notionClient: notion });
5
6const result = n2m.blockToMarkdown(block);
7console.log(result);

result:

![image](https://media.giphy.com/media/Ju7l5y9osyymQ/giphy.gif)

Custom Transformers

You can define your own custom transformer for a notion type, to parse and return your own string. setCustomTransformer(type, func) will overload the parsing for the giving type.

1const { NotionToMarkdown } = require("notion-to-md");
2const n2m = new NotionToMarkdown({ notionClient: notion });
3n2m.setCustomTransformer('embed', async (block) => {
4  const {embed} = block as any;
5  if (!embed?.url) return '';
6  return `<figure>
7  <iframe src="${embed?.url}"></iframe>
8  <figcaption>${await n2m.blockToMarkdown(embed?.caption)}</figcaption>
9</figure>`;
10});
11const result = n2m.blockToMarkdown(block);
12// Result will now parse the `embed` type with your custom function. 

Note Be aware that setCustomTransformer will take only the last function for the given type. You can't set two different transforms for the same type.

Contribution

Pull requests are welcome. For major changes, please open an issue first to discuss what you would like to change. Please make sure to update tests as appropriate.

Contributers

License

MIT