Notion-to-mdast NPM

notion-to-mdast

Notion's markdown export is buggy and lacks support for many features. This library aims to provide customizable alternative by using the official API to translate pages into a syntax tree, which can then be used to generate markdown or other formats.

An integration must be created to use this library. You must also find the id of the target page, the script search can be used to find it.

Usage

We must utilize ToMdast to convert the notion page to a syntax tree, and then compile it using the unified ecosystem.

The following code is a snippet of the translate script.

const client = new Client({
    auth: process.env.NOTION_API_KEY,
});

const toMdast = new ToMdast(client)
const root = await toMdast.translatePage(process.env.PAGE_ID!) as Root

const content = unified()
    .use(remarkStringify, { emphasis: "_" })
    .use(remarkMath)
    .use(remarkGfm)
    .use(remarkDirective)
    .use(remarkFrontmatter)
    .stringify(root)

console.log(content)

API

`new ToMdast(client: Client, options?: ToMdastOptions)`

Creates a new ToMdast instance. options is used to customize the output

`ToMdast#translatePage(pageId: string): Promise<Root>`

Translates a page into a syntax tree

`Options`

Customize the output of the syntax tree

export type Options = {
    blockHandles?: Partial<BlockHandles>
    richTextHandles?: Partial<RichTextHandles>
    propertyHandles?: Partial<PropertyHandles>
}

export type BlockHandle = (this: ToMdast, response: BlockObjectResponse) => Promise<Node | Node[]>
export type BlockHandles = Record<BlockObjectResponse['type'], BlockHandle>

export type RichTextHandle = (this: ToMdast, response: RichTextItemResponse) => Promise<Node>
export type RichTextHandles = Record<RichTextItemResponse['type'], RichTextHandle>

export type PropertyResponse = PageObjectResponse['properties'][keyof PageObjectResponse['properties']]
export type PropertyHandle = (this: ToMdast, response: PropertyResponse) => Promise<string>
export type PropertyHandles = Record<PropertyResponse['type'], PropertyHandle>

A handle is a function that takes in a response and returns a node or an array of nodes. The this context is the ToMdast instance. With Options the handles for each block type and rich text type can be customized. See handles for the default handles.

The metadata of the page is obtained from the page properties, and can also be customized with handles.

Roadmap

Paragraph
Mention
Headings
Code
Quote
Equation
Table
Callout (with ofm)
Toggle blocks (as list item)
Numbered list item
Bulleted list item
To do (with gfm)
Divider
Image
Video
PDF
File
Embed
Bookmark
Link Preview
Synced block (as container)
Column list and column (as container)
Child page (as link)
Metadata