@noticle/core

Core package for converting Notion pages to Markdown.

🚀 Installation

Install via npm

1# if JavaScript
2npm install @noticle/core
3
4# if TypeScript
5npm install @noticle/core @noticle/types

📖 Usage

Follow Notion's Getting Started Guide to obtain an API key.

Basic Example

1import {
2  $getPageFullContent,
3  NotionMarkdownConverter,
4} from "@noticle/core";
5import { Client } from "@notionhq/client";
6
7const client = new Client({
8  auth: API_KEY,
9});
10
11const pageId = "some-page-id";
12// Notion API helpers in this library.
13// Recursively retrieve the Notion Block's child elements
14const content = await $getPageFullContent(client, pageId);
15
16// convert to markdwon
17const executor = new NotionMarkdownConverter();
18const result = executor.execute(content);

[!WARNING] The APIs $getPageFullContent and $getDatabasePages may undergo specification changes in the future as we plan to remove the dependency on @notionhq/client.

Customizing Output Markdown

If you want to change the conversion of a Heading Block. For example, define a custom transformer that increases the number of # in a Markdown heading by one.

1import { createHeadingTransformerFactory, MarkdownUtils } from "@noticle/core";
2
3export const createMarkdownCustomHeadingTransformer = () => {
4	// Use a function to create a transformer
5  return createHeadingTransformerFactory(({ level, richText }) => {
6    const text = MarkdownUtils.convertRichTextsToMarkdown(richText);
7    return MarkdownUtils.wrapWithNewLines(MarkdownUtils.heading(text, level + 1)); // add 1 level
8  });
9};

To simplify writing tests for transformers, we provide the @noticle/testing library. This library allows you to easily create Notion block objects and test their conversion results.

1$ npm install @noticle/testing

1import {
2  createTransformerContext,
3  createHeading1Block,
4  createTextRichText,
5  dedent,
6} from "@noticle/testing";
7import { createMarkdownCustomHeadingTransformer } from "./createMarkdownCustomHeadingTransformer";
8
9describe("createMarkdownCustomHeadingTransformer", () => {
10  const transformer = createMarkdownCustomHeadingTransformer();
11
12  it("Can convert heading_1 block", () => {
13    const block = createHeading1Block({
14      richText: [
15        createTextRichText({
16          content: "Hello",
17        }),
18      ],
19    });
20    const context = createTransformerContext({
21      blocks: [block],
22    });
23
24    const result = transformer(context);
25    expect(result).toBe(dedent({ wrap: true })`
26      ## Hello
27    `);
28  });
29});

Define the created transformer in the options of the converter.

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

Caption Metadata

You can set metadata for captions in blocks such as images, code blocks, and embeds. Metadata is specified in key=value format, and the portion from the beginning of the caption to the first : is treated as metadata.

Basic Usage

width=500:This is an image description

In this case:

• width=500 is the metadata
• This is an image description is the actual caption

Multiple Metadata

Multiple metadata can be specified by separating them with &:

width=500&height=300:This is an image description

In this case:

• width=500 and height=300 are metadata
• This is an image description is the actual caption

Usage Examples

• Specifying image width: width=500:Image description
• Setting diff for code blocks: diff=true:filename.js

License

Distributed under the MIT License. See LICENSE for more information.

Author

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