{"id":15454978,"url":"https://github.com/emoriarty/jekyll-notion","last_synced_at":"2025-08-21T00:32:00.091Z","repository":{"id":42442627,"uuid":"444974196","full_name":"emoriarty/jekyll-notion","owner":"emoriarty","description":"Use Notion as a CMS for Jekyll.","archived":false,"fork":false,"pushed_at":"2025-08-11T14:30:00.000Z","size":257,"stargazers_count":85,"open_issues_count":6,"forks_count":7,"subscribers_count":2,"default_branch":"main","last_synced_at":"2025-08-16T05:29:57.804Z","etag":null,"topics":["jekyll","jekyll-plugin","notion","ruby"],"latest_commit_sha":null,"homepage":"","language":"Ruby","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/emoriarty.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2022-01-05T22:59:48.000Z","updated_at":"2025-08-10T17:58:47.000Z","dependencies_parsed_at":"2025-05-14T20:26:51.023Z","dependency_job_id":"9c712356-d2a7-4e57-844b-160ccd377be8","html_url":"https://github.com/emoriarty/jekyll-notion","commit_stats":{"total_commits":113,"total_committers":3,"mean_commits":"37.666666666666664","dds":0.4424778761061947,"last_synced_commit":"2a58389d50fa742ab5e8920822fe9e7bcd3cab1c"},"previous_names":[],"tags_count":29,"template":false,"template_full_name":null,"purl":"pkg:github/emoriarty/jekyll-notion","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/emoriarty%2Fjekyll-notion","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/emoriarty%2Fjekyll-notion/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/emoriarty%2Fjekyll-notion/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/emoriarty%2Fjekyll-notion/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/emoriarty","download_url":"https://codeload.github.com/emoriarty/jekyll-notion/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/emoriarty%2Fjekyll-notion/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":271409446,"owners_count":24754715,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-08-20T02:00:09.606Z","response_time":69,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["jekyll","jekyll-plugin","notion","ruby"],"created_at":"2024-10-01T22:08:08.354Z","updated_at":"2025-08-21T00:32:00.079Z","avatar_url":"https://github.com/emoriarty.png","language":"Ruby","funding_links":[],"categories":[],"sub_categories":[],"readme":"# jekyll-notion\n\nImport notion pages to jekyll.\n\nYou can learn more about how to use jekyll-notion with the following links:\n\n* [Load notion pages in jekyll](https://enrq.me/dev/2022/03/20/load-notion-pages-in-jekyll/)\n* [Managing Jekyll posts in Notion](https://enrq.me/dev/2022/03/24/managing-jekyll-posts-in-notion/)\n* [Embedding videos with jekyll-notion](https://enrq.me/dev/2023/03/31/embedding-videos-with-jekyll-notion/)\n\n## Installation\n\nUse gem to install.\n```bash\n$ gem install 'jekyll-notion'\n```\n\nOr add it to the `Gemfile`.\n```ruby\n# Gemfile\ngem 'jekyll-notion'\n```\n\n\u003e [!IMPORTANT]  \n\u003e When using jekyll-archives, make sure that jekyll-notion is placed before jekyll-archives in the gemfile. Otherwise pages imported by jekyll-notion won't be collected by jekyll-archives. More info [here](https://github.com/emoriarty/jekyll-notion/issues/95#issuecomment-2732112458).\n\nAnd update your jekyll plugins property in `_config.yml`.\n\n```yml\nplugins:\n  - jekyll-notion\n```\n\n## Usage\n\nBefore using the gem, create an integration and generate a secret token. For more in-depth instructions, refer to the Notion \"Getting Started\" [guide](https://developers.notion.com/docs/getting-started).\n\nOnce you have your secret token, make sure to export it into an environment variable named `NOTION_TOKEN`.\n\n```bash\n$ export NOTION_TOKEN=\u003csecret_...\u003e\n```\n\n### Databases\n\nOnce the [notion database](https://developers.notion.com/docs/working-with-databases) has been shared, specify the database `id` in the `_config.yml` file as follows.\n\n```yml\nnotion:\n  databases:\n    - id: 5cfed4de3bdc4f43ae8ba653a7a2219b\n```\n\nBy default, the notion pages in the database will be loaded into the `posts` collection.\n\nWe can also define __multiple databases__ as follows.\n\n```yml\ncollections:\n  - recipes\n  - films\n\nnotion:\n  databases:\n    - id: b0e688e199af4295ae80b67eb52f2e2f\n    - id: 2190450d4cb34739a5c8340c4110fe21\n      collection: recipes\n    - id: e42383cd49754897b967ce453760499f \n      collection: films\n```\n\nAfter running `jekyll build` (or `serve`) command, the `posts`, `recipes` and `films` collections will be loaded with pages from the notion databases. \n\n#### Database options\n\nEach dabatase support the following options.\n\n* `id`: the notion database unique identifier,\n* `collection`: the collection each page belongs to (posts by default),\n* `filter`: the database [filter property](https://developers.notion.com/reference/post-database-query-filter),\n* `sorts`: the database [sorts criteria](https://developers.notion.com/reference/post-database-query-sort),\n\n```yml\nnotion:\n  databases:\n    - id: e42383cd49754897b967ce453760499f\n      collection: posts\n      filter: { \"property\": \"Published\", \"checkbox\": { \"equals\": true } }\n      sorts: [{ \"timestamp\": \"created_time\", \"direction\": \"ascending\" }]\n```\n\n#### Posts date\n\nThe `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](https://jekyllrb.com/docs/front-matter/#predefined-variables-for-posts).\n\nIt'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`.\n\n### Pages\n\nIndividual Notion pages can also be loaded into Jekyll. Just define the `page` property as follows.\n\n```yml\nnotion:\n  pages:\n    - id: 5cfed4de3bdc4f43ae8ba653a7a2219b\n```\n\nAs databases, we can set up multiple pages.\n\n```yaml\nnotion:\n  pages:\n    - id: e42383cd49754897b967ce453760499f\n    - id: b0e688e199af4295ae80b67eb52f2e2f\n    - id: 2190450d4cb34739a5c8340c4110fe21\n```\n\nThe filename of the generated page is the notion page title. Check [below](#page-filename) for more info.\n\nAll properties assigned to a notion page will be interpreted by jekyll as front matter. For example, if the [permalink](https://jekyllrb.com/docs/permalinks/#front-matter) 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`.\n\n### Data\n\nInstead 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.\n\n```yml\nnotion:\n  databases:\n    - id: b0e688e199af4295ae80b67eb52f2e2f\n    - id: e42383cd49754897b967ce453760499f\n      data: films\n  pages:\n    - id: e42383cd49754897b967ce453760499f\n    - id: b0e688e199af4295ae80b67eb52f2e2f\n      data: about\n```\n\nPage properties and body of the notion page are stored as a hash object.\n\nData objects can be accessed as follows.\n\n```html\n\u003cul\u003e\n{% for film in site.data.films %}\n  \u003cli\u003e{{ film.title }}\u003c/li\u003e\n{% endfor %}\n\u003c/ul\u003e\n```\n\nNotice, the page body is stored in the key `content`.\n\n```html\n{{ site.data.about.content }}\n```\n\nThe rest of properties are mapped as expected. For more info go to [notion properties](#notion-properties).\n\n### Watch (Deprecated)\n\n_Use the cache mechanism instead._\n\nBy default, databases are only requested during the first build. Subsequent builds use the results from the cache.\n\nSet `fetch_on_watch` to true to allow request on each rebuild.\n\n```yml\nnotion:\n  fetch_on_watch: true\n  databases:\n    - id: e42383cd49754897b967ce453760499f\n```\n\nAnd that's all. Each page in the notion database will be included in the selected collection.\n\n### Cache\n\nStarting 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.\n\nThe cache mechanism is based on the [vcr](https://github.com/vcr/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:\n\n```bash\n.cache/jekyll-notion/vcr_cassetes/e42383cd49754897b967ce453760499f.yml\n```\n\n**Note: The `cache` option invalidates the fetch_on_watch feature.**\n\n#### Cache folder\n\nBy 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.\n\n```yaml\nnotion:\n  cache_dir: another/folder\n```\n\nThe path must be relative to the working folder.\n\n#### Cleaning cache\n\nTo 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.\n\n#### Disabling cache\n\nIf you're not interested in the cache or you just want to disable it, set the ˋcache` option to false.\n\n```yaml\nnotion:\n  cache: false\n```\n\n## Notion properties\n\nNotion page properties are set for each document in the front matter.\n\nPlease, refer to the [notion_to_md](https://github.com/emoriarty/notion_to_md/) gem to learn more.\n\n## Page filename\n\nThere are two kinds of documents in Jekyll: posts and others.\n\nWhen the document is a post, the filename format contains the `created_time` property plus the page title as specified in [jekyll docs](https://jekyllrb.com/docs/posts/#creating-posts).\n\n```\nYEAR-MONTH-DAY-title.MARKUP\n```\n\nThe filename for any other document is the page title.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Femoriarty%2Fjekyll-notion","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Femoriarty%2Fjekyll-notion","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Femoriarty%2Fjekyll-notion/lists"}