notionconvert.com

Notion To MD is a free, open-source Node.js library that fetches Notion pages and converts them into Markdown, HTML, plain text, or custom formats. It is built for developers who want to pull Notion content into a website, CMS, static site generator, or automated publishing pipeline — not for people looking for a click-to-export browser tool. If you need a one-off manual export, this is more machinery than you need; if you need repeatable, programmatic conversion inside a Node.js project, it fits.

What it actually does

The library handles two jobs: retrieving page content from Notion and transforming it into output you can use elsewhere. The site describes it as "a flexible Node.js library to fetch and transform Notion pages into Markdown, HTML, or custom formats via a powerful plugin system."

Concretely, that means:

• Block conversion — parses and converts a wide range of Notion blocks, including text, lists, images, code blocks, callouts, and databases.
• Media handling — strategies to download, upload, or buffer Notion images and files, with links updated automatically and cleanup managed for you.
• Output flexibility — Markdown is the default framing, but HTML, plain text, and fully custom formats are supported through plugins.

The plugin system is the core design

Rather than a fixed converter with a few options, Notion To MD exposes several extension points. The documentation lists these concept areas:

The site also maintains catalogues of media strategies, exporter plugins, and renderer plugins, plus guides such as creating a renderer plugin from scratch or modifying an existing one. This matters for evaluation: if your target format is unusual, the question is whether an existing plugin covers it or whether you (or your team) are prepared to write one.

Where it fits in a workflow

The intended pattern is a build step or backend job: your Node.js code calls the library, receives converted content, and passes it to a destination. The site names static site generators (Next.js, Hugo, Eleventy), CMS platforms (WordPress, Webflow), documentation platforms, and databases as integration targets, and describes automating publishing workflows so Notion content flows to multiple destinations.

A typical use case looks like this: a team drafts documentation in Notion, and a scheduled Node.js script converts the relevant pages to Markdown and commits them to a docs repository. The library's media handling is what makes this practical — images referenced in Notion need to end up somewhere your published site can serve them, and the download/upload strategies address that.

Who should use it — and who shouldn't

Reasonable fit if you:

• Are comfortable in Node.js and can install and configure a library.
• Need conversion to run repeatedly or automatically, not once.
• Want control over output format, media behavior, or frontmatter.
• Are integrating Notion content into an existing site or pipeline.

Look elsewhere if you:

• Want a hosted converter or a browser-based export button.
• Need a no-code solution.
• Only need to export a page or two by hand.

Practical caveats

The site presents the project as free and open-source, and the documentation is versioned (v4 is current, with v3 material and a changelog also available). Two things worth checking before committing: the repository's activity signals on the site are minimal (the page shows 0 stars and 0 forks alongside "used by 11.2k repos"), so verify current maintenance status on the linked GitHub repository; and the site does not publish pricing or account requirements, so treat access and hosting details as unconfirmed until you check the repository and docs directly.

The fastest way to judge fit is to read the Getting Started and Concepts sections of the documentation, then try converting one real page with your intended output format before designing a pipeline around it.

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.

Yes. notion-to-md is a Node.js library that fetches Notion pages and transforms them into Markdown, HTML, plain text, or fully custom output, and it is designed to plug into a CMS backend or a static site build. The condition is that you work in a Node.js environment and are willing to configure the plugin system — the default path produces Markdown, while other formats and destinations come from renderer and exporter plugins.

What the library actually does

notionconvert.com describes notion-to-md as "a flexible Node.js library to fetch and transform Notion pages into Markdown, HTML, or custom formats via a powerful plugin system." It is free and open-source. The site lists these capabilities:

• Customizable output formats — the extensible plugin system allows transformation to Markdown, HTML, plain text, or completely custom output formats.
• Integration with any system — the architecture allows integration with any CMS (WordPress, Webflow, etc.) or backend by handling content conversion and media processing.
• Automation — build pipelines that publish Notion content to static sites, documentation platforms, or databases.
• Node.js ecosystem fit — integrates into Node.js build processes and static site generators such as Next.js, Hugo, and Eleventy.

How non-Markdown output is produced

Output format is not a single switch; it is determined by which renderer and exporter plugins you use. The documentation's Concepts section separates Exporter Plugins from Renderer Plugins, alongside configuration, media handling, page references, context variables and templates, block transformers, annotation transformers, database property transformers, and frontmatter transformers. In practice:

The docs also include a plugin catalogue with separate media strategy, exporter, and renderer catalogues, plus a guide on creating a renderer plugin from scratch and one on modifying an existing renderer plugin. Those are the pages to read before committing to a custom format.

Integration paths, by destination

• Static site generators (Next.js, Hugo, Eleventy): run the conversion as part of the Node.js build process, then let the generator consume the resulting files.
• CMS backends (WordPress, Webflow, or others): use an exporter plugin to hand converted content to the CMS or your own backend, rather than writing files by hand.
• Databases or documentation platforms: the site explicitly frames automated pipelines for publishing to "multiple destinations like static sites, documentation platforms, or databases."

Media and links are part of the conversion

If your pages contain images or files, format choice is not the only decision. notion-to-md offers media handling strategies to "download, upload, or buffer Notion images and files, automatically updating links and managing cleanup." The blog includes a post on mastering media handling in v4 covering download, upload, and direct strategies, and a media strategy catalogue. Pick a strategy that matches where the output will live — a CMS that hosts its own assets needs different handling than a static build that copies files locally.

What to check before you rely on it

1. Version. The documentation is labeled v4 (with a v4-0-0-alpha.5 changelog entry) and there is also a v3 section. Plugin APIs and configuration differ between major versions, so match guides to the version you install.
2. Block coverage. The site states it parses and converts a wide range of Notion blocks including text, lists, images, code blocks, callouts, and databases. If your pages use unusual blocks, verify them against the block transformer documentation.
3. Custom format effort. HTML and plain text are presented as plugin-driven outcomes, not built-in toggles. Budget time for the "create renderer plugin from scratch" guide if your target format is not covered by an existing catalogue entry.
4. Setup and authentication. The site's Getting Started section is the entry point for installation and fetching pages; it does not publish pricing or login terms, so treat access requirements as something to confirm there rather than assume.

For a first test, convert one representative page to Markdown, then swap in a renderer plugin and an exporter plugin to confirm the same page reaches your CMS or static build intact — including images — before scaling to a full site.

notion-to-md (notionconvert.com) is a free, open-source Node.js library that fetches Notion pages and converts them into Markdown, HTML, or custom formats. To get started, you need a Node.js project, a Notion integration token with access to the target page, and the page's ID. Install the library, initialize it with the Notion client, then call the conversion method on a page ID and write the resulting Markdown to a file or pass it to your build pipeline.

What you need before you start

• A Node.js project — the library is designed for Node.js and integrates with build processes, static site generators (Next.js, Hugo, Eleventy), or any backend application.
• A Notion integration token — created in Notion and given access to the page(s) you want to convert.
• The Notion page ID — the page you intend to export.
• A place to send the output — a file, a CMS, a static site, or a database, depending on your workflow.

The library is described as free and open-source on its site. The documentation does not state pricing or login requirements beyond what Notion itself requires for API access, so treat Notion-side access setup as a prerequisite rather than something the library handles for you.

Step 1: Install the library in your Node.js project

Add notion-to-md to your project's dependencies using your package manager, then confirm it resolves in your package.json. The site presents the library as a standard Node.js package, so installation follows the usual dependency workflow for your project. If you are unsure which version to target, check the Changelog section of the documentation — the site documents a v4 line (including pre-release versions such as v4-0-0-alpha.5) alongside v3 material.

Step 2: Connect to Notion and initialize the converter

The library works by fetching Notion pages through the official Notion client and then transforming the returned blocks. In practice, your setup has three inputs:

1. Your integration token, used to authenticate the Notion client.
2. The page ID, identifying which page to fetch.
3. Conversion options, such as output format and media handling, passed through the library's configuration.

The site describes an "intuitive API" with deep control available through configuration and plugins. The exact function signatures and option names are version-specific, so follow the Getting Started page in the documentation for your installed version rather than copying snippets from blog posts that may target an older release.

Step 3: Run the conversion and handle the output

Once initialized, you invoke the conversion on a page ID. The expected result is a Markdown representation of the page's blocks — text, lists, images, code blocks, callouts, databases, and more are parsed and converted. From there you decide where the output goes:

• Write to a file for a static site generator or documentation platform.
• Feed a CMS or backend such as WordPress or Webflow, which the site lists as integration targets.
• Insert into a database or publishing pipeline as part of an automated workflow.

A useful way to think about it: the library handles content conversion and media processing, while your code decides the destination. That separation is what makes automated publishing workflows possible — you can run the same conversion step and route the result to multiple destinations.

Step 4: Verify the result

Check that the generated Markdown preserves the structures you care about: headings, nested lists, code blocks, and links. If your pages contain images or files, confirm the media links resolve correctly — the library offers download, upload, and buffer strategies for Notion media, and the chosen strategy determines whether links are rewritten and how cleanup is handled. The blog post "Mastering Media Handling in notion-to-md v4" covers these strategies in detail.

Common sticking points

• Page access errors usually mean the Notion integration was not granted access to that specific page.
• Missing or broken media links point to a media strategy that doesn't match your hosting setup; review the media strategy catalogue.
• Unexpected output structure often comes from version differences — v4 introduced changes to rendering, frontmatter, and plugin behavior compared with v3.
• Custom formats require the plugin system rather than default settings; the documentation includes guides on modifying existing renderer plugins and building one from scratch.

Where to find the documentation and guides

The site's Documentation section is the primary reference. It includes:

• Getting Started — the entry point for installation and first conversion.
• Guides — modifying renderer plugins, handling blocks with children, creating renderer plugins from scratch, using the page reference utility, and modifying Notion database rendering.
• Concepts — configuration, media handling, page references, exporter plugins, renderer plugins, context variables and templates, block transformers, annotation transformers, database property transformers, and frontmatter transformers.
• Catalogues — media strategies, exporter plugins, and renderer plugins.
• Changelog — version history, including the v4 line.
• Blog — practical posts on media handling, converting properties to frontmatter, handling documents, and converting comments to Markdown footnotes.

If your goal is a one-off export, the Getting Started page plus the default configuration is enough. If you need custom output, start with the Concepts section on renderer and exporter plugins, then use the catalogues to see what already exists before writing your own.

notion-to-md does not leave Notion-hosted images and files as-is by default. It exposes a media handling layer with three strategies — download, upload, and direct/buffer — and rewrites the links in the generated Markdown to point at wherever the media ends up. You choose the strategy through configuration; the library then processes each media block during conversion and updates the reference automatically. This applies to images and files embedded in Notion pages, not to arbitrary external URLs you paste as plain text.

The three media strategies

The strategy is a configuration choice, not a per-file decision you make by hand — you set it once and the converter applies it consistently across the page.

Download

Use this when the Markdown output should be self-contained. The converter retrieves each Notion-hosted asset and writes it to a destination you configure, then replaces the original Notion link in the Markdown with the new local path. The practical benefit is that your output no longer depends on Notion's signed, expiring URLs.

Upload

Use this when your destination is a CMS, static host, or object store. The converter fetches the asset and hands it to your upload target, then writes the resulting public URL into the Markdown. Because the upload step is yours to define, the returned link is whatever your storage layer produces — the library's job is to fetch, hand off, and substitute.

Direct / buffer

Use this when you want speed or when a downstream step will handle persistence. The asset is either left pointing at its Notion source or held in memory rather than written to disk. This is the lightest option, but it means the Markdown still references Notion-hosted URLs, which can expire — so treat it as an intermediate state rather than a final published form.

How links get updated

The link rewrite is the part that makes the strategy useful. During conversion, each media block is processed according to your configured strategy, and the Markdown that comes out references the post-processing location — a local path for download, your storage URL for upload, or the original source for direct. You do not need a separate find-and-replace pass over the output; the substitution happens as part of rendering.

A concrete example: a page contains an image whose Notion URL is a temporary signed link. With the download strategy configured to a local assets/ folder, the generated Markdown contains ![alt](assets/image-name.png) instead of the Notion URL. Run the same page through with upload configured, and the same image reference becomes your CDN URL. The page content is identical; only the media strategy changed the output.

Cleanup and configuration

Media handling is configured alongside the rest of the conversion options, and the library documents it as a distinct concept with its own configuration surface. Two things worth planning for:

• Cleanup of downloaded files. If you re-run conversions, downloaded assets can accumulate. Decide whether your pipeline overwrites, versions, or prunes the media directory, and wire that into your build rather than relying on the converter to manage lifecycle.
• Naming and collisions. Assets pulled from different pages can share names. Check how your configured destination handles collisions before you commit to a flat folder.

The library also ships a media strategy catalogue in its documentation, which is the right place to confirm the exact configuration keys and any strategy-specific options for the version you install — the plugin system is extensible, so available behavior can differ between releases.

Choosing a strategy

• Publishing to a static site or docs platform that serves its own assets → download, and commit or deploy the media folder with the Markdown.
• Content going to a CMS or CDN you control → upload, so links resolve to your infrastructure.
• Building a preview, a one-off export, or a pipeline where a later step re-hosts media → direct/buffer, accepting that links are temporary.
• Mixing sources (some pages public, some internal) → pick the strategy that matches your strictest destination, since the setting applies across the conversion.

If your output will be published and long-lived, avoid leaving Notion URLs in the Markdown; signed links expire, and the page will show broken media later.