notionic 0.0.0-stage → 0.8.3

package/CHANGELOG.md

@@ -0,0 +1,135 @@
+# notionic
+
+## 0.8.3
+
+### Patch Changes
+
+- [#42](https://github.com/nublson/notionic/pull/42) [`7d202c2`](https://github.com/nublson/notionic/commit/7d202c2bd121d6d6ca94cd0f951ee6ffb72f8cdd) Thanks [@nublson](https://github.com/nublson)! - Adds npm search keywords (`notion-api`, `notion-renderer`, `nextjs`) and a link to GitHub issues to the package metadata.
+
+## 0.8.2
+
+### Patch Changes
+
+- [#39](https://github.com/nublson/notionic/pull/39) [`2d6256c`](https://github.com/nublson/notionic/commit/2d6256c46055aa99c61e7e786a7c3dd03542cad1) Thanks [@nublson](https://github.com/nublson)! - Inline code of up to 24 characters no longer breaks across lines, so short names like `notion-callout` stay whole instead of splitting at a hyphen in narrow columns. Longer code still wraps.
+
+- [#39](https://github.com/nublson/notionic/pull/39) [`2d6256c`](https://github.com/nublson/notionic/commit/2d6256c46055aa99c61e7e786a7c3dd03542cad1) Thanks [@nublson](https://github.com/nublson)! - On touch screens, where heading anchors are always shown, the `#` is smaller and regular weight, so it reads apart from the heading instead of as part of it.
+
+## 0.8.1
+
+### Patch Changes
+
+- [#38](https://github.com/nublson/notionic/pull/38) [`32e56af`](https://github.com/nublson/notionic/commit/32e56afcbfec9ae5c7c1906cfc0d5c80797d8354) Thanks [@nublson](https://github.com/nublson)! - File, PDF, bookmark, embed and link preview cards press in slightly (scale 0.99, 150ms) when clicked; reduced motion keeps only the hover fill. Page link titles fade their underline on hover (150ms) like other links.
+
+- [#38](https://github.com/nublson/notionic/pull/38) [`32e56af`](https://github.com/nublson/notionic/commit/32e56afcbfec9ae5c7c1906cfc0d5c80797d8354) Thanks [@nublson](https://github.com/nublson)! - Heading anchors fade in on hover (150ms) instead of popping in, and toggleable headings grow open and shrink closed with a fade (200ms) in browsers that support `::details-content` and `interpolate-size`; others open instantly as before. Reduced motion keeps only the fade.
+
+- [#38](https://github.com/nublson/notionic/pull/38) [`32e56af`](https://github.com/nublson/notionic/commit/32e56afcbfec9ae5c7c1906cfc0d5c80797d8354) Thanks [@nublson](https://github.com/nublson)! - Links fade their underline to the text color on hover (150ms) instead of switching instantly.
+
+- [#38](https://github.com/nublson/notionic/pull/38) [`32e56af`](https://github.com/nublson/notionic/commit/32e56afcbfec9ae5c7c1906cfc0d5c80797d8354) Thanks [@nublson](https://github.com/nublson)! - Switching tabs fades the new panel in (150ms) instead of swapping it instantly; the first panel still shows at once on page load. The registry's `notion-tabs` does the same.
+
+- [#38](https://github.com/nublson/notionic/pull/38) [`32e56af`](https://github.com/nublson/notionic/commit/32e56afcbfec9ae5c7c1906cfc0d5c80797d8354) Thanks [@nublson](https://github.com/nublson)! - Table of contents entries fade their text and underline in on hover (150ms) instead of switching instantly.
+
+- [#38](https://github.com/nublson/notionic/pull/38) [`32e56af`](https://github.com/nublson/notionic/commit/32e56afcbfec9ae5c7c1906cfc0d5c80797d8354) Thanks [@nublson](https://github.com/nublson)! - Toggles grow open and shrink closed with a fade (200ms), like toggleable headings, in browsers that support `::details-content` and `interpolate-size`. The registry's `notion-toggle` animates its Collapsible panel the same way, and a closed panel no longer leaves an 8px gap.
+
+## 0.8.0
+
+### Minor Changes
+
+- [#37](https://github.com/nublson/notionic/pull/37) [`c2161d2`](https://github.com/nublson/notionic/commit/c2161d22c411df042ea3ec3d3224c602a2e8d1c6) Thanks [@nublson](https://github.com/nublson)! - Tabs render as real tabs instead of an accordion: a row of pills that scrolls sideways when the tabs don't fit, and the selected tab's content below. Still no JavaScript: each tab is a radio button, so the arrow keys switch tabs and scroll the selected one into view. Up to 20 tabs per block.
+
+- [#37](https://github.com/nublson/notionic/pull/37) [`c2161d2`](https://github.com/nublson/notionic/commit/c2161d22c411df042ea3ec3d3224c602a2e8d1c6) Thanks [@nublson](https://github.com/nublson)! - Code blocks name their language as people write it ("TypeScript", "Plain text", "CSS") instead of Notion's lowercase API value, in the label and the accessible name. `languageName` is exported for custom code components; the registry's `notion-code` uses it.
+
+- [#37](https://github.com/nublson/notionic/pull/37) [`c2161d2`](https://github.com/nublson/notionic/commit/c2161d22c411df042ea3ec3d3224c602a2e8d1c6) Thanks [@nublson](https://github.com/nublson)! - Child pages and links to pages render as rows with the page's icon (emoji, custom emoji or image, or a page icon without one) and a hover surface, and rows that follow each other sit close together, like subpages in Notion. `fetchBlocks` now fetches each subpage to attach its icon as `linkedPage`. Image icons on linked pages, dropped before, now render.
+
+- [#37](https://github.com/nublson/notionic/pull/37) [`c2161d2`](https://github.com/nublson/notionic/commit/c2161d22c411df042ea3ec3d3224c602a2e8d1c6) Thanks [@nublson](https://github.com/nublson)! - Embeds and link previews get preview cards like bookmarks: `fetchBlocks` now fetches the page behind each one and attaches its title, description and image as `bookmarkPreview`. Without a preview, they render as a one-line card with a link icon instead of a bare URL that wraps. `bookmarkPreviews: false` turns all of these requests off.
+
+- [#37](https://github.com/nublson/notionic/pull/37) [`c2161d2`](https://github.com/nublson/notionic/commit/c2161d22c411df042ea3ec3d3224c602a2e8d1c6) Thanks [@nublson](https://github.com/nublson)! - Videos: external links to video files (.mp4, .webm, .mov, .m4v, .ogv) play in a video player, as in Notion, instead of rendering as links. Players and YouTube embeds share the image outline and get a muted fill, so they keep their shape while loading.
+
+### Patch Changes
+
+- [#37](https://github.com/nublson/notionic/pull/37) [`c2161d2`](https://github.com/nublson/notionic/commit/c2161d22c411df042ea3ec3d3224c602a2e8d1c6) Thanks [@nublson](https://github.com/nublson)! - Native audio and video players turn dark with the page under the `dark` class, `data-theme="dark"` or `data-mode="dark"`, and are named by their caption for screen readers.
+
+- [#37](https://github.com/nublson/notionic/pull/37) [`c2161d2`](https://github.com/nublson/notionic/commit/c2161d22c411df042ea3ec3d3224c602a2e8d1c6) Thanks [@nublson](https://github.com/nublson)! - Bookmarks without a preview render as a one-line card with a link icon instead of a bare URL that wraps. Preview cards show the URL without its protocol, let the title wrap to two lines on narrow cards, and give the image a muted surface while it loads.
+
+- [#37](https://github.com/nublson/notionic/pull/37) [`c2161d2`](https://github.com/nublson/notionic/commit/c2161d22c411df042ea3ec3d3224c602a2e8d1c6) Thanks [@nublson](https://github.com/nublson)! - Refined callouts: icons sit in a fixed slot centered on the first line, so text lines up across callouts; callouts with a text color keep the default surface, and those with a background color drop the border; custom emoji icons now render.
+
+- [#37](https://github.com/nublson/notionic/pull/37) [`c2161d2`](https://github.com/nublson/notionic/commit/c2161d22c411df042ea3ec3d3224c602a2e8d1c6) Thanks [@nublson](https://github.com/nublson)! - Columns go side by side based on the space they're in (36rem), not the screen width, so a renderer in a sidebar or a card stacks them instead of squeezing them.
+
+- [#37](https://github.com/nublson/notionic/pull/37) [`c2161d2`](https://github.com/nublson/notionic/commit/c2161d22c411df042ea3ec3d3224c602a2e8d1c6) Thanks [@nublson](https://github.com/nublson)! - Refined dividers: twice the usual space on each side, so they read as section breaks; a heading right after a divider drops its own top margin.
+
+- [#37](https://github.com/nublson/notionic/pull/37) [`c2161d2`](https://github.com/nublson/notionic/commit/c2161d22c411df042ea3ec3d3224c602a2e8d1c6) Thanks [@nublson](https://github.com/nublson)! - Embeds render as a one-line card with the URL and the caption below, instead of a bare link labelled by the caption or the raw URL.
+
+- [#37](https://github.com/nublson/notionic/pull/37) [`c2161d2`](https://github.com/nublson/notionic/commit/c2161d22c411df042ea3ec3d3224c602a2e8d1c6) Thanks [@nublson](https://github.com/nublson)! - The plain equation block shares the code block's surface and type, and tells screen readers it's an equation's LaTeX source.
+
+- [#37](https://github.com/nublson/notionic/pull/37) [`c2161d2`](https://github.com/nublson/notionic/commit/c2161d22c411df042ea3ec3d3224c602a2e8d1c6) Thanks [@nublson](https://github.com/nublson)! - Files render as cards: an icon, the file name on one line (the full name as a tooltip when it truncates), its type, and the caption below, which was dropped before when a file had a name.
+
+- [#37](https://github.com/nublson/notionic/pull/37) [`c2161d2`](https://github.com/nublson/notionic/commit/c2161d22c411df042ea3ec3d3224c602a2e8d1c6) Thanks [@nublson](https://github.com/nublson)! - Refined headings: the anchor link follows the last word when a heading wraps, with a larger hit area; headings balance their lines and use a tighter line height; every level keeps twice as much space above as below; colored headings span the full width; toggleable headings use a chevron that rotates when open, with their content aligned to the heading text.
+
+- [#37](https://github.com/nublson/notionic/pull/37) [`c2161d2`](https://github.com/nublson/notionic/commit/c2161d22c411df042ea3ec3d3224c602a2e8d1c6) Thanks [@nublson](https://github.com/nublson)! - Images get an inset 1px outline, black at 10% (white at 10% in dark mode), so light images keep their edge against the page. It's the `--notionic-image-outline` variable, to change or turn off.
+
+- [#37](https://github.com/nublson/notionic/pull/37) [`c2161d2`](https://github.com/nublson/notionic/commit/c2161d22c411df042ea3ec3d3224c602a2e8d1c6) Thanks [@nublson](https://github.com/nublson)! - Refined lists: nested bullets go disc, circle, square and nested numbers 1., a., i., as in Notion; bullets use the muted color; to-do checkboxes are drawn like shadcn's Checkbox instead of a dimmed disabled control, centered on the first line; nested to-dos are indented under their parent's text. The theme now also uses `primary-foreground` (see "Use your own theme tokens").
+
+- [#37](https://github.com/nublson/notionic/pull/37) [`c2161d2`](https://github.com/nublson/notionic/commit/c2161d22c411df042ea3ec3d3224c602a2e8d1c6) Thanks [@nublson](https://github.com/nublson)! - Refined text rendering: long words, URLs and inline code wrap instead of overflowing narrow screens; body line height is 1.6; colored backgrounds bleed past the text so it stays aligned with the blocks around it; inline code and highlights keep their padding and corners across line breaks; underlines use the font's thickness; indents and borders use logical properties, so they mirror in right-to-left languages.
+
+- [#37](https://github.com/nublson/notionic/pull/37) [`c2161d2`](https://github.com/nublson/notionic/commit/c2161d22c411df042ea3ec3d3224c602a2e8d1c6) Thanks [@nublson](https://github.com/nublson)! - PDFs render as file cards, named after the file and typed "PDF", with the caption below, instead of a bare link showing the caption or the raw URL. Uploaded files keep their name when `transformFileUrl` returns a URL without one.
+
+- [#37](https://github.com/nublson/notionic/pull/37) [`c2161d2`](https://github.com/nublson/notionic/commit/c2161d22c411df042ea3ec3d3224c602a2e8d1c6) Thanks [@nublson](https://github.com/nublson)! - Refined quotes: emphasis inside a quote turns roman so it still stands out against the italic, and quotes with a background color get padding on their open sides and rounded end corners.
+
+- [#37](https://github.com/nublson/notionic/pull/37) [`c2161d2`](https://github.com/nublson/notionic/commit/c2161d22c411df042ea3ec3d3224c602a2e8d1c6) Thanks [@nublson](https://github.com/nublson)! - Refined tables: columns size to their content, up to 16rem before text wraps, and a table wider than the page scrolls sideways instead of squeezing every column to its narrowest; cells align to the start edge and numbers use tabular figures.
+
+- [#37](https://github.com/nublson/notionic/pull/37) [`c2161d2`](https://github.com/nublson/notionic/commit/c2161d22c411df042ea3ec3d3224c602a2e8d1c6) Thanks [@nublson](https://github.com/nublson)! - Table of contents entries are 28px tap targets with no gaps between them.
+
+- [#37](https://github.com/nublson/notionic/pull/37) [`c2161d2`](https://github.com/nublson/notionic/commit/c2161d22c411df042ea3ec3d3224c602a2e8d1c6) Thanks [@nublson](https://github.com/nublson)! - Refined toggles: the same chevron as toggleable headings replaces the browser's triangle, and a wrapped summary and the toggle's content line up on one edge.
+
+## 0.7.0
+
+### Minor Changes
+
+- [#32](https://github.com/nublson/notionic/pull/32) [`df7d4ec`](https://github.com/nublson/notionic/commit/df7d4ecbab5eec6ee7a32eef50adb2881cfa9ea7) Thanks [@nublson](https://github.com/nublson)! - Interactive demos: pass your own React components as `demos={{ "morph-button": MorphButton }}`, and an embed of a URL ending in `/demos/<name>` renders that component in its place, in a frame with the embed's caption below. The URL's query reaches the demo as `params`. Replace the frame with `components.demo`.
+
+## 0.6.0
+
+### Minor Changes
+
+- [#31](https://github.com/nublson/notionic/pull/31) [`74ce1db`](https://github.com/nublson/notionic/commit/74ce1db5d931342e0b4f0525d51337d6049f1c80) Thanks [@nublson](https://github.com/nublson)! - Bookmarks render as cards with the bookmarked page's title, description, image and favicon, like in Notion. `fetchBlocks` reads them from the page's Open Graph tags and attaches them as `bookmarkPreview`; pass `bookmarkPreviews: false` to make no requests outside Notion. Bookmarks without a preview still render as links.
+
+## 0.5.0
+
+### Minor Changes
+
+- [#28](https://github.com/nublson/notionic/pull/28) [`0dfca00`](https://github.com/nublson/notionic/commit/0dfca00345d8233b850794246b144a54d460e42c) Thanks [@nublson](https://github.com/nublson)! - Follow any dark mode setup and renamed theme tokens
+
+- [#27](https://github.com/nublson/notionic/pull/27) [`ba01dfd`](https://github.com/nublson/notionic/commit/ba01dfdf42934715ffa8a2e9d0597058e5047443) Thanks [@nublson](https://github.com/nublson)! - Notion's background colors (`--notionic-*-bg`) are now mixed from their text color and your theme's `--background`, so overriding the nine text colors (for example `--notionic-red: var(--destructive)`) themes the backgrounds too, in light and dark mode. `--notionic-bg-mix` sets their strength.
+
+## 0.4.0
+
+### Minor Changes
+
+- [#22](https://github.com/nublson/notionic/pull/22) [`ed4a20a`](https://github.com/nublson/notionic/commit/ed4a20a0ecddb51efb507a618cb133c0cb452682) Thanks [@nublson](https://github.com/nublson)! - Add `notionic/markdown` with `blocksToMarkdown(blocks, options)`, which turns Notion blocks into GitHub-flavored Markdown for feeds and `llms.txt`. It supports every block `NotionRenderer` does, and takes the same `pageHref` and `transformFileUrl` options.
+
+## 0.3.0
+
+### Minor Changes
+
+- [#18](https://github.com/nublson/notionic/pull/18) [`106aa72`](https://github.com/nublson/notionic/commit/106aa72d6903a8e6a622b8e5a67c4cdbd7a89010) Thanks [@nublson](https://github.com/nublson)! - **Breaking:** notionic now requires React 19. The peer dependency changes from `^18.0.0 || ^19.0.0` to `^19.0.0`. React 18 was never tested, and the package only targets React Server Components frameworks, which run React 19. If you're on React 18, stay on notionic 0.2.
+
+- [#17](https://github.com/nublson/notionic/pull/17) [`8e279be`](https://github.com/nublson/notionic/commit/8e279bedc56421ad3fd280a99dec8795f0bab0e9) Thanks [@nublson](https://github.com/nublson)! - Add `transformFileUrl` to `NotionRenderer`, which rewrites the URLs of files uploaded to Notion (images, videos, files, PDFs, audio and callout icons), so they can point at a route that re-signs them before Notion's one-hour expiry. `resolveFileUrl` applies it in custom components.
+
+### Patch Changes
+
+- [#16](https://github.com/nublson/notionic/pull/16) [`63119a9`](https://github.com/nublson/notionic/commit/63119a996698fa551a9827d24a72447201b99ea3) Thanks [@nublson](https://github.com/nublson)! - Lint and format with Biome
+
+## 0.2.0
+
+### Minor Changes
+
+- [#12](https://github.com/nublson/notionic/pull/12) [`05c92ea`](https://github.com/nublson/notionic/commit/05c92ea7365d60784063c01d1d07b9ade8e32eca) Thanks [@nublson](https://github.com/nublson)! - Add `fetchPage`, which returns a page's title, icon, cover, last edited time and properties with its blocks. `fetchBlocks` now attaches the linked page's title and icon to `link_to_page` blocks, which render as links through `pageHref`.
+
+## 0.1.0
+
+### Minor Changes
+
+- [#10](https://github.com/nublson/notionic/pull/10) [`3ed98f2`](https://github.com/nublson/notionic/commit/3ed98f27cde1d25544c1b8f31a0dbd6cc523c9ff) Thanks [@nublson](https://github.com/nublson)! - Render table of contents, tabs, line breaks within text and date mentions, found by rendering a real Notion page. `collectHeadings` returns the page's headings with their anchor ids, for outlines. Equations inside text can be replaced with the new `inline_equation` component, which the registry's `notion-equation` (KaTeX) uses. The registry also adds `notion-tabs` (shadcn Tabs) and `notion-mermaid` (diagrams).
+
+## 0.0.1
+
+- First release: `NotionRenderer` for Notion API blocks as React Server Components, styled with Tailwind CSS and shadcn/ui tokens; `fetchBlocks` in `notionic/fetch`; and `notionic/styles.css`.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Nubelson
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,262 @@
-# Temporary Holding Version
+# notionic
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+[![npm](https://img.shields.io/npm/v/notionic)](https://www.npmjs.com/package/notionic)
+[![CI](https://github.com/nublson/notionic/actions/workflows/ci.yml/badge.svg?branch=main)](https://github.com/nublson/notionic/actions/workflows/ci.yml)
+[![License: MIT](https://img.shields.io/npm/l/notionic)](https://github.com/nublson/notionic/blob/main/LICENSE)
+
+Render blocks from the [official Notion API](https://developers.notion.com) as React Server Components, styled with Tailwind CSS and shadcn/ui's theme tokens.
+
+- **Server-first.** Every block renders on the server; notionic ships no client JavaScript.
+- **Follows your theme.** Components use shadcn/ui tokens (`foreground`, `muted`, `border`…), so they match your app, dark mode included.
+- **Replaceable.** Swap the component for any block type.
+- **Zero runtime dependencies** besides React.
+
+> Early development. The API may change before 1.0.
+
+## Install
+
+```bash
+pnpm add notionic @notionhq/client
+```
+
+notionic needs React 19. `@notionhq/client` is only needed to fetch blocks with `notionic/fetch`.
+
+## Set up Tailwind CSS
+
+notionic needs Tailwind CSS v4. Import its styles after Tailwind:
+
+```css
+@import "tailwindcss";
+@import "notionic/styles.css";
+```
+
+This one line tells Tailwind to scan notionic's components, and defines Notion's nine colors as `--notionic-*` variables. Their dark values apply under the `dark` class, `data-theme="dark"` or `data-mode="dark"`, and on pages whose [`color-scheme`](https://developer.mozilla.org/docs/Web/CSS/color-scheme) is dark, so a page that follows `prefers-color-scheme` gets them by declaring `color-scheme: light dark`.
+
+### Match Notion's colors to your brand
+
+Override the text colors after the import. Each background color (`--notionic-red-bg`…) is mixed from its text color and your `--background`, so it follows on its own:
+
+```css
+:root,
+.dark {
+  --notionic-red: var(--destructive);
+  --notionic-blue: var(--primary);
+}
+```
+
+Mapping to tokens that already switch in dark mode, like shadcn's, keeps both modes right. To make every background stronger or subtler, set `--notionic-bg-mix` (default `14%`, `22%` in dark mode); to set one background directly, override its `--notionic-*-bg`.
+
+### Use your own theme tokens
+
+The components use shadcn/ui's color tokens, and Tailwind only generates their classes if your theme defines them. If your design system names them differently, map yours to these eight, after importing notionic:
+
+```css
+@theme inline {
+  --color-background: var(--color-page);
+  --color-foreground: var(--color-text);
+  --color-muted: var(--color-surface);
+  --color-muted-foreground: var(--color-text-subtle);
+  --color-border: var(--color-line);
+  --color-ring: var(--color-focus);
+  --color-primary: var(--color-brand);
+  --color-primary-foreground: var(--color-on-brand);
+}
+```
+
+Replace each right-hand side with your own token. notionic needs no others.
+
+## Render a page
+
+```tsx
+import { Client } from "@notionhq/client";
+import { NotionRenderer } from "notionic";
+import { fetchBlocks } from "notionic/fetch";
+
+const notion = new Client({ auth: process.env.NOTION_TOKEN });
+
+export default async function Page() {
+  const blocks = await fetchBlocks(notion, "your-page-id");
+  return <NotionRenderer blocks={blocks} />;
+}
+```
+
+To also get the page's title, icon, cover and properties, use `fetchPage(notion, pageId)`, which returns `{ page, blocks }`.
+
+`fetchBlocks` fetches every block of the page with its nested blocks, following pagination. It limits requests in flight (`concurrency`, default 3) and nesting depth (`maxDepth`, default 5). It doesn't cache: use your framework's cache, such as Next.js's `"use cache"`.
+
+For bookmarks, embeds and link previews, `fetchBlocks` also fetches the linked page and reads its title, description, image and favicon, so the block renders as a card like a Notion bookmark. A page that's slow (over 5 seconds), unreachable or untitled renders as a one-line card with the URL, and private network addresses are never fetched. Pass `bookmarkPreviews: false` to make no requests outside Notion.
+
+You can also pass blocks you fetched yourself: `NotionRenderer` takes the API's block objects with nested blocks attached as `children` (the `NotionBlock` type).
+
+## Options
+
+### Link Notion pages to your routes
+
+Links to other Notion pages point to notion.so by default. Map them to your own routes with `pageHref`, or return `null` to render the text without a link:
+
+```tsx
+<NotionRenderer
+  blocks={blocks}
+  pageHref={(pageId) => routes.get(pageId) ?? null}
+/>
+```
+
+`pageId` is 32 lowercase hex characters, without dashes.
+
+### Replace a block's component
+
+```tsx
+import { NotionRenderer, RichText, type BlockProps } from "notionic";
+
+function Callout({ block, context, children }: BlockProps<"callout">) {
+  return (
+    <aside className="rounded-lg border p-4">
+      <RichText text={block.callout.rich_text} context={context} />
+      {children}
+    </aside>
+  );
+}
+
+<NotionRenderer blocks={blocks} components={{ callout: Callout }} />;
+```
+
+`children` holds the block's nested blocks, already rendered.
+
+`notion-mermaid` loads Mermaid in the browser only on pages with a diagram, follows the `dark` class, and keeps showing the code until the diagram draws, or if its source doesn't parse. Wrap the code component you use: `withMermaid(NotionCode)`, or `withMermaid(defaultComponents.code)`.
+
+Equations inside text have their own key, `inline_equation`, whose component gets the equation's LaTeX as `expression`.
+
+### Interactive demos
+
+Put your own React components in a page, like the demos in a design engineering blog. Each demo is a component in your project, so it can use anything you install (Motion, Sonner, charts, 3D). In Notion, an embed of a URL ending in `/demos/<name>` marks where it goes, and its caption goes below it.
+
+```tsx
+// components/demos/morph-button.tsx
+"use client";
+export function MorphButton({ params }: DemoProps) { /* … */ }
+
+// app/page.tsx
+<NotionRenderer blocks={blocks} demos={{ "morph-button": MorphButton }} />;
+```
+
+In Notion, add `/embed` with `https://your-site.com/demos/morph-button`. Only the path counts, so the same embed renders on localhost and previews. The URL's query reaches the demo as `params`: `?speed=slow` is `{ speed: "slow" }`. Unknown names render as links.
+
+To see the demo inside Notion while you write, add a page at `/demos/[name]` that renders the demo alone:
+
+```tsx
+// app/demos/[name]/page.tsx
+export default async function DemoPage({ params }: { params: Promise<{ name: string }> }) {
+  const { name } = await params;
+  const Demo = Object.hasOwn(demos, name) ? demos[name] : undefined;
+  if (!Demo) notFound();
+  return <main className="grid min-h-svh place-items-center"><Demo name={name} params={{}} /></main>;
+}
+```
+
+Demos render in `DemoFrame`, a bordered stage with the caption centered below. Replace it with `components={{ demo: MyFrame }}`; it gets the demo as `children`, plus `name`, `caption` and `context`. Only the demos a page uses send JavaScript to the browser.
+
+## Supported blocks
+
+Paragraph (with line breaks), headings 1–4 (including toggleable headings), bulleted, numbered and to-do lists, quote, callout, toggle, divider, equation, code, table, columns, tabs, table of contents, synced block, image, video (YouTube or file), audio, file, PDF, bookmark (a card with the page's title, description and image, from `fetchBlocks`), embed and link preview (cards like bookmarks, or for an embed one of your demos), and child page and link to page (with their icons and titles, from `fetchBlocks`). Date mentions render as `<time>`.
+
+Notion's heading 1 renders as `<h2>`, since your page title is the `<h1>`; heading 2 as `<h3>`, and so on. Headings get ids and anchor links.
+
+Tabs render as real tabs with no JavaScript: a row of pills that scrolls sideways, and one panel at a time. To use shadcn's Tabs component instead, add `notion-tabs` from the shadcn registry.
+
+Code renders as plain text. For syntax highlighting, use `notion-code` from the shadcn registry below. Equations, in blocks and inside text, show their LaTeX source; `notion-equation` typesets them with KaTeX.
+
+Unsupported blocks render nothing, with a warning in development.
+
+### Page outline
+
+`collectHeadings(blocks)` returns the page's headings in reading order, with the same anchor ids the rendered headings get, for a sidebar outline:
+
+```tsx
+import { collectHeadings } from "notionic";
+
+const outline = collectHeadings(blocks); // [{ id: "intro", text: "Intro", level: 1, blockId }]
+```
+
+## shadcn/ui components
+
+notionic's shadcn registry has versions of some blocks built on your own shadcn/ui components. The shadcn CLI copies them into your project, with the shadcn components they use, so you can edit them.
+
+| Item | Built on |
+| --- | --- |
+| `notion-code` | Code Block, highlighted on the server with Shiki, with a copy button |
+| `notion-callout` | Alert |
+| `notion-table` | Table |
+| `notion-toggle` | Collapsible |
+| `notion-tabs` | Tabs, with every panel kept in the HTML |
+| `notion-equation` | KaTeX, rendered on the server: equation blocks and equations inside text |
+| `notion-mermaid` | Mermaid: draws `mermaid` code blocks as diagrams, wrapping your code component |
+
+Add the registry to your `components.json`:
+
+```json
+{
+  "registries": {
+    "@notionic": "https://notionic.dev/r/{name}.json"
+  }
+}
+```
+
+Then add the items you want, and pass them to `components`:
+
+```bash
+npx shadcn@latest add @notionic/notion-code @notionic/notion-callout @notionic/notion-table @notionic/notion-toggle @notionic/notion-tabs @notionic/notion-equation @notionic/notion-mermaid
+```
+
+```tsx
+import { NotionCallout } from "@/components/notion-callout";
+import { NotionCode } from "@/components/notion-code";
+import { NotionTable } from "@/components/notion-table";
+import { NotionToggle } from "@/components/notion-toggle";
+import { NotionTabs } from "@/components/notion-tabs";
+import { NotionEquation, NotionInlineEquation } from "@/components/notion-equation";
+import { withMermaid } from "@/components/notion-mermaid";
+
+<NotionRenderer
+  blocks={blocks}
+  components={{
+    code: withMermaid(NotionCode),
+    callout: NotionCallout,
+    table: NotionTable,
+    toggle: NotionToggle,
+    tab: NotionTabs,
+    equation: NotionEquation,
+    inline_equation: NotionInlineEquation,
+  }}
+/>;
+```
+
+`notion-code` highlights the languages listed in `lib/highlighter.tsx`, which comes with shadcn's Code Block. Add a language there to highlight it; others render as plain text.
+
+## Markdown
+
+`notionic/markdown` turns the same blocks into GitHub-flavored Markdown, for RSS feeds, `llms.txt` and other plain-text uses:
+
+```ts
+import { blocksToMarkdown } from "notionic/markdown";
+
+const markdown = `# ${page.title}\n\n${blocksToMarkdown(blocks, { pageHref, transformFileUrl })}`;
+```
+
+It takes the same `pageHref` and `transformFileUrl` as `NotionRenderer`, so links and files match the HTML. Notion's heading 1 becomes `##`, so add the page title yourself. Toggles become `<details>`, equations `$…$` and `$$…$$`.
+
+## Uploaded files
+
+Notion's URLs for uploaded files (images, videos, files, icons) expire after an hour, which is shorter than most pages are cached. Pass `transformFileUrl` to point them at a route of yours that fetches a fresh URL:
+
+```tsx
+<NotionRenderer
+  blocks={blocks}
+  transformFileUrl={({ blockId }) => `/api/notion/file/${blockId}`}
+/>
+```
+
+The route retrieves the block with the Notion API (`notion.blocks.retrieve`) and redirects to its file's current URL. notionic.dev's route is a working example: `apps/web/app/api/notion/file/[blockId]/route.ts`. External URLs never go through `transformFileUrl`.
+
+## License
+
+MIT

package/dist/fetch.d.ts

@@ -0,0 +1,62 @@
+import { C as IdRequest, S as ListBlockChildrenResponse, T as PartialPageObjectResponse, f as NotionPage, u as NotionBlock, w as PageObjectResponse, x as ListBlockChildrenParameters } from "./types-DOxr5KpT.js";
+//#region ../../node_modules/.pnpm/@notionhq+client@5.27.1/node_modules/@notionhq/client/build/src/api-endpoints/pages.d.ts
+type GetPagePathParameters = {
+  page_id: IdRequest;
+};
+type GetPageQueryParameters = {
+  filter_properties?: Array<string>;
+};
+type GetPageParameters = GetPagePathParameters & GetPageQueryParameters;
+type GetPageResponse = PartialPageObjectResponse | PageObjectResponse;
+//#endregion
+//#region src/fetch.d.ts
+/**
+ * The part of the Notion client notionic uses. A `Client` from
+ * `@notionhq/client` satisfies it. Without `pages`, `link_to_page` blocks
+ * get no titles and subpages no icons.
+ */
+export type NotionClientLike = {
+  blocks: {
+    children: {
+      list(args: ListBlockChildrenParameters): Promise<ListBlockChildrenResponse>;
+    };
+  };
+  pages?: {
+    retrieve(args: GetPageParameters): Promise<GetPageResponse>;
+  };
+};
+export type FetchBlocksOptions = {
+  /** How many levels of nested blocks to fetch below the top level. Default 5. */
+  maxDepth?: number;
+  /**
+   * Max child-block requests in flight per level. Default 3, Notion's average
+   * rate limit per second.
+   */
+  concurrency?: number;
+  /**
+   * Fetch the page behind each bookmark, embed and link preview to read its
+   * title, description and image for a preview card. Default true. A page
+   * that's slow, unreachable or has no title renders as a one-line card.
+   */
+  bookmarkPreviews?: boolean;
+};
+/**
+ * Every block of a page (or any block), with nested blocks attached as
+ * `children`, ready for `<NotionRenderer>`.
+ *
+ * Child pages and databases are separate documents, so their content is not
+ * fetched. Caching is left to your framework.
+ */
+export declare function fetchBlocks(client: NotionClientLike, blockId: string, options?: FetchBlocksOptions): Promise<NotionBlock[]>;
+/**
+ * A page's metadata (title, icon, cover, properties…) and every block of it.
+ * Throws if the page doesn't exist or isn't shared with the integration.
+ */
+export declare function fetchPage(client: NotionClientLike & {
+  pages: NonNullable<NotionClientLike["pages"]>;
+}, pageId: string, options?: FetchBlocksOptions): Promise<{
+  page: NotionPage;
+  blocks: NotionBlock[];
+}>;
+//#endregion
+export {};