@sygnal/notion-html

Convert Notion API blocks and rich text into HTML.

Pure-JS, zero runtime dependencies. Works in Node, browsers, and edge runtimes (Cloudflare Workers).

Install

npm install @sygnal/notion-html

Usage

import { blocksToHtml } from "@sygnal/notion-html";

// `blocks` is an array of Notion block objects from the Notion REST API,
// with nested children attached as block.children.
const html = blocksToHtml(blocks);

Exports

| Function | Purpose | | --- | --- | | blocksToHtml(blocks) | Top-level converter. Walks an array of Notion blocks and returns HTML. | | richTextToHtml(richText) | Convert a Notion rich_text array (inline) to HTML — annotations, links, superscripts. | | cellToHtml(cell) | Convert a single table cell's rich_text array to HTML, with line-splitting and bullet/number list grouping. Used by blocksToHtml for table cells. | | extractPlainText(richText) | Concatenate the plain-text content of a rich_text array. | | escapeHtml(text) | Escape & < > " ' for safe interpolation into HTML. | | NotionBlock (type) | Minimal block-shape type. |

Block coverage

blocksToHtml handles: paragraph, heading_1, heading_2, heading_3, quote, code, image, divider, callout, toggle, table (with table_row), embed, video (Loom and YouTube embeds), bulleted_list_item, numbered_list_item. Unknown block types render as HTML comments.

Table cells with mixed content

Notion table cells are stored as a single rich_text array with \n separators. cellToHtml walks the array, splits on newlines (preserving inline annotations across line breaks), and groups consecutive bulleted lines (• , - , * ) into <ul>, consecutive numbered lines (1. , 2)) into <ol>, and other lines into <p>. Empty lines are skipped.

Styling

This package ships no CSS. Each consumer styles tables, lists, callouts, etc. according to their own design system.