Custom NotionCMS Block Renderers

By default NotionCMS will transform each block in your Notion page into HTML. The resulting HTML is reasonablly generic and is suitable for most projects. However, you may want a greater level of control when it comes to how each Notion block gets used in your project. That’s where the ncms-block-render-plugin comes in!

🧑‍🚀

Tip: This plugin is special in a number of ways! It comes with NotionCMS out of the box and grants you access to lower level, granular block transformations.

NotionCMS ships with a custom block rendering plugin that lets you create your own definitions for how each Notion block should be rendered. This will result in statically rendered HTML for each block and isn’t the best place for reactive components, though you could definitely use a reactive libraries’ SSR toolkit to render intricate components based on the Notion blocks state. This is the kind of power NotionCMS grants you!

🧑🏾‍🚀

Tip: You may be tempted to use this plugin in places where it’s perhaps not the best option. Make sure you have a good understanding of how plugins work by reading through the plugins documentation.

import NotionCMS, { blockRenderPlugin } from '@agency-kit/notion-cms'

const testNCMS = new NotionCMS({
  databaseId,
  notionAPIKey,
  plugins: [
    blocksRenderPlugin({
      blockRenderers: {
        CalloutBlock: (block) => {
                    // Make callouts stand out as h1s (don't do this!)
          return `<h1 class="callout><p>${parseRichText(block.callout.rich_text)}</p>
</h1>`
        },
        QuoteBlock: (block) => {
                    // totally replace all your quote blocks with this nice poem.
          return `<div class="blockquote"><p>QUOTH THE RAVEN NEVERMORE</p>
</div>`
        }
      }
    })
  ]
})

await testNCMS.fetch()

Blocks

There are many Notion blocks for you to apply a custom render function to. Here is a list of them and a few helpful notes on the useful values you can extract from each for use in your renderer.

Audio block

The Audio block, when rendered, will display an audio player that can be used to play an audio file.

👽

Tip: It’s recommended that you end your component html template literal with a few newlines like this: ‘\n\n’. This will make sure that no markdown elements get confused for plain text which sometimes happens when they immediately follow a line.

BulletedListItemBlock

The BulletedListItemBlock represents a bulleted list item within a bulleted list block. It contains a RichText object representing the text of the list item. Additionally, it may contain child blocks.

CalloutBlock

🧑‍🏭

Trick: Want to leave non-comment notes in your Notion pages without them getting used in your website? Something like this will do the trick:

plugins: [
    blocksRenderPlugin({
      blockRenderers: {
        // Eliminate callouts from your content!
              // Don't use null here.
                // See `Fallback to Default Block Renderers using null` below.
        CalloutBlock: (block) => '',
     }
    })
]

CodeBlock

EmbedBlock

FileBlock

Sample Block Data

"heading_1": {
                "rich_text": [
                    {
                        "type": "text",
                        "text": {
                            "content": "Kitchen Sink",
                            "link": null
                        },
                        "annotations": {
                            "bold": false,
                            "italic": false,
                            "strikethrough": false,
                            "underline": false,
                            "code": false,
                            "color": "default"
                        },
                        "plain_text": "Kitchen Sink",
                        "href": null
                    }
                ],
                "is_toggleable": false,
                "color": "default"
            }]
    }

HeadingBlock

Sample Block Data

"heading_1": {
                "rich_text": [
                    {
                        "type": "text",
                        "text": {
                            "content": "Kitchen Sink",
                            "link": null
                        },
                        "annotations": {
                            "bold": false,
                            "italic": false,
                            "strikethrough": false,
                            "underline": false,
                            "code": false,
                            "color": "default"
                        },
                        "plain_text": "Kitchen Sink",
                        "href": null
                    }
                ],
                "is_toggleable": false,
                "color": "default"
            }]
    }

### ImageBlock

NumberedListItemBlock

ParagraphBlock

PDFBlock

QuoteBlock

RichText

💀

Warning: This renderer is used in many of the internal workings of the other renderers - anywhere Rich text would be rendered. Make changes to this renderer with caution!

ToDoBlock

ToggleBlock

VideoBlock

Fallback to Default Block Renderers using `null`

If you want to render some block with your custom renderer conditionally, but are fine with using the defaults for other cases, you can simply return null anywhere inside your renderer and the default will be used. This way you don’t have to write your own default renderer you can just use the default NotionCMS renderer.