Notionの本文をMarkdownに変換するライブラリの現状

Notion API から取得した本文を Markdown に変換したい。少しでも楽をしたい。

という目的のもと、2022年1月現在どのような手段があるのかを調査しました。Markdown フォーマットに変換したいニーズはそれなりにあると思いますので、調査の一助になればと思います。

この記事では最終的に Typescript および notion-to-md パッケージを採用しています。

そもそも何の言語にするのか問題

決定だは「Notionが公式で提供しているライブラリが JavaScript しかない（2022/01現在）ということでした。しかも、Notion APIはまだベータ提供です。

Getting started - https://developers.notion.com/docs

今後どのような変更が入るかわからない状況なので、サードパーティのライブラリを用いてスピード感を落とすリスクを受け入れるよりも、オフィシャルサポートしているライブラリのほうが現時点は良いと考えました。

よって、 Javascript あるいは Typescript が選択肢になります。

notion-to-md (”Notion to Markdown” npm package)

notoin-to-md は、Notion API から取得したブロック（Blocks）から Markdown 書式を生成してくれます。見ての通り、幅広いブロック書式に対応しており大変便利です。

souvikinator/notion-to-md - https://github.com/souvikinator/notion-to-md

2022/01/27時点レポジトリ説明を引用

heading

images

quotes

links

bullets

todo

inline code

code block

strikethrough, underline, bold, italic

nested blocks

pages inside pages/child page

embeds, bookmarks, videos, files (converted to links)

Simple tables

divider

equation block (converted to code blocks)

convert returned markdown object to string (toMarkdownString())

typescript support

add tests

Simple Table へも対応済み

しかも、めちゃくちゃタイミングのいいことに、 2022/1/25 に “Simple Talbe” 書式も対応してくれました。Simple Table は、簡単な表ですね。現時点だと、まだこの書式への対応が実現できていないライブラリも多い状況です。

Notion で表を作るときには従来から「データベース」形式がありましたが、ちょっとした簡単な表を作るには大げさすぎる仕組みでした。それに対して、2021年の11月に新たに提供されたのが Simple Table 書式です。

SIMPLE TABLES are here! Type /table to get started 🏓 pic.twitter.com/YMPuR51LKn
— Notion (@NotionHQ) November 16, 2021

notion-to-md の実装イメージ

使い方はシンプルです。

（１）と（２）で示すとおり、全ブロックをループする実装が複数箇所あるので、膨大な記事を対象にした場合はもしかするとパフォーマンスが気になるかもしれません。

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

// blocks: Notion API から取得した Block を入れておく

// blocks（この時点では Notion API が返す複雑な構造）を
// notion-to-md が全ブロックを走査して Markdown 書式に変換し配列を作る　・・・（１）
const mdblocks: MdBlock[] = await n2m.blocksToMarkdown(blocks);

// （１）で作った Markdown 化された配列に対して、全て走査して1つのテキストに結合する・・・（２）
const mdString = n2m.toMarkdownString(mdblocks);

return mdString;

その他言語

Python

notion2md - 336 stars - https://github.com/echo724/notion2md

比較的更新は盛んに見えますが、まだ ToDo での未実装が多そうです。近々の実装に期待でしょうか。

（参考）Markdown を Notion API形式に変換するライブラリ

全く逆のアプローチですが、調査の過程で見つけたのでメモしておきます。

https://github.com/instantish/martian

このレポジトリの組織は Fabric という Slack と連携した課題管理サービスを提供しているようですね。のようですね。Slack でやりとりした課題を Notion にポストするために使うのでしょうか？（想像です）

使い方の一例になりそうですね。

Notion API を初めて触った時はとても複雑で面倒くさい気持ちになりました😁

この設計思想に至った理由について公式ブログで言及されていますが、Markdown だけでは Notion の複雑なページ情報を表現しきれないことが主な理由のようですね。とはいえ、Notionアプリでページ全体をコピーして貼り付けるだけでかなり完成度の高い Markdown 書式が出来上がるので、せめてそれだけでもいいからAPIから取得させてほしいのが本音ではあります。

APIでページコンテンツを表現する方法を決定したとき、2つの主要な候補がありました。

忠実度が低く、移植性が高い ： Markdownは、人間が読めるプレーンテキスト形式の一般的な構文です。これは、堅牢な既存のツールを備えた広くサポートされている形式であり、NotionのエディターはすでにMarkdownショートカットとエクスポートをサポートしています。

忠実度が高く、移植性が低い ： Notionブロック値の内部表現に大まかに基づいたカスタムJSON。調整されたスキーマは、ユーザーがこのデータを目的の出力形式に変換する必要があるという犠牲を払って、Notion固有のブロックタイプと形式をキャプチャします。

引用元；Creating the Notion API - https://www.notion.so/blog/creating-the-notion-api (公式ブログ記事, January 20, 2022)