Project

notion_to_md

0.01
The project is in a healthy, maintained state
notion_to_mdemoriarty/notion_to_mdHomepageDocumentationSource CodeBug TrackerWiki
Notion Markdown Exporter in Ruby
2005
2006
2007
2008
2009
2010
2011
2012
2013
2014
2015
2016
2017
2018
2019
2020
2021
2022
2023
2024
2025
 Popularity
Downloads
51,724
Stars
18
Forks
6
Watchers
1
 Releases
Current version
2.5.1
Total releases
28
First release
2021-12-28
Latest release
2025-09-07
 Issues
Open Issues
1
Closed Issues
9
Total Issues
10
Issue Closure Rate
90%
 Pull Requests
Open Pull Requests
2
Closed Pull Requests
9
Merged Pull Requests
94
Pull Request Acceptance Rate
89%
 Development
Primary Language
Ruby
Licenses
MIT
Average date of last 50 commits
2025-02-03
Reverse Dependencies
4

 Dependencies

Development

rubocop
>= 0
hashie
>= 0
rspec
>= 0
simplecov
>= 0
rubocop-rspec
>= 0
vcr
>= 0

Runtime

callee
~> 0.3.6
notion-ruby-client
~> 1
activesupport
~> 7
 Project Readme

notion_to_md

A Ruby library to export Notion pages and databases to Markdown. The output is fully compliant with the GitHub Flavored Markdown specification.

Gem Version CI

Note

You are reading the documentation for the latest development branch. For the stable v2.x.x documentation, see the v2.x.x branch.

Installation

Install via RubyGems:

gem install notion_to_md

Or add it to your Gemfile:

gem 'notion_to_md'

Beta version

Learn about the new changes in the following post.

If you want to try the beta release, install with the --pre flag:

gem install notion_to_md --pre

Or pin the beta in your Gemfile:

gem "notion_to_md", "3.0.0.beta2"

⚠️ This version is under active development. For stable usage, prefer the latest 2.x.x release.

Quick Start

# Convert a Notion page to Markdown
md = NotionToMd.call(:page, id: 'b91d5...', token: ENV['NOTION_TOKEN'])
File.write("page.md", md)

Usage

Before using the gem, create a Notion integration and obtain a secret token. See the Notion Getting Started Guide for details.

Pages

md = NotionToMd.call(:page, id: 'b91d5...', token: 'secret_...')
# or equivalently
md = NotionToMd.convert(:page, id: 'b91d5...', token: 'secret_...')

md is a string containing the page content in Markdown format.

Databases

mds = NotionToMd.call(:database, id: 'b91d5...')

mds is an array of strings, one per page.

Environment Variables

If your token is stored in NOTION_TOKEN, you don’t need to pass it explicitly:

export NOTION_TOKEN=<secret_...>
md = NotionToMd.call(:page, id: 'b91d5...')

Supported Blocks

Everything in Notion is a block object.

Block type Nested children supported?
paragraph ✅
heading_1 / heading_2 / heading_3 ❌
bulleted_list_item ✅
numbered_list_item ✅
to_do ✅
image, file, pdf, video ❌
bookmark, embed, link_preview ❌
callout ❌
quote ❌
divider ❌
table ❌
code ❌
equation ❌

Front Matter

By default, front matter is disabled. Enable it with:

NotionToMd.call(:page, id: 'b91d5...', frontmatter: true)

Examples

Default properties:

---
id: e42383cd-4975-4897-b967-ce453760499f
title: An amazing post
cover: https://img.bank.sh/an_image.jpg
created_time: 2022-01-23T12:31:00.000Z
last_edited_time: 2022-01-23T12:31:00.000Z
icon: 💥
archived: false
created_by_id: db313571-0280-411f-a6de-70e826421d16
created_by_object: user
last_edited_by_id: db313571-0280-411f-a6de-70e826421d16
last_edited_by_object: user
---

Custom properties:

---
tags: tag1, tag2, tag3
multiple_options: option1, option2
---

Custom property names are parameterized and underscored.

Supported property types:

  • number
  • select
  • multi_select
  • date
  • people
  • files
  • checkbox
  • url
  • email
  • phone_number
  • rich_text (plain text only)

Note

Advanced types such as formula, relation, and rollup are not supported. See the Notion property value docs.

Development

Run the test suite with:

rspec