@notion-md-converter/core

NotionページをMarkdownに変換するためのコアパッケージです。

🚀 インストール

npmでインストール

# JavaScriptの場合
npm install @notion-md-converter/core

# TypeScriptの場合
npm install @notion-md-converter/core @notion-md-converter/types

📖 使い方

APIキーを取得するには、NotionのGetting Started Guideに従ってください。

基本的な例

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

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

const pageId = "some-page-id";
// このライブラリのNotion APIヘルパー
// Notion Blockの子要素を再帰的に取得
const content = await $getPageFullContent(client, pageId);

// Markdownに変換
const executor = new NotionMarkdownConverter();
const result = executor.execute(content);

Markdown出力のカスタマイズ

見出しブロックの変換を変更したい場合の例です。例えば、Markdown見出しの#の数を1つ増やすカスタムトランスフォーマーを定義します。

import { createHeadingTransformerFactory, MarkdownUtils } from "@notion-md-converter/core";

export const createMarkdownCustomHeadingTransformer = () => {
    // トランスフォーマーを作成する関数を使用
  return createHeadingTransformerFactory(({ level, richText }) => {
    const text = MarkdownUtils.convertRichTextsToMarkdown(richText);
    return MarkdownUtils.wrapWithNewLines(MarkdownUtils.heading(text, level + 1)); // レベルを1追加
  });
};

トランスフォーマーのテストを簡単に書けるよう、@notion-md-converter/testingライブラリを提供しています。このライブラリを使用すると、Notionブロックオブジェクトを簡単に作成し、変換結果をテストできます。

$ npm install @notion-md-converter/testing

import {
  createTransformerContext,
  createHeading1Block,
  createTextRichText,
  dedent,
} from "@notion-md-converter/testing";
import { createMarkdownCustomHeadingTransformer } from "./createMarkdownCustomHeadingTransformer";

describe("createMarkdownCustomHeadingTransformer", () => {
  const transformer = createMarkdownCustomHeadingTransformer();

  it("heading_1ブロックを変換できる", () => {
    const block = createHeading1Block({
      richText: [
        createTextRichText({
          content: "Hello",
        }),
      ],
    });
    const context = createTransformerContext({
      blocks: [block],
    });

    const result = transformer(context);
    expect(result).toBe(dedent({ wrap: true })`
      ## Hello
    `);
  });
});

作成したトランスフォーマーをコンバーターのオプションで定義します。

const executor = new NotionMarkdownConverter({
  heading: createMarkdownCustomHeadingTransformer(),
});
const result = executor.execute(content);

キャプションメタデータ

画像、コードブロック、埋め込みなどのブロックでキャプションにメタデータを設定できます。メタデータはkey=value形式で指定し、キャプションの先頭から最初の:までがメタデータとして扱われます。

基本的な使い方

width=500:これは画像の説明です

この場合：

width=500 がメタデータ
これは画像の説明です が実際のキャプション

複数のメタデータ

複数のメタデータは&で区切って指定できます：

width=500&height=300:これは画像の説明です

この場合：

width=500 と height=300 がメタデータ
これは画像の説明です が実際のキャプション

使用例

画像幅の指定： width=500:画像の説明
コードブロックのdiff設定： diff=true:filename.js

ライセンス

MITライセンスの下で配布されています。詳細はLICENSEをご覧ください。

作者

malvageee (https://github.com/salvage0707)