jekyll-fetch-notion

jekyll-fetch-notion

The Jekyll plugin introduces the fetch_notion command. This command fetches all Notion content as specified by the _config.yml file and places it directly into your git repository. This project is a fork of jekyll-notion, created due to incompatible synchronization methods. You can find more details in this pull request.

Note: Data and page fetching are planned for future releases but are not yet available.

The original project was designed with the idea that Notion content should be fetched during site building and not tracked by git. This project, however, takes a different approach. It arranges your workflow so that your Notion content is git-tracked and fetched before site building.

I believe this method aligns better with Jekyll's "ideology" and also offers several advantages:

• Your Notion content is git-tracked and preserved. This ensures a smooth transition from Notion back to plain .md editing or to another synchronization tool. As Jekyll is a static site generator, everything remains static.
• Separating Notion synchronization from site building simplifies the process and provides you more precise control. For example, you again can git-clone and build a site as-is without Notion token.

However, every implementation has its own pros and cons. Choose the one that best suits your needs.

For more insights into my experience with jekyll-fetch-notion, check out these posts:

• Yet another way to establish Notion + Jekyll synchronization
• Notion + Jekyll images synchronization

Installation

Use gem to install:

gem install 'jekyll-fetch-notion'

Or add it to the Gemfile:

gem 'jekyll-fetch-notion'

And then update your jekyll plugins property in _config.yml:

plugins:
  - jekyll-fetch-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_...>

Then you can run command to fetch all the Notion content and place it inside your's site repository:

jekyll fetch_notion

Then you probably need to stage, commit and push all the fetched files to trigger your default CI build flow and make your updated site deployed.

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 fetch_notion command, the posts, recipes and films collections will be fetched 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.

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.

Alternatives

Actually, there are a lot of alternatives available, but, however, mostly all of them are not so mature and hard to extend. This one (like jekyll-notion) is tested by time and easy to extend because of notion_to_md usage.

License

MIT License

Copyright (c) 2024 Enrique Arias, Daniil Sivak

Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
SOFTWARE.