0.01
The project is in a healthy, maintained state
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
 Dependencies

Development

Runtime

 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