### Navigate to example project and start development server Source: https://github.com/notionx/react-notion-x/blob/master/contributing.md Steps to navigate to the minimal example project and start its Next.js development server. ```bash cd examples/minimal pnpm dev ``` -------------------------------- ### Development Server Start Source: https://github.com/notionx/react-notion-x/blob/master/examples/minimal/readme.md Commands to start the development server using npm or yarn. ```bash npm run dev # or yarn dev ``` -------------------------------- ### Install Source: https://github.com/notionx/react-notion-x/blob/master/packages/notion-client/readme.md Install the notion-client package using npm. ```bash npm install notion-client ``` -------------------------------- ### Install Source: https://github.com/notionx/react-notion-x/blob/master/packages/notion-x-to-md/readme.md Install the notion-x-to-md package using npm. ```bash npm install notion-x-to-md ``` -------------------------------- ### Install notion-utils Source: https://github.com/notionx/react-notion-x/blob/master/packages/notion-utils/readme.md Install the notion-utils package using npm. ```bash npm install notion-utils ``` -------------------------------- ### NotionAPI Initialization Example Source: https://github.com/notionx/react-notion-x/blob/master/_autodocs/configuration.md Example of initializing the NotionAPI client with custom options. ```typescript import { NotionAPI } from 'notion-client' const api = new NotionAPI({ authToken: process.env.NOTION_TOKEN, userTimeZone: 'Europe/London', ofetchOptions: { timeout: 30000, headers: { 'User-Agent': 'MyApp/1.0' } } }) ``` -------------------------------- ### NotionAPI Constructor Example Source: https://github.com/notionx/react-notion-x/blob/master/_autodocs/api-reference/notion-api.md Example of how to instantiate the NotionAPI client. ```typescript import { NotionAPI } from 'notion-client' const notion = new NotionAPI({ authToken: process.env.NOTION_TOKEN, userTimeZone: 'UTC' }) ``` -------------------------------- ### getPage Example Source: https://github.com/notionx/react-notion-x/blob/master/_autodocs/api-reference/notion-api.md Example of fetching a Notion page with specific options. ```typescript const notion = new NotionAPI({ authToken: process.env.NOTION_TOKEN }) const recordMap = await notion.getPage('d4d88c36f395471352b13ce9ada3be82', { concurrency: 5, fetchCollections: true, signFileUrls: true }) ``` -------------------------------- ### Start development compilation Source: https://github.com/notionx/react-notion-x/blob/master/contributing.md Command to start compiling the project packages. ```bash pnpm dev ``` -------------------------------- ### notion-client usage example Source: https://github.com/notionx/react-notion-x/blob/master/_autodocs/api-reference/packages-overview.md Example of initializing and using the NotionAPI client from the notion-client package. ```typescript import { NotionAPI } from 'notion-client' const api = new NotionAPI({ authToken: process.env.NOTION_TOKEN }) const recordMap = await api.getPage(pageId) ``` -------------------------------- ### notion-compat import example Source: https://github.com/notionx/react-notion-x/blob/master/_autodocs/api-reference/packages-overview.md Example of importing and using NotionCompatAPI to fetch and convert a Notion page. ```typescript import { NotionCompatAPI } from 'notion-compat' import { Client } from '@notionhq/client' const client = new Client({ auth: process.env.NOTION_TOKEN }) const compat = new NotionCompatAPI(client) const recordMap = await compat.getPage(pageId) ``` -------------------------------- ### getBlocks Example Source: https://github.com/notionx/react-notion-x/blob/master/_autodocs/api-reference/notion-api.md Example of fetching multiple blocks by their IDs. ```typescript const pageChunk = await notion.getBlocks(['block1', 'block2', 'block3']) ``` -------------------------------- ### General Page Layout and Styling Example Source: https://github.com/notionx/react-notion-x/blob/master/_autodocs/configuration.md Example demonstrating various layout and styling props for NotionRenderer. ```typescript } footer={} darkMode={isDarkMode} showTableOfContents={true} /> ``` -------------------------------- ### getPage Minimal Configuration Example Source: https://github.com/notionx/react-notion-x/blob/master/_autodocs/configuration.md Example of configuring getPage for minimal configuration (fastest). ```typescript const recordMap = await api.getPage(pageId, { concurrency: 1, // sequential requests fetchMissingBlocks: false, // skip missing blocks fetchCollections: false, // skip collections signFileUrls: false, // skip file signing fetchCustomEmojis: false // skip emoji data }) ``` -------------------------------- ### Installation Source: https://github.com/notionx/react-notion-x/blob/master/_autodocs/README.md Install the main rendering library, API client, and optional compatibility layers or markdown conversion utilities. ```bash # Main rendering library npm install react-notion-x notion-types notion-utils # API client npm install notion-client # Optionally: compatibility layer with official Notion SDK npm install notion-compat @notionhq/client # Optionally: markdown conversion npm install notion-x-to-md ``` -------------------------------- ### search Example Source: https://github.com/notionx/react-notion-x/blob/master/_autodocs/api-reference/notion-api.md Example usage of the search function. ```typescript const results = await notion.search({ ancestorId: 'd4d88c36f395471352b13ce9ada3be82', query: 'meeting notes', limit: 20 }) ``` -------------------------------- ### Install notion-types Source: https://github.com/notionx/react-notion-x/blob/master/packages/notion-types/readme.md Install the notion-types package using npm. ```bash npm install notion-types ``` -------------------------------- ### NotionContextProvider Example Source: https://github.com/notionx/react-notion-x/blob/master/_autodocs/api-reference/react-notion-x.md Example usage of the NotionContextProvider component. ```typescript import { NotionContextProvider, NotionRenderer } from 'react-notion-x' export function Page({ recordMap }) { return ( `/page/${id.slice(0, 8)}`} > ) } ``` -------------------------------- ### getPage Performance-Optimized Configuration Example Source: https://github.com/notionx/react-notion-x/blob/master/_autodocs/configuration.md Example of configuring getPage for performance optimization. ```typescript const recordMap = await api.getPage(pageId, { concurrency: 10, // fetch faster fetchCollections: true, // preload collection data fetchMissingBlocks: true, // ensure complete data signFileUrls: true, // enable file downloads collectionReducerLimit: 100 // limit collection size }) ``` -------------------------------- ### useNotionContext Example Source: https://github.com/notionx/react-notion-x/blob/master/_autodocs/api-reference/react-notion-x.md Example usage of the useNotionContext hook. ```typescript import { useNotionContext } from 'react-notion-x' function CustomBlock() { const { darkMode, recordMap, mapPageUrl } = useNotionContext() return (
{/* Custom block implementation */}
) } ``` -------------------------------- ### Custom Components Example Source: https://github.com/notionx/react-notion-x/blob/master/_autodocs/configuration.md Example of providing custom React components for blocks like Code and Equation. ```typescript ( ), Equation: ({ latex }) => }} /> ``` -------------------------------- ### Clone the repository and install dependencies Source: https://github.com/notionx/react-notion-x/blob/master/contributing.md Steps to clone the react-notion-x repository and install its dependencies using pnpm. ```bash git clone https://github.com/NotionX/react-notion-x.git cd react-notion-x pnpm install ``` -------------------------------- ### addSignedUrls Example Source: https://github.com/notionx/react-notion-x/blob/master/_autodocs/api-reference/notion-api.md Example usage of the addSignedUrls function. ```typescript await notion.addSignedUrls({ recordMap, contentBlockIds: ['pdf-block-1', 'image-block-2'] }) ``` -------------------------------- ### notion-utils import example Source: https://github.com/notionx/react-notion-x/blob/master/_autodocs/api-reference/packages-overview.md Example of importing utility functions from the notion-utils package. ```typescript import { getPageTitle, getPageProperty, parsePageId, estimatePageReadTime } from 'notion-utils' ``` -------------------------------- ### notion-x-to-md import example Source: https://github.com/notionx/react-notion-x/blob/master/_autodocs/api-reference/packages-overview.md Example of importing and using notionPageToMarkdown to convert a Notion record map to Markdown. ```typescript import { notionPageToMarkdown } from 'notion-x-to-md' const markdown = await notionPageToMarkdown(recordMap) console.log(markdown) ``` -------------------------------- ### TypeScript Support Import Example Source: https://github.com/notionx/react-notion-x/blob/master/_autodocs/api-reference/packages-overview.md Example of importing TypeScript type definitions for Notion packages. ```typescript import type { Block, ExtendedRecordMap } from 'notion-types' import { NotionAPI } from 'notion-client' import { NotionRenderer } from 'react-notion-x' ``` -------------------------------- ### estimatePageReadTime example Source: https://github.com/notionx/react-notion-x/blob/master/_autodocs/api-reference/notion-utils.md Example usage of estimatePageReadTime. ```typescript import { estimatePageReadTime } from 'notion-utils' const estimate = estimatePageReadTime(rootBlock, recordMap) console.log(`Read time: ${estimate.totalReadTimeInMinutes.toFixed(1)} minutes`) ``` -------------------------------- ### notion-types import example Source: https://github.com/notionx/react-notion-x/blob/master/_autodocs/api-reference/packages-overview.md Example of importing core types from the notion-types package. ```typescript import type { Block, ExtendedRecordMap, Collection, SearchResults, Color, PropertyType } from 'notion-types' ``` -------------------------------- ### HTML-ish Example Source: https://github.com/notionx/react-notion-x/blob/master/packages/notion-x-to-md/examples/0c322c33381c49bca5083a451c334c39.md An example labeled as 'HTML-ish' containing a hierarchical list with emojis. ```HTML 🦄 Team Abstract ☕ Tightrope Coffee ✨ Mobile App ✨ Landing Page ✨ Kiosk UI ``` -------------------------------- ### react-notion-x usage example Source: https://github.com/notionx/react-notion-x/blob/master/_autodocs/api-reference/packages-overview.md Example of using the NotionRenderer component from the react-notion-x package and importing its styles. ```typescript import { NotionRenderer, NotionContextProvider, useNotionContext } from 'react-notion-x' import 'react-notion-x/styles.css' ``` -------------------------------- ### NotionRenderer Props Example Source: https://github.com/notionx/react-notion-x/blob/master/_autodocs/configuration.md Example of configuring the NotionRenderer component with custom URL mapping functions. ```jsx `/docs/${pageId.slice(0, 8)}`} mapImageUrl={(url, block) => { if (!url) return '' if (url.includes('notion-static')) return `/cdn/${btoa(url)}` return url }} /> ``` -------------------------------- ### Usage Example Source: https://github.com/notionx/react-notion-x/blob/master/packages/notion-compat/readme.md Demonstrates how to initialize and use NotionCompatAPI to fetch a page's record map. ```typescript import { Client } from '@notionhq/client' import { NotionCompatAPI } from 'notion-compat' const notion = new NotionCompatAPI( new Client({ auth: process.env.NOTION_TOKEN }) ) const recordMap = await notion.getPage(pageId) ``` -------------------------------- ### Notion API Client Example Source: https://github.com/notionx/react-notion-x/blob/master/packages/notion-x-to-md/examples/0c322c33381c49bca5083a451c334c39.md JavaScript example demonstrating how to use the NotionAPI client to fetch collection data. ```JavaScript const { NotionAPI } = require('./build') async function main() { const api = new NotionAPI() // const output = await api.getPage('067dd719-a912-471e-a9a3-ac10710e7fdf') const collectionId = '2d8aec23-8281-4a94-9090-caaf823dd21a' const collectionViewId = 'ab639a5a-853e-45e1-9ef7-133b486c0acf' const output = await api.getCollectionData(collectionId, collectionViewId) console.log(JSON.stringify(output, null, 2)) } main() ``` -------------------------------- ### SearchNotionFn Example Source: https://github.com/notionx/react-notion-x/blob/master/_autodocs/api-reference/react-notion-x.md Example implementation of the SearchNotionFn to perform searches using NotionAPI.search. ```typescript const searchNotion = async (params) => { const { query, ancestorId, limit, filters } = params // Use NotionAPI.search const results = await notionApi.search({ query, ancestorId, limit: limit || 20, filters }) return results } ``` -------------------------------- ### Example: Custom MapPageUrlFn Source: https://github.com/notionx/react-notion-x/blob/master/_autodocs/api-reference/react-notion-x.md Example implementation of a custom mapPageUrl function for react-notion-x. ```typescript const mapPageUrl = (pageId, recordMap) => { // Simple slug-based URL const slug = pageId.slice(0, 8) return `/docs/${slug}` // Or use page title // const title = getPageTitle(recordMap) // return `/docs/${slugify(title)}` // Or full URL // return `https://mysite.com/page/${pageId}` } ``` -------------------------------- ### Default Page Styling Example Source: https://github.com/notionx/react-notion-x/blob/master/_autodocs/configuration.md Example of how to set default page icon, cover, and cover position using NotionRenderer props. ```typescript ``` -------------------------------- ### NotionBlockRenderer Example Source: https://github.com/notionx/react-notion-x/blob/master/_autodocs/api-reference/notion-renderer.md Example of how to use the NotionBlockRenderer component to render a specific block. ```typescript import { NotionBlockRenderer } from 'react-notion-x' // Render a specific block from the record map ``` -------------------------------- ### Pattern 2: Using Official Notion SDK with Compatibility Layer Source: https://github.com/notionx/react-notion-x/blob/master/_autodocs/api-reference/packages-overview.md Example demonstrating the use of the official Notion SDK with the compatibility layer for data conversion. ```typescript import { NotionCompatAPI } from 'notion-compat' import { Client } from '@notionhq/client' const client = new Client({ auth: process.env.NOTION_TOKEN }) const compat = new NotionCompatAPI(client) const recordMap = await compat.getPage('page-id') ``` -------------------------------- ### Environment Variables for Notion API and Configuration Source: https://github.com/notionx/react-notion-x/blob/master/_autodocs/configuration.md Example of environment variables for Notion API authentication, API URL, Node.js settings, and debugging. ```bash # Notion API Authentication NOTION_TOKEN= # API Configuration NOTION_API_URL=https://www.notion.so/api/v3 # Node.js NODE_ENV=production NODE_OPTIONS=--max-old-space-size=4096 # Debug DEBUG=notion:* ``` -------------------------------- ### Example Usage of groupBlockContent Source: https://github.com/notionx/react-notion-x/blob/master/_autodocs/api-reference/notion-utils.md An example demonstrating how to use the groupBlockContent function to group block IDs and retrieve specific block types. ```typescript import { groupBlockContent } from 'notion-utils' const grouped = groupBlockContent(contentIds, recordMap) const textBlocks = grouped.get('text') const images = grouped.get('image') ``` -------------------------------- ### Example: Custom Component Override Source: https://github.com/notionx/react-notion-x/blob/master/_autodocs/api-reference/react-notion-x.md Example demonstrating how to override default components in react-notion-x for custom rendering. ```typescript import { NotionRenderer } from 'react-notion-x' import SyntaxHighlighter from 'react-syntax-highlighter' ( {children} ), Equation: ({ latex }) => ( ), Image: ({ src, alt, ...props }) => ( {alt} ), Link: ({ href, children }) => ( {children} ), Tweet: ({ id }) => ( ) }} /> ``` -------------------------------- ### Block CSS Classes Example Source: https://github.com/notionx/react-notion-x/blob/master/_autodocs/api-reference/block-component.md Example of how CSS classes are generated for different block types. ```typescript .notion-${blockType} // e.g., .notion-image, .notion-code, .notion-text ``` -------------------------------- ### CLI Usage with URL Source: https://github.com/notionx/react-notion-x/blob/master/packages/notion-x-to-md/readme.md Example of using the notion-x-to-md CLI with a Notion page URL. ```bash npx -y notion-x-to-md https://notion.so/067dd719a912471ea9a3ac10710e7fdf ``` -------------------------------- ### Pattern 4: Custom Component Rendering Source: https://github.com/notionx/react-notion-x/blob/master/_autodocs/api-reference/packages-overview.md Example of customizing the rendering of Notion blocks with custom components like SyntaxHighlighter and KaTeX. ```typescript import { NotionRenderer } from 'react-notion-x' import SyntaxHighlighter from 'react-syntax-highlighter' ( {children} ), Equation: ({ latex }) => }} /> ``` -------------------------------- ### MapImageUrlFn Example Source: https://github.com/notionx/react-notion-x/blob/master/_autodocs/api-reference/react-notion-x.md Example implementation of the MapImageUrlFn to transform Notion S3 URLs or proxy images through a CDN. ```typescript const mapImageUrl = (url, block) => { if (!url) return undefined // Transform Notion S3 URLs if (url.includes('secure.notion-static.com')) { return `/api/image?url=${encodeURIComponent(url)}` } // Proxy all images through CDN return `https://cdn.example.com/image?url=${encodeURIComponent(url)}` } ``` -------------------------------- ### Invalid JavaScript Example Source: https://github.com/notionx/react-notion-x/blob/master/packages/notion-x-to-md/examples/0c322c33381c49bca5083a451c334c39.md An example labeled as 'Invalid JavaScript' which contains text that appears to be investor statistics. ```JavaScript **Participating** 216 investors 94% invest in pre-seed + seed 96% US-based investor 19% angels 81% venture capitalists 6 investments made via tool ``` -------------------------------- ### Header Component Override Example Source: https://github.com/notionx/react-notion-x/blob/master/_autodocs/api-reference/react-notion-x.md Example of overriding the built-in Header component for custom page navigation. ```typescript (
) }} /> ``` -------------------------------- ### Basic Usage Example Source: https://github.com/notionx/react-notion-x/blob/master/_autodocs/api-reference/notion-renderer.md An example demonstrating how to use the NotionRenderer component with NotionAPI to fetch and render a Notion page. ```typescript import { NotionRenderer } from 'react-notion-x' import { NotionAPI } from 'notion-client' const notion = new NotionAPI() const recordMap = await notion.getPage('d4d88c36f395471352b13ce9ada3be82') export function Page() { return ( `/pages/${pageId}`} mapImageUrl={(url, block) => { if (!url) return '' if (url.startsWith('http')) return url return `/images/${url}` }} /> ) } ``` -------------------------------- ### Usage Source: https://github.com/notionx/react-notion-x/blob/master/packages/notion-client/readme.md Example usage of the NotionAPI client to fetch page content and collection data. ```typescript import { NotionAPI } from 'notion-client' // you can optionally pass an authToken to access private notion resources const api = new NotionAPI() // fetch a page's content, including all async blocks, collection queries, and signed urls const page = await api.getPage('067dd719-a912-471e-a9a3-ac10710e7fdf') // fetch the data for a specific collection instance const collectionId = '2d8aec23-8281-4a94-9090-caaf823dd21a' const collectionViewId = 'ab639a5a-853e-45e1-9ef7-133b486c0acf' const collectionData = await api.getCollectionData( collectionId, collectionViewId ) ``` -------------------------------- ### Pattern 5: Custom Page/Image URL Mapping Source: https://github.com/notionx/react-notion-x/blob/master/_autodocs/api-reference/packages-overview.md Example of customizing how page URLs and image URLs are mapped within NotionRenderer. ```typescript { const slug = getPageTitle(recordMap).toLowerCase().replace(/\s+/g, '-') return `/docs/${slug}` }} mapImageUrl={(url, block) => { if (!url) return '' return `/api/proxy-image?url=${encodeURIComponent(url)}` }} /> ``` -------------------------------- ### Custom Code Block Example Source: https://github.com/notionx/react-notion-x/blob/master/_autodocs/api-reference/notion-renderer.md Example of customizing the Code and Equation block rendering using the components prop. ```typescript import { NotionRenderer } from 'react-notion-x' ( {children} ), Equation: ({ latex }) => }} /> ``` -------------------------------- ### Import CSS Styles Source: https://github.com/notionx/react-notion-x/blob/master/readme.md Example of importing necessary CSS styles for react-notion-x, prismjs, and katex in a Next.js application. ```typescript // core styles shared by all of react-notion-x (required) import 'react-notion-x/styles.css' // used for code syntax highlighting (optional) import 'prismjs/themes/prism-tomorrow.css' // used for rendering equations (optional) import 'katex/dist/katex.min.css' ``` -------------------------------- ### ComponentOverrideFn Example Source: https://github.com/notionx/react-notion-x/blob/master/_autodocs/api-reference/react-notion-x.md Example of using ComponentOverrideFn to customize the rendering of property values like dates and selects. ```typescript { // Customize how dates are rendered const defaultNode = defaultFn() return ( {defaultNode} ) }, propertySelectValue: (props, defaultFn) => { // Add badges around select values return ( {defaultFn()} ) } }} /> ``` -------------------------------- ### Type Mismatch Example Source: https://github.com/notionx/react-notion-x/blob/master/_autodocs/errors-and-troubleshooting.md Demonstrates the correct way to import and use types for props in TypeScript. ```typescript import type { Block, ExtendedRecordMap, Color } from 'notion-types' import type { NotionComponents, MapPageUrlFn } from 'react-notion-x' // ✓ Correct const mapPageUrl: MapPageUrlFn = (id) => `/page/${id}` // ✗ Incorrect const mapPageUrl = (id) => `/page/${id}` // missing type annotation ``` -------------------------------- ### Next.js Integration Example Source: https://github.com/notionx/react-notion-x/blob/master/_autodocs/api-reference/react-notion-x.md Special props for integrating Next.js Image and Link components. ```typescript ``` -------------------------------- ### CLI Usage with Page ID Source: https://github.com/notionx/react-notion-x/blob/master/packages/notion-x-to-md/readme.md Example of using the notion-x-to-md CLI with a Notion page ID. ```bash npx -y notion-x-to-md de14421f13914ac7b528fa2e31eb1455 ``` -------------------------------- ### Pattern 3: Extract Data and Convert to Markdown Source: https://github.com/notionx/react-notion-x/blob/master/_autodocs/api-reference/packages-overview.md Example showing how to extract page title and image URLs using notion-utils and convert the page to Markdown using notion-x-to-md. ```typescript import { NotionAPI } from 'notion-client' import { getPageTitle, getPageImageUrls } from 'notion-utils' import { notionPageToMarkdown } from 'notion-x-to-md' const api = new NotionAPI() const recordMap = await api.getPage('page-id') const title = getPageTitle(recordMap) const images = getPageImageUrls(recordMap) const markdown = await notionPageToMarkdown(recordMap) ``` -------------------------------- ### Usage Source: https://github.com/notionx/react-notion-x/blob/master/packages/notion-x-to-md/readme.md Example of using notion-x-to-md in a TypeScript project to convert a Notion page to Markdown. ```typescript import { NotionAPI } from 'notion-client' import { notionPageToMarkdown } from 'notion-x-to-md' const api = new NotionAPI() // fetch a notion page's content const page = await api.getPage('067dd719a912471ea9a3ac10710e7fdf') // convert the page to a markdown string const markdown = await notionPageToMarkdown(page) console.log(markdown) ``` -------------------------------- ### Provide component overrides Source: https://github.com/notionx/react-notion-x/blob/master/_autodocs/errors-and-troubleshooting.md Example of providing custom components for different block types. ```typescript ( {children} ), Equation: ({ latex }) => , Tweet: ({ id }) => , Pdf: ({ src }) => }} /> ``` -------------------------------- ### Authentication with Official Notion SDK Source: https://github.com/notionx/react-notion-x/blob/master/_autodocs/README.md Example of using the notion-compat adapter with the official Notion SDK. ```typescript import { NotionCompatAPI } from 'notion-compat' const compat = new NotionCompatAPI(official_client) ``` -------------------------------- ### Advanced: ofetchOptions for HTTP Client Configuration Source: https://github.com/notionx/react-notion-x/blob/master/_autodocs/configuration.md Example of passing additional HTTP client options like timeout, retry, headers, and cache settings. ```typescript new NotionAPI({ ofetchOptions: { timeout: 60000, // 60 second timeout retry: 3, // retry up to 3 times headers: { 'User-Agent': 'MyBot/1.0', 'X-Custom-Header': 'value' }, cache: 'no-cache' } }) ``` -------------------------------- ### Fetch Notion Page Data Source: https://github.com/notionx/react-notion-x/blob/master/readme.md Example of fetching data for a Notion page using the NotionAPI. ```typescript import { NotionAPI } from 'notion-client' const notion = new NotionAPI() const recordMap = await notion.getPage('067dd719a912471ea9a3ac10710e7fdf') ``` -------------------------------- ### Table of Contents Configuration Source: https://github.com/notionx/react-notion-x/blob/master/_autodocs/errors-and-troubleshooting.md Example of how to configure the `showTableOfContents` and `minTableOfContentsItems` props for the NotionRenderer. ```typescript ``` -------------------------------- ### Error Handling Example Source: https://github.com/notionx/react-notion-x/blob/master/_autodocs/README.md Demonstrates a try-catch block for handling common errors when fetching Notion pages. ```typescript try { const recordMap = await api.getPage(pageId) } catch (error) { if (error.message.includes('invalid notion pageId')) { // Invalid page ID format } else if (error.message.includes('Notion page not found')) { // Page doesn't exist or not accessible } else { // Network or API error } } ``` -------------------------------- ### Fetch missing blocks Source: https://github.com/notionx/react-notion-x/blob/master/_autodocs/errors-and-troubleshooting.md Example of ensuring missing blocks are fetched by setting fetchMissingBlocks to true. ```typescript const recordMap = await api.getPage(pageId, { fetchMissingBlocks: true }) ``` -------------------------------- ### Usage Example Source: https://github.com/notionx/react-notion-x/blob/master/packages/notion-utils/readme.md Demonstrates how to use the parsePageId function from notion-utils to extract Notion page IDs from various URL formats. ```typescript import { parsePageId } from 'notion-utils' parsePageId( 'https://www.notion.so/Notion-Tests-067dd719a912471ea9a3ac10710e7fdf' ) // '067dd719-a912-471e-a9a3-ac10710e7fdf' parsePageId('About-d9ae0c6e7cad49a78e21d240cf2e3d04') // 'd9ae0c6e-7cad-49a7-8e21-d240cf2e3d04' parsePageId('About-d9ae0c6e7cad49a78e21d240cf2e3d04', { uuid: false }) // 'd9ae0c6e7cad49a78e21d240cf2e3d04' ``` -------------------------------- ### Authentication with token_v2 cookie Source: https://github.com/notionx/react-notion-x/blob/master/_autodocs/README.md Example of authenticating the NotionAPI client using a token_v2 cookie. ```typescript const api = new NotionAPI({ authToken: process.env.NOTION_TOKEN }) ``` -------------------------------- ### Render Notion Page with React Source: https://github.com/notionx/react-notion-x/blob/master/readme.md Example of rendering fetched Notion page data using NotionRenderer. ```tsx import React from 'react' import { NotionRenderer } from 'react-notion-x' export default ({ recordMap }) => ( ) ``` -------------------------------- ### Reduce fetch scope for large pages Source: https://github.com/notionx/react-notion-x/blob/master/_autodocs/errors-and-troubleshooting.md Example of reducing the fetch scope by disabling certain options. ```typescript await api.getPage(pageId, { fetchCollections: false, // skip collections fetchMissingBlocks: false, // skip extra blocks signFileUrls: false // skip file signing }) ``` -------------------------------- ### Use lower concurrency for network requests Source: https://github.com/notionx/react-notion-x/blob/master/_autodocs/errors-and-troubleshooting.md Example of using lower concurrency for fetching page data. ```typescript await api.getPage(pageId, { concurrency: 1 // sequential requests }) ``` -------------------------------- ### Ensure unique block IDs in lists Source: https://github.com/notionx/react-notion-x/blob/master/_autodocs/errors-and-troubleshooting.md Example demonstrating the correct way to map blocks to unique keys. ```typescript // ✓ Correct {blocks.map(block => ( ))} // ✗ Incorrect {blocks.map((block, i) => ( ))} ``` -------------------------------- ### Notion Page Metadata (JSON) Source: https://github.com/notionx/react-notion-x/blob/master/packages/notion-x-to-md/examples/0c322c33381c49bca5083a451c334c39.md Example JSON object representing page metadata like icon, cover, and cover position. ```JSON { "page_icon": "🔥", "page_cover": "https://images.unsplash.com/photo-1532386236358-a33d8a9434e3?ixlib=rb-1.2.1&q=85&fm=jpg&crop=entropy&cs=srgb", "page_cover_position": 0.5 } ``` -------------------------------- ### CLI Help Source: https://github.com/notionx/react-notion-x/blob/master/packages/notion-x-to-md/readme.md Help information for the notion-x-to-md CLI. ```bash Usage: notion-x-to-md [options] Converts a Notion page to Markdown Arguments: page Notion page ID or URL (must be publicly accessible) Options: -h, --help display help for command ``` -------------------------------- ### Pattern 1: Fetch and Render a Page Source: https://github.com/notionx/react-notion-x/blob/master/_autodocs/api-reference/packages-overview.md Common usage pattern for fetching a Notion page using NotionAPI and rendering it with NotionRenderer. ```typescript import { NotionAPI } from 'notion-client' import { NotionRenderer } from 'react-notion-x' import 'react-notion-x/styles.css' const api = new NotionAPI() const recordMap = await api.getPage('page-id') export function Page() { return } ``` -------------------------------- ### NotionAPI Constructor Options Source: https://github.com/notionx/react-notion-x/blob/master/_autodocs/configuration.md The NotionAPI client accepts configuration options during initialization. ```typescript new NotionAPI({ apiBaseUrl?: string authToken?: string activeUser?: string userTimeZone?: string ofetchOptions?: OfetchOptions }) ``` -------------------------------- ### Performance Tuning for Server-Side Rendering (SSR) Source: https://github.com/notionx/react-notion-x/blob/master/_autodocs/configuration.md Recommended configuration for `api.getPage` when performing server-side rendering. ```typescript const recordMap = await api.getPage(pageId, { concurrency: 10, // higher concurrency safe on server fetchCollections: true, // preload all data signFileUrls: true, // sign files upfront fetchMissingBlocks: true // ensure complete data }) ``` -------------------------------- ### Performance Tuning for Static Generation Source: https://github.com/notionx/react-notion-x/blob/master/_autodocs/configuration.md Recommended configuration for `api.getPage` when performing static generation. ```typescript const recordMap = await api.getPage(pageId, { concurrency: 15, // maximize throughput chunkLimit: 200, // larger chunks fetchCollections: true, signFileUrls: true, fetchRelationPages: true // include all related content }) ``` -------------------------------- ### getListStyle Source: https://github.com/notionx/react-notion-x/blob/master/_autodocs/api-reference/notion-utils.md Gets the style of a list block. ```typescript function getListStyle(block: Block, recordMap: ExtendedRecordMap): 'ordered' | 'unordered' | null ``` -------------------------------- ### Example Block Object: Text Type Source: https://github.com/notionx/react-notion-x/blob/master/packages/notion-client/readme.md This JSON object demonstrates the structure of a block object when its type is 'text'. It includes properties like id, version, type, properties, format, and timestamps. ```json { role: 'reader', value: { id: '0377e1a4-dc3d-4daf-99dd-f54f986d932e', version: 1, type: 'text', properties: { title: [Array] }, format: { copied_from_pointer: [Object] }, created_time: 1655961814278, last_edited_time: 1655961814278, parent_id: '08d5ba1e-03d2-4d4a-add7-a414f297ff8a', parent_table: 'block', alive: true, copied_from: '526d2008-0d0b-46f8-9de1-7411a85bff7b', created_by_table: 'notion_user', created_by_id: '55b29a2b-a8fe-4a11-9f9d-ada341bd922b', last_edited_by_table: 'notion_user', last_edited_by_id: '55b29a2b-a8fe-4a11-9f9d-ada341bd922b', space_id: '6b70425f-211e-4318-80c6-5d093df8f7eb' } } ``` -------------------------------- ### getListNumber Source: https://github.com/notionx/react-notion-x/blob/master/_autodocs/api-reference/notion-utils.md Gets the list item number for numbered lists. ```typescript function getListNumber(block: Block, recordMap: ExtendedRecordMap): number ``` -------------------------------- ### getListNestingLevel Source: https://github.com/notionx/react-notion-x/blob/master/_autodocs/api-reference/notion-utils.md Gets the nesting level of a list item block. ```typescript function getListNestingLevel(block: Block, recordMap: ExtendedRecordMap): number ``` -------------------------------- ### getPageBreadcrumbs Source: https://github.com/notionx/react-notion-x/blob/master/_autodocs/api-reference/notion-utils.md Gets the breadcrumb trail from root to a specific page. ```typescript function getPageBreadcrumbs( pageId: string, recordMap: ExtendedRecordMap ): Array<{ id: string; title: string | null }> ``` -------------------------------- ### getBlockIcon Source: https://github.com/notionx/react-notion-x/blob/master/_autodocs/api-reference/notion-utils.md Gets the icon (emoji or image URL) for a block. ```typescript function getBlockIcon(block: Block, recordMap: ExtendedRecordMap): string | null ``` ```typescript import { getBlockIcon } from 'notion-utils' const icon = getBlockIcon(block, recordMap) // "📝" ``` -------------------------------- ### getBlockCollectionId Source: https://github.com/notionx/react-notion-x/blob/master/_autodocs/api-reference/notion-utils.md Gets the collection ID for a collection_view or collection_view_page block. ```typescript function getBlockCollectionId( block: Block, recordMap: ExtendedRecordMap ): string | undefined ``` -------------------------------- ### Get Collection Data Source: https://github.com/notionx/react-notion-x/blob/master/_autodocs/README.md Fetches data for a Notion collection. ```typescript const data = await api.getCollectionData(collectionId, viewId) ``` -------------------------------- ### Performance Tuning for Client-Side Rendering (CSR) Source: https://github.com/notionx/react-notion-x/blob/master/_autodocs/configuration.md Recommended configuration for `api.getPage` when performing client-side rendering. ```typescript const recordMap = await api.getPage(pageId, { concurrency: 3, // respect browser limits fetchCollections: false, // load on demand signFileUrls: false, // sign files on demand fetchMissingBlocks: false // load on demand }) ``` -------------------------------- ### Optimizing Fetching for Performance Source: https://github.com/notionx/react-notion-x/blob/master/_autodocs/errors-and-troubleshooting.md Demonstrates how to optimize data fetching by adjusting parameters in the `api.getPage` call. ```typescript const recordMap = await api.getPage(pageId, { concurrency: 1, // reduce concurrent requests fetchCollections: false, // skip collections if not needed fetchMissingBlocks: false, signFileUrls: false }) ``` -------------------------------- ### BulletedListBlock / NumberedListBlock Source: https://github.com/notionx/react-notion-x/blob/master/_autodocs/types.md List items with optional starting number for numbered lists. ```typescript interface BulletedListBlock extends BaseTextBlock { type: 'bulleted_list' } interface NumberedListBlock extends BaseTextBlock { type: 'numbered_list' format?: { list_start_index?: number } } ``` -------------------------------- ### Example Block Object: Page Type Source: https://github.com/notionx/react-notion-x/blob/master/packages/notion-client/readme.md This JSON object shows the structure of a block object when its type is 'page'. It includes properties like id, version, type, content array, timestamps, and parent information. ```json { role: 'reader', value: { id: 'af961803-cd0c-470e-bd27-1d025baa2f95', version: 31, type: 'page', properties: { '==~K': [Array], 'BN]P': [Array], title: [Array] }, content: [ '8cbf7053-da37-4d69-8cde-89343baf3623', '0fc1712e-852c-4307-b72b-094dadaa86ba' ], created_time: 1655962200000, last_edited_time: 1655979420000, parent_id: '175482e5-870d-4da8-980c-ead469427316', parent_table: 'collection', alive: true, created_by_table: 'notion_user', created_by_id: '55b29a2b-a8fe-4a11-9f9d-ada341bd922b', last_edited_by_table: 'notion_user', last_edited_by_id: '55b29a2b-a8fe-4a11-9f9d-ada341bd922b', space_id: '6b70425f-211e-4318-80c6-5d093df8f7eb' } } ``` -------------------------------- ### Handling Invalid Page IDs Source: https://github.com/notionx/react-notion-x/blob/master/_autodocs/errors-and-troubleshooting.md Example of how to use `parsePageId` and check for invalid input. ```typescript import { parsePageId } from 'notion-utils' const id = parsePageId(input) if (!id) { console.error('Invalid page ID:', input) } ``` -------------------------------- ### Increase timeout for network requests Source: https://github.com/notionx/react-notion-x/blob/master/_autodocs/errors-and-troubleshooting.md Example of increasing the request timeout using ofetchOptions. ```typescript const api = new NotionAPI({ ofetchOptions: { timeout: 60000 // 60 seconds } }) ``` -------------------------------- ### Importing Types Source: https://github.com/notionx/react-notion-x/blob/master/_autodocs/README.md Example of importing TypeScript types for Notion data structures and components. ```typescript import type { Block, ExtendedRecordMap, Color, PropertyType } from 'notion-types' import type { NotionComponents, MapPageUrlFn } from 'react-notion-x' ```