How notion-to-md Converts Notion Databases, Properties, and Comments

notion-to-md handles these three content types through separate, configurable mechanisms: databases are rendered by a dedicated database renderer that maps each Notion property type to an output format, page properties can be transformed into Markdown frontmatter, and Notion comments can be converted into Markdown footnotes. All three are part of the library's plugin and transformer system, so the default behavior can be adjusted or replaced. The details below apply to the v4 line of the library as described in its documentation.

How databases are rendered

When the converter encounters a Notion database block, it does not flatten it into plain text. Instead, a database renderer walks the database's schema and rows and produces output based on the property types it finds. The documentation lists "How to Modify Notion Database Rendering" as a dedicated guide, which confirms that database output is a first-class, customizable concern rather than a fixed string.

The practical implication: the shape of your database output depends on which property types your database uses and how the renderer is configured. If a property type is not handled the way you want, the documented path is to modify the renderer rather than post-process the Markdown.

Property transformers

Property transformers are the layer that decides how an individual property value becomes output. They sit alongside the other transformer categories the library exposes:

• Block transformers — change how a block is rendered.
• Annotation transformers — change how inline formatting (bold, italic, links, and similar) is rendered.
• Database property transformers — change how a database property value is rendered.
• Frontmatter transformers — change how page properties become frontmatter.

Because property transformers are a named concept in the docs, the intended workflow is to register or override a transformer for the property types you care about, instead of rewriting the whole database renderer.

Converting properties to frontmatter

Page properties (the fields at the top of a Notion page) can be emitted as Markdown frontmatter — the YAML-style block between --- delimiters at the top of a file that static site generators read. The library documents this as "How to Convert Notion Properties to Frontmatter with notion-to-md v4," and frontmatter transformers are the mechanism that controls the mapping.

A concrete scenario: you keep a blog post in Notion with properties for title, slug, publish date, and tags, and you build with a static site generator that reads frontmatter. Rather than manually copying those fields, you let the frontmatter transformer map each Notion property to a frontmatter key. The expected result is a Markdown file whose frontmatter block carries those values, ready for the generator to consume.

Two things to verify in your own setup:

1. Property type coverage — confirm each property type you use (date, multi-select, relation, and so on) has a transformer that produces the value format your generator expects.
2. Key naming — frontmatter keys must match what your site generator reads; the transformer is where you align them.

Turning comments into footnotes

Notion comments are page-level discussion, not part of the page body, so converting them requires an explicit decision about where they land. The library documents "How to Convert Notion Comments to Markdown Footnotes with notion-to-md v4," meaning comments can be emitted as Markdown footnote syntax rather than inline text.

The useful mental model: each comment becomes a footnote reference in the body with the comment content collected at the bottom of the document. This keeps the main text clean while preserving the discussion. As with the other features, check the documented guide for the exact configuration, since comment retrieval depends on the Notion API returning comments for the page and on how you want multiple comments ordered.

Choosing what to enable

If you only need body content as Markdown, none of these need configuring. Enable them when your pipeline depends on metadata, structured database output, or preserved discussion — and treat each as a separate switch rather than assuming one setting covers all three.