Vue Notion Renderer

Common errors

• Failed to resolve component: NotionRenderer

  cause The `NotionRenderer` component was not correctly imported or registered within your Vue application.
  fix Ensure you have `import { NotionRenderer } from 'vue-notion';` in your script, and it's either globally registered or registered in the `components` option of the parent component, e.g., `{ components: { NotionRenderer } }`.

• TypeError: Cannot read properties of undefined (reading 'call') at Proxy.render (webpack-internal:///./node_modules/@janniks/vue3-katex/dist/index.js)

  cause This error often indicates that the `@janniks/vue3-katex` library, a peer dependency, is missing or its styles are not loaded, leading to issues when `vue-notion` attempts to render Notion equation blocks.
  fix Install `@janniks/vue3-katex` (`npm install @janniks/vue3-katex`) and add `import '@janniks/vue3-katex/dist/katex.min.css';` to your main application entry point (e.g., `main.js` or `App.vue`'s `<script setup>` or `<style>`).

Warnings

• breaking Version `3.0.0` represents a major version update. While specific API breaking changes are not detailed in the provided release notes, major releases typically include significant internal refactoring, potential API changes, or drops in support for older Vue.js versions or environments. Always perform thorough testing when upgrading from `1.x` to `3.x`.
  Fix: Review the official `vue-notion` documentation and GitHub changelog for detailed migration guides specific to 3.0.0. Test your application extensively after upgrading.
• gotcha The package has a peer dependency on `@janniks/vue3-katex` for rendering mathematical equations. If `@janniks/vue3-katex` is not installed, or its required CSS (`@janniks/vue3-katex/dist/katex.min.css`) is not imported, Notion equation blocks will not render correctly and may lead to console errors.
  Fix: Install `@janniks/vue3-katex` via npm or yarn (`npm install @janniks/vue3-katex`) and ensure `import '@janniks/vue3-katex/dist/katex.min.css';` is included in your main application entry file or a global stylesheet.
• gotcha Early versions of `vue-notion` (prior to `1.5.0`) contained a bug related to the `??` (nullish coalescing) operator, which could cause runtime errors in environments that do not fully support ES2020 features. This was fixed in `1.5.0`.
  Fix: Upgrade to `vue-notion@^1.5.0` or `vue-notion@^3.0.0` to resolve issues related to the nullish coalescing operator.
• gotcha Custom component support via the `blockOverrides` setting was introduced in version `1.4.2`. If you intend to override default Notion block rendering with your own Vue components, you must be on this version or newer.
  Fix: Ensure your `vue-notion` version is `^1.4.2` or later to utilize the `blockOverrides` functionality for custom block rendering.

Install

• npm install vue-notion npm
• yarn add vue-notion yarn
• pnpm add vue-notion pnpm

Imports

• NotionRenderer
  wrong:

  const NotionRenderer = require('vue-notion')

  correct:

  import { NotionRenderer } from 'vue-notion'

  The library primarily uses named exports and is designed for ESM environments with Vue 3. CommonJS `require` syntax is not supported for modern Vue 3 usage.

Quickstart

Demonstrates how to import and use the `NotionRenderer` component with mock Notion block data. It includes necessary CSS for KaTeX and sets up a basic Vue 3 application to display rendered content, highlighting various block types including code and equations.

import { createApp, defineComponent, h } from 'vue';
import { NotionRenderer } from 'vue-notion';
import '@janniks/vue3-katex/dist/katex.min.css'; // Essential for math rendering

// Mock Notion block data (in a real app, this would come from Notion API)
const mockNotionBlocks = [
  { id: '1', type: 'paragraph', paragraph: { rich_text: [{ type: 'text', text: { content: 'Welcome to your Notion page rendered in Vue!' } }] } },
  { id: '2', type: 'heading_2', heading_2: { rich_text: [{ type: 'text', text: { content: 'Key Features:' } }] } },
  { id: '3', type: 'bulleted_list_item', bulleted_list_item: { rich_text: [{ type: 'text', text: { content: 'Render various block types (paragraphs, headings, lists)' } }] } },
  { id: '4', type: 'bulleted_list_item', bulleted_list_item: { rich_text: [{ type: 'text', text: { content: 'Support for images and code blocks' } }] } },
  { id: '5', type: 'code', code: { rich_text: [{ type: 'text', text: { content: 'function hello() { console.log("Vue-Notion"); }' } }], language: 'javascript' } },
  { id: '6', type: 'equation', equation: { expression: 'x = \frac{-b \pm \sqrt{b^2-4ac}}{2a}' } },
  { id: '7', type: 'image', image: { type: 'external', external: { url: 'https://picsum.photos/id/237/200/100' } } },
  { id: '8', type: 'paragraph', paragraph: { rich_text: [{ type: 'text', text: { content: 'Remember to fetch actual Notion data from their API and pass it to the renderer.' } }] } }
];

const App = defineComponent({
  components: { NotionRenderer },
  data() {
    return {
      notionPageBlocks: mockNotionBlocks
    };
  },
  template: `
    <div id="app" style="font-family: sans-serif; max-width: 800px; margin: 0 auto; padding: 20px;">
      <h1>My Notioned Blog Post</h1>
      <NotionRenderer :blockMap="notionPageBlocks" fullPage />
    </div>
  `,
});

createApp(App).mount('#app');