jekyll-notion

Import notion pages to a jekyll collection or data.

Installation

Use gem to install.

$ gem install 'jekyll-notion'

Or add it to the Gemfile.

# Gemfile
gem 'jekyll-notion'

And update your jekyll plugins property in _config.yml.

plugins:
  - jekyll-notion

Setup

Before using the gem create an integration and generate a secret token. Check notion getting started guide to learn more.

Export the notion secret token in an environment variable named NOTION_TOKEN.

$ export NOTION_TOKEN=<secret_...>

Once your notion database has been shared, specify the database id in your _config.yml as follows.

notion:
  database:
    id: 5cfed4de3bdc4f43ae8ba653a7a2219b

After running jekyll build (or serve) command, the posts collection is loaded with pages of the notion database specified in the configuration.

Mutiple dabatases

You can also define multiple databases as follows.

collections:
  - recipes
  - films

notion:
  databases:
    - id: b0e688e199af4295ae80b67eb52f2e2f
    - id: 2190450d4cb34739a5c8340c4110fe21
      collection: recipes
    - id: e42383cd49754897b967ce453760499f 
      collection: films

Data

Instead of storing notion pages in a collection, you can also map to the data object. Use the data property instead of collection.

notion:
  database:
    id: e42383cd49754897b967ce453760499f
    data: films

Page properties and body are stored as a hash data.

As a particular characteristic, the page is stored in a key named content.

<p>{{ site.data.films.content }}</p>

The rest of properties as mapped as expected.

Pages

Individual Notion pages can also be mapped to data. Just define the pages or page property as follows.

notion:
  pages:
    - id: e42383cd49754897b967ce453760499f
      data: about
    - id: b0e688e199af4295ae80b67eb52f2e2f
      data: contact
    - id: 2190450d4cb34739a5c8340c4110fe21
      data: footer

This feature is only available for data.

Database options

Each dabatase support the following options.

  • id: the notion database unique identifier,
  • collection: the collection each page belongs to (posts by default),
  • filter: the database query filter,
  • sort: the database query sort,
notion:
  database:
    id: e42383cd49754897b967ce453760499f
    collection: posts
    filter: { "property": "Published", "checkbox": { "equals": true } }
    sort: { "property": "Last ordered", "direction": "ascending" }

Watch

By default, databases are only requested during the first build. Subsequent builds use the results from the cache.

Set fetch_on_watch to true to allow request on each rebuild.

notion:
  fetch_on_watch: true
  database:
    id: e42383cd49754897b967ce453760499f

And that's all. Each page in the notion database will be included in the selected collection.

Notion properties

Below, default properties per notion page are set for each document front matter.

Notion page properties are id, title, created_time, last_edited_time, icon, cover and archived.

---
id: e42383cd-4975-4897-b967-ce453760499f
title: An amazing post
cover: https://img.bank.sh/an_image.jpg
date: 2022-01-23T12:31:00.000Z
icon: 💥
archived: false
---

In addition to default properties, custom properties are also appended to front matter.

Please, refer to the notion_to_md gem to learn more.

Page filename

There are two kinds of collections: posts and others.

When the collection is posts, the filename format contains the created_time property plus the page title as specified in jekyll docs.

YEAR-MONTH-DAY-title.MARKUP

Any other collection, the filename is the page title.