README.md

Note This repository is automatically generated from the main parser monorepo. Please submit any issues or pull requests there.

rehype-notion

Plugin for rehype to turn HTML into Notion blocks

Contents

• rehype-notion
  • Contents
  • What is this?
  • When should I use this?
  • Install
  • Use
  • API
    • default()
      • Signature
      • Parameters
      • Returns
    • Options
      • Properties
        • hastToMdastOptions?
        • markdownToNotionOptions?
        • mdastToMarkdownOptions?
    • Block
  • Security
  • Related
  • License

What is this?

A compiler plugin for rehype that transforms a [hast][hast] syntax tree into Notion blocks.

When should I use this?

You want to convert HTML to Notion blocks but want control over the conversion process. If you just want to convert HTML to Notion blocks, you should use html-to-notion-blocks instead.

Install

This package is ESM only. In Node.js (version 12.20+, 14.14+, 16.0+, 18.0+), install as

pnpm add rehype-notion
# or with yarn
# yarn add rehype-notion
# or with npm
# npm install rehype-notion

Use

import { unified } from 'unified'
import rehypeParse from 'rehype-parse'
import rehypeNotion from 'rehype-notion'

const html = `
  <h1>Heading</h1>
  <p>Paragraph</p>
`

const notionBlocks = unified().use(rehypeParse).use(rehypeNotion).processSync(html).result

// or with options and async

const vfile = await unified()
  .use(parse)
  .use(
    rehypeNotion,
    //  {
    //    hastToMdastOptions: {...}
    //    mdastToMarkdownOptions: {...}
    //    markdownToNotionOptions: {...}
    //  }
  )
  .process(html).result

const notionBlocks = vfile.result

console.log(notionBlocks)
// [
//   {
//     object: 'block',
//     type: 'heading_1',
//     heading_1: {
//       rich_text: [
//         {
//           annotations: {
//             bold: false,
//             italic: false,
//             strikethrough: false,
//             underline: false,
//             code: false,
//             color: 'default'
//           },
//           text: {
//             content: 'Heading',
//             link: null
//           }
//           type: 'text',
//         }
//       ]
//     }
//   },
//   {
//     object: 'block',
//     type: 'paragraph',
//     paragraph: {
//       rich_text: [
//         {
//           annotations: {
//             bold: false,
//             italic: false,
//             strikethrough: false,
//             underline: false,
//             code: false,
//             color: 'default'
//           },
//           text: {
//             content: 'Paragraph',
//             link: null
//           }
//           type: 'text'
//         }
//       ]
//     }
//   }
// ]

API

---

default()

A plugin is a function. It configures the processor and in turn can receive options. Plugins can configure processors by interacting with parsers and compilers (at this.Parser or this.Compiler) or by specifying how the syntax tree is handled (by returning a Transformer).

Signature

default(this: Processor<void, Root, Root, BlockObjectRequest[]> | Processor<void, Comment, Comment, BlockObjectRequest[]> | Processor<void, DocType, DocType, BlockObjectRequest[]> | Processor<void, Element, Element, BlockObjectRequest[]> | Processor<void, Text, Text, BlockObjectRequest[]>, ...settings: [Options] | [void] | []): void;

Parameters

| Name | Type | Description | | :------------ | :---------------------------------------------------------- | :---------------------------------------------------------------- | ----------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------- | --- | | this | Processor<void, Root, Root, BlockObjectRequest[]> | Processor<void, Comment, Comment, BlockObjectRequest[]> | Processor<void, DocType, DocType, BlockObjectRequest[]> | Processor<void, Element, Element, BlockObjectRequest[]> | Processor<void, Text, Text, BlockObjectRequest[]> | - | | ...settings | [Options] | [void] | [] | Configuration for plugin. Plugins typically receive one options object, but could receive other and more values. Users can also pass a boolean instead of settings: true (to turn a plugin on) or false (to turn a plugin off). When a plugin is turned off, it won’t be called. When creating your own plugins, please accept only a single object! It allows plugins to be reconfigured and it helps users to know that every plugin accepts one options object. |

Returns

void

Plugins can return a Transformer to specify how the syntax tree is handled.

Defined in: node_modules/.pnpm/[email protected]/node_modules/unified/index.d.ts:531

---

Options

Properties

hastToMdastOptions?

Options

Defined in: src/lib/rehype-notion.ts:29

markdownToNotionOptions?

BlocksOptions

Defined in: src/lib/rehype-notion.ts:31

mdastToMarkdownOptions?

MdastToMarkdownOptions

Defined in: src/lib/rehype-notion.ts:30

---

Block

AppendBlockChildrenParameters["children"][number]

Defined in: src/lib/rehype-notion.ts:13

Security

Use of rehypeNotion can open you up to a [cross-site scripting (XSS)][xss] attack. If you are processing user input, be sure to use a HTML sanitizer, such as rehype-sanitize.

Related

• html-to-notion-blocks
  • Convert HTML to Notion blocks without constructing the procssing pipeline yourself
• @tryfabric/martian
  • Convert Markdown to Notion blocks using a simple API
• rehype-sanitize
• rehype — HTML processor powered by plugins part of the unified collective

License

GPL-3.0-or-later © Thomas F. K. Jorna