How Do I Get Started Converting Notion Pages to Markdown with notion-to-md?

Updated

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.