Load notion pages in jekyll

In this article, I am going to show you what you need to do to allow jekyll to download notion pages using the jekyll-notion gem.

Before you can use jekyll-notion, the first thing you must do is to have a notion account. You can create one here if you don’t have one. You must also create an integration token. Please follow the getting started guide on notion for this. This should take no more than 5 minutes.

Now, if you are ready and have your token in hand, it’s time to create a page. For example, let’s say the about page.

You do not need to create a real page now. Choose a lorem ipsum sample to test.

By the way, remember that not all content is supported by jekyll-notion. See this list to find out which items are supported.

Once you are done with the page, the next step is to share it with your integration. In my case, I called it blog.

Now that the page is shared, copy the page id from the URL.

Assuming you have already installed jekyll and jekyll-notion, open the _config.yml file and add the following configuration with the id of your page.

notion:
  pages:
    - id: 94x5ae3e3e434f038fbcb2958a891bc6

If you haven’t installed jekyll yet, check how to do it in its official documentation. You can also see how to install jekyll-notion here.

And last but not least, export the NOTION_TOKEN environment variable with the notion secret created in the integration step.

export NOTION_TOKEN=secret_XXXXXXXXXXXXXXXXXXXXXXXXXXX

Now that everything is configured, run the jekyll serve command and you should see the following output.

$ jekyll serve
...
Jekyll Notion: Page => about
               URL => /about/
...
  Server address: http://127.0.0.1:4000
Server running... press ctrl-c to stop.

And that’s it for the page about. You can now visit http://localhost:4000/about. If your port is another one, change it to yours.

Perhaps, we just want to change the current layout. There are two options to deal with this. We can set the layout using the front matter defaults in the _config.yml.

defaults:
  -
    scope:
      path: "about"
    values:
      layout: about

Or, by defining the layout property on the page. To do this, create a custom text property called layout.

The next time we build, the declared layout will be used. Notice that I have also included the permalink property. Therefore, the about page is available at http://localhost:4000/about-me.

If we want to know which properties are mapped exactly from notion, we can run jekyll in verbose mode.

$ jekyll serve --verbose
...
Jekyll Notion: Page => about
               URL => /about-me/
               Props => ["permalink", "layout", "id", "title", "created_time", "cover", "icon", "last_edited_time", "archived"]
...

Each property contained in the page maps to the front matter. Check which property types are supported.

From now on, you can easily create as many pages as you want in notion and use them in your jekyll site.

notion:
  pages:
    - id: 94x5ae3e3e434f038fbcb2958a891bc6 # about
    - id: 04d0d210d323bbbd4efad360ecaf049a # portfolio
    - id: 5b9f2b71762df312ce9421dd957cd849 # services

In a future article, I will show you how to map notion databases to jekyll posts. Spoiler: it’s not much different from mapping pages.