この記事はNotionで書かれています
⇒ https://malvageee.notion.site/Notion-Qiita-Markdown-1af2ad69d3ce80b189a5c816f8c1eccd

はじめに

こんにちは、はじめまして。まるべいじと申します！
今回は、私が開発しているNotionをMarkdownに変換するライブラリが新たにQiitaにも対応したのでご紹介します。先日、このプロジェクトがサイボウズ社の社内勉強会で紹介されたと知り、開発の励みになっています。

このライブラリは「技術記事を書きたいけれど、書き始めるまでのハードルが高い」と感じているエンジニアの皆さんを支援するために開発しました。
インストールや設定が面倒だと感じる方も、デモサイトもありますので、ぜひ気軽に試してみてください！

最後まで読んでいただけると幸いです。

📢 notion-md-converter

📌 デモサイト（詳しい使い方はこちら）

こちらの初回公開からの大型アップデートです

記事を書くハードル高い

皆さんは技術記事でアウトプットしていますか？
「書きたいけど、なかなか手が出ない...」という方、多いのではないでしょうか。自分も技術記事の執筆の心理的ハードルが高いと感じる一人です。

なぜ記事を書き始められないのか、その理由を考えると、実は執筆環境が大きな壁になっていることに気づきました。
自分が特に重要だと感じるのは次の2点です：

どこでも気軽に書き始められること
書き心地の良さ

一文字書くまでのステップが多いほど、継続的なアウトプットは難しくなると思っています。

どこでも始められる執筆環境の重要性

技術記事を書こうと思いながら、実際には書けずに終わってしまう経験は誰にでもあるのではないでしょうか。自分自身、こんなパターンで何度も挫折してきました：

外出中に
「この技術について記事を書きたいな。でも今はパソコンがないし、スマホでメモするのも後で清書するのが面倒だから…帰ってから書こう！」
帰宅後
「ゲーム楽しい！！！！！！」
寝る直前
「あ、記事書くの忘れてた…まぁ、明日気が向いたら書こう」
翌日
「ゲーム楽しい！！！！！！」

こうした日々が続くと、アイデアが浮かんでも「どうせ書かないだろう」と諦めるクセがついてしまいます。だからこそ、思いついたその瞬間に、どこでも書き始められる環境が重要です。

最近の技術ブログプラットフォームはGitHubと連携できるようになり、好みのエディターでAIの助けを借りながら執筆できるようになりました。これは素晴らしい進化ですが、「自分のPC環境が必要」という制約があります。

書き心地のよさがもたらすクリエイティビティ

文章を書く際、道具や環境の「書き心地」は思いのほか重要な要素です。例えるなら、滑らかに書けるペンと引っかかるボールペンの違いのようなもの。技術記事の執筆においても同じことが言えます。

使いづらいエディタや複雑な構文に悩まされると、本来伝えたかった技術的な内容よりも「書き方」に意識が奪われてしまいます。そのストレスが積み重なると、次第に「書くこと自体」が苦痛になってしまうのです。

自分が理想とする書き心地とは：

思考の流れを止めない: 技術的なアイデアが湧いてきた時、それを表現するための手段で躓かないこと
整形よりも内容に集中: マークダウンやHTMLタグなど、装飾の構文を意識せずに書けること
後で編集しやすい: 書いた内容を見直し、構造を変えたくなった時に柔軟に対応できること

Notionのようなモダンなエディタが人気を集めているのは、まさにこの「書き心地のよさ」を実現しているからではないでしょうか。リッチなインターフェースでありながら、シンプルに使え、見た目も美しい。そんな環境で書いた内容を、そのままQiitaなどの技術ブログに変換できれば、技術的な思考と執筆の間の障壁が取り除かれると思っています。

最高のエディタ。Notionで全ての記事を書きたい。

私はNotionを日常的に愛用しています。仕事でもプライベートでも、その使いやすさに助けられる場面が数多くあります。

Notionの魅力は何といっても執筆体験の良さ。PC、スマホ、どの端末で開いても直感的に文章が書けます。見出しの追加や書式変更もシンプルな操作で完結し、データはクラウドで自動的に同期されるため、場所やデバイスに縛られることなく思考を形にできます。

しかし、このNotionで書いた内容を技術記事として公開しようとすると、一つの大きな壁にぶつかります。それが技術ブログプラットフォームとの互換性の問題です。

例えば、このようなブロックをコピーして

テキストを貼り付けると、このような形に変わってしまいます。

<aside>

コールアウト

</aside>

プラットフォームによってコールアウト形式の文法が異なるので、単純にコピーしたMarkdownでプレビューすると、そのままのテキストや思ってたものと違うものが表示されるケースが発生します。

コールアウトを正しく変換しようとしたら、このようにサイトごとに合わせた形式にする必要があります。

NotionからQiita Markdownへの変換ライブラリの紹介

色々長く説明しまってましたが、この問題を解決するのがこのライブラリです！
何回もの設計の見直しをして、シンプルなインターフェースで柔軟に簡単なコードで拡張できるようにしてきました。

提供するメイン機能は1つ。
Notionをあなたの求めるMarkdownに変換します。

シンプルなMarkdown形式でも、Qiita形式でも、Zenn形式でも。
（今後ははてなブログでも使えるようにする予定）

ライブラリの使い方

今回は、qiita向けの変換のみに特化して説明します。
coreの使い方やカスタマイズ、テストの書き方については、ライブラリのREADMEから確認してください。

Step0: Notionの情報を取得する

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

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

内部統合は、選択したワークスペースに関連付けられます。統合を作成するには、ワークスペースの所有者である必要があります。

まずはサイドバーから設定を開きます
コネクト > インテグレーションの作成または管理を選択
新しいインテグレーションを選択
フォームを入力
1. インテグレーション名：任意
2. 種類：内部
3. ロゴ：未設定でOK
トークンをコピー
1. 表示 > コピーを押す
権限は読み取りだけあればOKなので、気になるようであれば更新と挿入はチェックをはずしてOKです

NotionのページIDを取得する

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

Step1: ライブラリをインストール

npmの初期設定

$ mkdir article-export
$ cd article-export
$ npm init

必要な依存を追加

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

Step2: 出力部分を実装する

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

main.js

import { $getPageFullContent } from "@notion-md-converter/core";
import { NotionQiitaMarkdownConverter } from "@notion-md-converter/qiita";
import { Client } from "@notionhq/client";

const client = new Client({
  auth: "API_KEY",
});

// fetch Notion Page Blocks
const pageId = "some-page-id";
const content = await $getPageFullContent(client, pageId);

// convert to markdwon
const executor = new NotionQiitaMarkdownConverter();
const result = executor.execute(content);

Step3: 実行！！

$ node main.js

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

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

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

ライブラリでは、キャプションの先頭から最初の:までの部分をメタデータとして扱うCaption Metadaと呼んでいる機能があります。
これにより、各プラットフォームの細かな機能の差分を吸収してます。

コードブロックのdiff表示

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

👇こんな感じ

sample.ts

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

メッセージのalert表示

Notionのコールアウトブロックの背景色か文字色をredかyellowにすることでnoteの設定を変えられます。

red： alert
yellow：warn
それ以外：info

👇こんな感じ

これはinfoのメッセージ

これはwarnのメッセージ

これはalertのメッセージ

画像の添付

Qiita特有ではないですが、現在のライブラリだとNotionの画像をホスティングできる場所にアップロードする機能を提供してないので、Notionに画像添付したものは画像有効期限の1時間後に見れなくなってしまいます。
なので、ライブラリのFileAdapter機能を使って、画像のホスティング先を変えるなどカスタマイズすることで、Notionにアップロードした画像の埋め込みも柔軟に行えます。
（Gyazoにアップロードして、そのURLをNotionにはると上記の設定不要なのでおすすめ）

以上がライブラリの使い方です！

My執筆フロー

このような感じで執筆してます。

外出中の隙間時間で大枠の執筆
- スマホで書けるので思い立ったときにすぐできる
PCで全体を整える
- スマホでは表現しにくいところはPCを使って、文章を整えたりするのにAI使って調整します
デモサイトでMarkdownに変換する
- いちいちプログラム実行する必要がないので、デモサイトと言いつつ個人的には変換サービスのようにたくさん使ってます
ZennやQiitaにMarkdownをそのまま貼り付け
- 貼り付けたらそのMarkdownのまま使えるので、プレビュー見ておかしいところないか確認するだけ
投稿！！

🎉 感謝 🎉

OSSの初公開から現在に色々な反応いただきありがとうございます！改善していく励みになってます。

ダウンロードして使ってくれた方
デモサイトを使ってくれた方
記事にいいねをくれた方
GitHubにstarをくれた方
issueを上げてくれた方
PullRequestを上げてくれた方
ツイートやはてブをくれた方

さいごに

現在は使いやすさの向上と対応プラットフォームの追加をしています。今後はさらに改善するので、ぜひ使ってみてください。

良いなと思ったら、GitHub starやいいねお願いします！issueやPRも待ってます！