⚒️

Zenn記事の執筆を効率化!NotionのMarkdown変換ライブラリをnpm公開

2025/02/18に公開

はじめに

こんにちは。はじめまして!まるべいじ(malvageee)です。

先日、NotionのページをMarkdownに変換するライブラリをOSSとして公開しました。
Zennにも対応しているので、技術記事を書いている方にも便利です。

📢 公開記事:

https://zenn.dev/smartcamp/articles/4b3e05623bf11e

初回リリース時はgit cloneが必要で、導入のハードルが少し高かったのですが、今回はnpmに公開しました!
これにより、より簡単に導入・利用できるようになりました。
この記事では、ライブラリの使い方を詳しく解説します。
すぐにサンプルコードを見たい方は、以下のリポジトリをご覧ください。
すぐに動かしたい場合も、以下のサンプルコードからすぐに試せます。

📌 サンプルコード:

https://github.com/salvage0707/notion-md-converter/tree/main/example

それでは、使い方を見ていきましょう! 🚀

一般的なMarkdownを出力する

Step0: NotionのAPIトークンを取得する

NotionのAPIトークンの取得がまだの場合はこちらを参考に取得してください

取得方法はNotion APIの公式ドキュメントをもとに説明していきます。
今回は、一番簡単なプライベートなIntegrationを作成します。

  1. まずはサイドバーから設定を開きます
    https://i.gyazo.com/e6ec44b55975fd3e2892d8fe1908f1ac.png

  2. コネクト > インテグレーションの作成または管理を選択
    https://i.gyazo.com/029d3342870f3c4099750888fdaed1df.png

  3. 新しいインテグレーションを選択
    https://i.gyazo.com/d74c2678d0e7c38b88daebb6e072c41d.png

  4. フォームを入力

    1. インテグレーション名:任意
    2. 種類:内部
    3. ロゴ:未設定でOK
      https://i.gyazo.com/63a5b3250e373ed1cdbe54db8f9ae456.png
  5. トークンをコピー

    1. 表示 > コピー を押す
      https://i.gyazo.com/f4f4e397da799cdd8f72db4daa7cad78.png

Step1: NotionのページIDを取得する

  1. 出力したいNotionのページを開く
    ※ 出力したいページよりも上の階層であればどこでもOK
  2. ページの右上のアイコンからStep0で作ったIntegrationを接続する
    https://i.gyazo.com/cdc26dc07d50c0736377c403f0da5eef.png
  3. ページのリンクをコピーする
    https://i.gyazo.com/f0fa96ac87ed8d1d4d49a8422727f547.png
  4. リンクからIDを取得
    https://www.notion.so/workspace-name/xxxx-12342ad69d3ce800c98fdc39ab42998b7?pvs=4
    12342ad69d3ce800c98fdc39ab42998b7

Step2: ライブラリの実行環境を作る

参考:https://github.com/salvage0707/notion-md-converter/tree/main/example/core

  1. npmの初期設定

    $ mkdir article-export
    $ cd article-export
    $ npm init
    
  2. 必要な依存を追加

    $ npm install @notion-md-converter/core @notionhq/client
    

Step3: 出力部分を実装する

参考:https://github.com/salvage0707/notion-md-converter/blob/main/example/core/src/simple-export/main.ts

main.js
import { $getPageFullContent, NotionMarkdownConverter } from "@notion-md-converter/core";
import { Client } from "@notionhq/client";

const main = async () => {
  const client = new Client({
    auth: "notion-api-token",
  });

  const pageId = "notoin-page-id"
  const content = await $getPageFullContent(client, );

  const executor = new NotionMarkdownConverter();
  const result = executor.execute(content);
  console.log(result);
};

main();

Step4: 実行!!

$ node main.js

こんな感じでマークダウン変換が行えます!

Zenn形式のMarkdownを出力する

各プラットフォーム毎に拡張できるパッケージを用意しているので(まだZennしかないですが)、そちらをインストールすることですぐに実装できます。

$ npm install @notion-md-converter/zenn
main.js
- import { $getPageFullContent, NotionMarkdownConverter } from "@notion-md-converter/core";
+ import { $getPageFullContent } from "@notion-md-converter/core";
+ import { NotionZennMarkdownConverter } from "@notion-md-converter/zenn";
import { Client } from "@notionhq/client";

const main = async () => {
  const client = new Client({
    auth: "notion-api-token",
  });

  const pageId = "notoin-page-id"
  const content = await $getPageFullContent(client, );

- const executor = new NotionMarkdownConverter();
+ const executor = new NotionZennMarkdownConverter();
  const result = executor.execute(content);
  console.log(result);
};

main();

これであとは実行するだけです!

Zennパッケージ特有のNotion記法

可能な限り、Notionの標準の使い方だけでZennのMarkdown記法を対応できるようにしたかったのですが、一部対応できず、Notionの使い方を工夫することで実現できるようにしています。

コードブロックのdiff表示

Notionのコードブロックのキャプションにdiff: をつけることでdiff表記で出力されます。
(コードの言語設定と両立するためにこの形を取りました)

https://i.gyazo.com/54b29eef3c9b34ae368154c035d641ce.png

👇こんな感じ

sample.ts
- console.log("before");
+ console.log("after");

メッセージのalert表示

Notionのコールアウトブロックの背景色がredか、文字色をredにするとalert付きのメッセージで出力されます
(設定でred以外でもalertにすることもできます)

https://i.gyazo.com/3097c8e868a6dda1de09ce8841b046a9.png

👇こんな感じ

画像の添付

Zenn特有ではないですが、現在のライブラリだとNotionの画像をホスティングできる場所にアップロードする機能を提供してないので、Notionに画像添付したものは画像有効期限の1時間後に見れなくなってしまいます。
なので、Gyazoなどの画像を外部でホスティングできるURLをNotionに貼って出力すると画像も扱えます。

最後に

初のnpm公開でわからないこと多かったですが、より使ってもらいやすい環境ができたんではないかと思っています。

バージョン管理できるようになったので、今後はZennだけでなく色々なプラットフォームに対応して、より機能を充実させられればと思います!

良いなと思ったら、GitHub starやいいねお願いします!

https://github.com/salvage0707/notion-md-converter

SMARTCAMP Engineer Blog

Discussion