jekyll-notion
Import notion pages to jekyll.
You can learn more about how to use jekyll-notion with the following links:
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
Usage
Before using the gem, create an integration and generate a secret token. For more in-depth instructions, refer to the Notion "Getting Started" guide.
Once you have your secret token, make sure to export it into an environment variable named NOTION_TOKEN.
$ export NOTION_TOKEN=<secret_...>
Databases
Once the notion database has been shared, specify the database id in the _config.yml file as follows.
notion:
databases:
- id: 5cfed4de3bdc4f43ae8ba653a7a2219b
By default, the notion pages in the database will be loaded into the posts collection.
We can also define multiple databases as follows.
collections:
- recipes
- films
notion:
databases:
- id: b0e688e199af4295ae80b67eb52f2e2f
- id: 2190450d4cb34739a5c8340c4110fe21
collection: recipes
- id: e42383cd49754897b967ce453760499f
collection: films
After running jekyll build (or serve) command, the posts, recipes and films collections will be loaded with pages from the notion databases.
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 filter property,sorts: the database sorts criteria,
notion:
databases:
- id: e42383cd49754897b967ce453760499f
collection: posts
filter: { "property": "Published", "checkbox": { "equals": true } }
sorts: [{ "timestamp": "created_time", "direction": "ascending" }]
Posts date
The created_time property of a notion page is used to set the date in the post filename. This is the date used for the date variable of the predefined variables for posts.
It's important to note that the created_time cannot be modifed. However, if you wish to change the date of a post, you can create a new page property named "date" (or "Date"). This way, the posts collection will use the date property for the post date variable instead of the created_time.
Pages
Individual Notion pages can also be loaded into Jekyll. Just define the page property as follows.
notion:
pages:
- id: 5cfed4de3bdc4f43ae8ba653a7a2219b
As databases, we can set up multiple pages.
notion:
pages:
- id: e42383cd49754897b967ce453760499f
- id: b0e688e199af4295ae80b67eb52f2e2f
- id: 2190450d4cb34739a5c8340c4110fe21
The filename of the generated page is the notion page title. Check below for more info.
All properties assigned to a notion page will be interpreted by jekyll as front matter. For example, if the permalink property is set to /about/ in the notion page, jekyll will use it to create the corresponding path at the output directory at /about/index.html.
Data
Instead of storing the notion pages in a collection or in the pages list, you can assign them to the data object.Just declare the data property next to the page or database id.
notion:
databases:
- id: b0e688e199af4295ae80b67eb52f2e2f
- id: e42383cd49754897b967ce453760499f
data: films
pages:
- id: e42383cd49754897b967ce453760499f
- id: b0e688e199af4295ae80b67eb52f2e2f
data: about
Page properties and body of the notion page are stored as a hash object.
Data objects can be accessed as follows.
<ul>
{% for film in site.data.films %}
<li>{{ film.title }}</li>
{% endfor %}
</ul>
Notice, the page body is stored in the key content.
{{ site.data.about.content }}
The rest of properties are mapped as expected. For more info go to notion properties.
Watch (Deprecated)
Use the cache mechanism instead.
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
databases:
- id: e42383cd49754897b967ce453760499f
And that's all. Each page in the notion database will be included in the selected collection.
Cache
Starting from version 2.4.0, every request to Notion is cached locally. The cache enables the retrieval of Notion resources only during the first request. Subsequent requests are fetched from the cache, which can significantly reduce build times.
The cache mechanism is based on the vcr gem, which records HTTP requests. Every Notion resource, whether it is a database or page, is stored in an independent file using the document ID as the filename. For example, a database ID e42383cd49754897b967ce453760499f will be stored in the following path:
.cache/jekyll-notion/vcr_cassetes/e42383cd49754897b967ce453760499f.yml
Note: The cache option invalidates the fetch_on_watch feature.
Cache folder
By default, the cache folder is .cache/jekyll-notion/vcr_cassetes, but you can change this folder by setting the cache_dir property in the _config.yml file as follows.
notion:
cache_dir: another/folder
The path must be relative to the working folder.
Cleaning cache
To clear the cache, delete the cache folder. If you want to remove a specific cache file, locate the file that matches the Notion resource ID and delete it.
Disabling cache
If you're not interested in the cache or you just want to disable it, set the ˋcache` option to false.
notion:
cache: false
Notion properties
Notion page properties are set for each document in the front matter.
Please, refer to the notion_to_md gem to learn more.
Page filename
There are two kinds of documents in Jekyll: posts and others.
When the document is a post, the filename format contains the created_time property plus the page title as specified in jekyll docs.
YEAR-MONTH-DAY-title.MARKUP
The filename for any other document is the page title.