Hey there 👋

I wanted to share how I made a small Go package called https://github.com/brittonhayes/notionmd that converts markdown into Notion blocks.

The problem

Why am I doing this? Do I just love abstract syntax trees? Sorta, but that's not the reason. Here’s the issue: I receive vulnerability findings and reports from security researchers in markdown format. This is great because markdown is wonderful, simple, and ubiquitous!

This is less great because I want to organize these reports in Notion automatically but the Notion API expects blocks not markdown.

<aside> 💡 I want something that converts all this markdown into beautifully formatted Notion pages automatically.

</aside>

What do I want the solution to feel like?

The ideal experience for this is that I could pass in whatever markdown I want into a single function and magically get a bunch of Notion blocks back.

I shouldn’t have to know what an abstract syntax tree is or even what each of the block types are. I just want a tidy workspace of nicely formatted security findings in Notion ✨

Neat, let’s build it

So with a rough idea of the experience I’m looking for, let’s get a little more specific on how we can get from A → B.

  1. Input Markdown content.
  2. Parse markdown into a tree of markdown nodes (I’ll explain this in a second).
  3. Split long documents into smaller chunks
  4. Convert each node in the tree to its corresponding Notion block.
  5. Output an array of Notion blocks for use with the Notion API.

What on earth is an abstract syntax tree?

For the purposes of our problem statement, it’s a way to derive meaning from the syntax of our markdown documents. We use the derived meaning to match the corresponding markdown element to Notion’s blocks. Let me show you just how the two sources depict the same thing.

Heading - Markdown