notion-x-to-md

Converts a Notion page to Markdown. Very useful for LLMs.

Features

• ✅ use notion content with LLMs
• ✅ renders all notion blocks including collections
• ✅ renders embedded tweets as markdown
• ✅ works without an API key
• ✅ unit tests
• ✅ free

Install

npm install notion-x-to-md

Usage

import { NotionAPI } from 'notion-client'
import { notionPageToMarkdown } from 'notion-x-to-md'

const api = new NotionAPI()

// fetch a notion page's content
const page = await api.getPage('067dd719a912471ea9a3ac10710e7fdf')

// convert the page to a markdown string
const markdown = await notionPageToMarkdown(page)

console.log(markdown)

CLI

npx -y notion-x-to-md https://notion.so/067dd719a912471ea9a3ac10710e7fdf

npx -y notion-x-to-md de14421f13914ac7b528fa2e31eb1455

Usage: notion-x-to-md [options] <page>

Converts a Notion page to Markdown

Arguments:
  page        Notion page ID or URL (must be publicly accessible)

Options:
  -h, --help  display help for command

Examples

| Notion Page | Page ID | Markdown Output | Supported? | Notes | | ---------------------------- | -------------------------------------------------------------------------------------- | ---------------------------------------------------- | ---------- | ------------------------------------------------------------------------------------------------------------------------------------ | | Notion Kit Test Suite | 067dd719a912471ea9a3ac10710e7fdf | md | ✅ | index / overview | | Basic Blocks | 0be6efce9daf42688f65c76b89f8eb27 | md | ✅ | | | Lists | de14421f13914ac7b528fa2e31eb1455 | md | ✅ | | | Bookmarks | c1c8f540c06f4ac89f831e4a9cc402ae | md | ✅ | just rendered as links (no images) | | Checklists | 38fa73d49b8f40aab1f3f8c82332e518 | md | ✅ | | | Toggles | 5995506f2c564d81956aa38711e12337 | md | ✅ | | | Links | 52353862df0f48ba85648db7d0acd1dd | md | ✅ | | | Image Gallery | 3492bd6dbaf44fe7a5cac62c5d402f06 | md | ✅ | | | Image Upload | 912379b0c54440a286619f76446cd753 | md | ✅ | | | Math Equations | 7820b2d5300747b38e31344eb06fbd57 | md | ✅ | | | Sync Blocks | 8bcd65801a5d450fb7218d8890a38c29 | md | ✅ | | | Code Blocks | 0c322c33381c49bca5083a451c334c39 | md | ✅ | | | Simple Table | 9d9814f3220a4b3bbc2481ad6fd7c913 | md | ✅ | | | Collection Number Formatting | 17aef37fb4624588ab1ff0e6671acba5 | md | ✅ | | | Collections | 2fea615a97a7401c81be486e4eec2e94 | md | ☑️ | all collection views rendered as markdown tables | | Buttons | 30bedb27f12481cc9d6afe0976b52e60 | md | ☑️ | button labels/actions not rendered | | Tweet Embeds | 7b7f063709034186adbfb46f455d5065 | md | ☑️ | uses tweet-to-md; polls not shown; gif and video tweets show poster image only | | Embeds | 5d4e290ca4604d8fb809af806a6c1749 | md | ☑️ | videos shown as link; iframe embeds (Maps, Figma, Drive) render empty |

Notes

• You don't need to create any Notion API keys or integrations; just make sure your Notion page is publicly accessible.
• Resulting image URLs hosted by Notion will work for a short while before becoming inaccessible. This is the same thing that happens with the official Notion app.
  • If you want permanent image URLs, you can post-process the ExtendedRecordMap returned by NotionAPI.getPage to upload the temporary images to a permanent URL, while storing a mapping of block IDs to permanent URLs.
• Collections (databases) are supported, including lots of nuanced features like proper number/date/expression/formula formatting, though all database views will be rendered as markdown tables.
• Why's it called notion-x-to-md? Because notion-to-md was already taken, but this version is based on react-notion-x which has a long history of stable maintenance.
• It outputs Github-Flavored Markdown (GFM) which is well-supported by LLMs.

License

MIT © Travis Fischer

Support my OSS work by following me on X