https://github.com/kerwanp/notion-render

A Javascript library to transform Notion API RichText object into HTML
https://github.com/kerwanp/notion-render

Last synced: 11 days ago
JSON representation

A Javascript library to transform Notion API RichText object into HTML

• Host: GitHub
• URL: https://github.com/kerwanp/notion-render
• Owner: kerwanp
• License: apache-2.0
• Created: 2023-03-14T13:18:35.000Z (over 1 year ago)
• Default Branch: dev
• Last Pushed: 2023-12-30T22:25:32.000Z (11 months ago)
• Last Synced: 2024-10-27T05:05:09.443Z (21 days ago)
• Language: TypeScript
• Homepage: https://notion-render-docs.vercel.app
• Size: 26.4 MB
• Stars: 97
• Watchers: 4
• Forks: 2
• Open Issues: 7
• Metadata Files:
  • Readme: README.md
  • License: LICENSE

Awesome Lists containing this project

README

        





## Notion Render

### Transform [Notion](https://notion.so) Rich Text into HTML, JSX and more.








[![PRs Welcome](https://img.shields.io/badge/PRs-Are%20welcome-brightgreen.svg?style=flat-square)](https://makeapullrequest.com) [![Commitizen friendly](https://img.shields.io/badge/Commitizen-Friendly-brightgreen.svg?style=flat-square)](http://commitizen.github.io/cz-cli/) [![License](https://img.shields.io/github/license/syneki/notion-cms?label=License&style=flat-square)](LICENCE)

[![@notion-render/client](https://img.shields.io/npm/v/@notion-render/client?label=%40notion-render%2Fclient&style=flat-square)](https://www.npmjs.com/package/@notion-render/client)

[🔨 Install](#🔨-install) • [🚀 Get started](#🚀-get-started) • [⚛ Renderers](#⚛-renderers) • [🎲 Blocks](#🎲-blocks) • [🔧 Extend](#🔧-extend)

[Contribute](#contributing) • [License](#license)



# ⚠ Pre-release

This project is currently in pre-release, you can use it but some features are lacking and core components are still able to change.

Do not hesitate to open an issue to provide your feedback, report bugs and to propose new features.

# 🔨 Install

```shell

$ npm install @notion-render/client

$ yarn add @notion-render/client

```

# 🚀 Get started

```typescript

import { Client } from '@notionhq/notion';

import { NotionRenderer } from '@notion-render/client';

const client = new Client({

  auth: process.env.NOTION_TOKEN,

});

const renderer = new NotionRenderer();

const { results } = await client.blocks.children.list({

  block_id: '',

});

const html = renderer.render(...results);

```

# ⚛ Renderers

| Renderer | Status         |

| -------- | -------------- |

| HTML     | 🔶 In progress |

| Markdown | ❌ Planned     |

# 🎲 Blocks

| Block Type | Supported | Notion client required | Available in | Notes |

| --- | --- | --- | --- | --- |

| Text | ✅ Yes |  | `@notion-render/client` | `` |

| Bookmark | ✅ Yes |  | `@notion-render/client` | Uses `url-metadata` to generate bookmark |

| Breadcrumb | ❌ Missing |  |  | Embedded preview of external URL |

| Bulleted List Item | ✅ Yes |  | `@notion-render/client` | `
` |

| Callout | ✅ Yes |  | `@notion-render/client` | `
` |

| Child database | ❌ Missing |  |  |  |

| Child page | ❌ Missing |  |  |  |

| Code | ✅ Yes |  | `@notion-render/client` | 
 |

| Column List | ✅ Yes | ⚠ Yes | `@notion-render/client` | `
` |

| Column | ✅ Yes | ⚠ Yes | `@notion-render/client` | `
` |

| Divider | ✅ Yes |  | `@notion-render/client` | `
` |

| Embed | ❌ Missing |  |  |  |

| Equations | ❌ Missing |  |  |  |

| Files | ❌ Missing |  |  |  |

| Heading 1 | ✅ Yes |  | `@notion-render/client` | `
` |

| Heading 2 | ✅ Yes |  | `@notion-render/client` | `
` |

| Heading 3 | ✅ Yes |  | `@notion-render/client` | `
` |

| Toggle Heading 1 | ✅ Yes | ⚠ Yes | `@notion-render/client` | `
` Requires Notion client |

| Toggle Heading 2 | ✅ Yes | ⚠ Yes | `@notion-render/client` | `
` Requires Notion client |

| Toggle Heading 3 | ✅ Yes | ⚠ Yes | `@notion-render/client` | `
` Requires Notion client |

| Image | ✅ Yes |  | `@notion-render/client` | `` |

| Link preview | ❌ Missing |  |  |  |

| Mention | ✅ Yes |  | `@notion-render/client` | `` Returns plain text (e.g. @John Doe) |

| Numbered List Item | ✅ Yes |  | `@notion-render/client` | `
` |

| Paragraph | ✅ Yes |  | `@notion-render/client` | `
` |

| PDF | ❌ Missing |  |  |  |

| Quote | ✅ Yes |  | `@notion-render/client` | `

` |

| Synced block | ❌ Missing |  |  |  |

| Table | 🔶 Not fully supported |  | `@notion-render/client` | `` Header row and column not supported |

| Table Row | 🔶 Not fully supported |  | `@notion-render/client` | `` Header row and column not supported |

| Table of contents | ❌ Missing |  |  |  |

| Template | ❌ Deprecated |  |  |  |

| To do | ✅ Yes |  | `@notion-render/client` | `
` |

| Toggle | ✅ Yes | ⚠ Yes | `@notion-render/client` | `` |

| Video | ❌ Missing |  |  |  |


# 🔧 Extend

## Custom renderer

You can create custom renderers to handle custom Notion plugins and override existing blocks.

```typescript

import { NotionRenderer, createBlockRenderer } from '@syneki/notion-render';

const paragraphRenderer = createBlockRenderer(

  'paragraph',

  (data, renderer) => {

    return `
${renderer.render(...data.paragraph.rich_text)}
`;

  }

);


const renderer = new NotionRenderer({

  renderers: [paragraphRenderer],

});

```

# Contributing

I'd love for you to contribute to this project. You can request new features by creating an issue, or submit a pull request with your contribution.

# Licence

Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at

```

http://www.apache.org/licenses/LICENSE-2.0

```

Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.