jekyll-notion 2.3.2 → 2.4.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: dadf92a4c00ce112ad5ca51e136b676a380b54fedfa75a9488ce5437d56a71d1
-  data.tar.gz: df4431eab3308f7502082196c9d8bb8518b340c94d7c76950f0430664769afa1
+  metadata.gz: 823cd1e40e6efc0003a0829807361ef7e9aef85d13e7a5a83236be1ea48312b0
+  data.tar.gz: 729882137bd7597ce87f2ba66d8f79df57b794262cd19950b5288f952a8f6c13
 SHA512:
-  metadata.gz: 6d4aba49009378a8ca3e298d1de97d5285854bc5282c1aedb6e43ad7d6406a60baa0cfae614f33d027fa7a94353f2d03bd93405d6c8b60ac0ea72639a7f50f26
-  data.tar.gz: 79bc2b133cd57a4da85216433564963ac56a49120ac36ed15aa8bb585fce64b54751f8a635816c1c9fc6afd968ad6289e4cc1dea854cee85576753cfd22e1397
+  metadata.gz: a32dc6d722f0692658969df2d7ebfd195e865503c47fda06ed2556f8b7c005968a2c08f96dfe4a5188926fc192094494d53423d107b67ca93a9717952a05f2e4
+  data.tar.gz: 3b8b5b61aa56e48e2823f58c00ddc67af8a9bdc5b892aedd7d13863aea25ecf14cf2def9b64cc1259170974527d00d250b8468b053d38a14e1957037d13f1fd3

data/README.md

@@ -24,9 +24,9 @@ plugins:
 
 ## Usage
 
-Before using the gem create an integration and generate a secret token. Check [notion getting started guide](https://developers.notion.com/docs/getting-started) to learn more.
+Before 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).
 
-Once you have youe secret, export it in an environment variable named `NOTION_TOKEN`.
+Once you have your secret token, make sure to export it into an environment variable named `NOTION_TOKEN`.
 
 ```bash
 $ export NOTION_TOKEN=<secret_...>
@@ -34,7 +34,7 @@ $ export NOTION_TOKEN=<secret_...>
 
 ### Databases
 
-Once the [notion database](https://www.notion.so/help/intro-to-databases) has been shared, specify the database `id` in the `_config.yml` file as follows.
+Once 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.
 
 ```yml
 notion:
@@ -42,7 +42,7 @@ notion:
     - id: 5cfed4de3bdc4f43ae8ba653a7a2219b
 ```
 
-By default, the notion pages contained in the database will be loaded into the `posts` collection.
+By default, the notion pages in the database will be loaded into the `posts` collection.
 
 We can also define __multiple databases__ as follows.
 
@@ -80,6 +80,12 @@ notion:
       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](https://jekyllrb.com/docs/front-matter/#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.
@@ -155,6 +161,42 @@ notion:
 
 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](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:
+
+```bash
+.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.
+
+```yaml
+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.
+
+```yaml
+notion:
+  cache: false
+```
+
 ## Notion properties
 
 Notion page properties are set for each document in the front matter.

data/lib/jekyll-notion/abstract_notion_resource.rb

@@ -39,7 +39,7 @@ module JekyllNotion
     end
 
     def build_blocks(block_id)
-      NotionToMd::Blocks.build(block_id: block_id) do |nested_id|
+      NotionToMd::Blocks.build(:block_id => block_id) do |nested_id|
         @notion.block_children({ :block_id => nested_id })
       end
     end

data/lib/jekyll-notion/cacheable.rb

@@ -0,0 +1,33 @@
+# frozen_string_literal: true
+
+#
+
+module JekyllNotion
+  module Cacheable
+    def self.setup(cache_dir)
+      # Using VCR to record and playback Notion API responses for caching
+      VCR.configure do |config|
+        config.cassette_library_dir = cache_path(cache_dir)
+        config.hook_into :faraday # Faraday is used by notion-ruby-client gem
+        config.filter_sensitive_data("<NOTION_TOKEN>") { ENV["NOTION_TOKEN"] }
+        config.allow_http_connections_when_no_cassette = true
+        config.default_cassette_options = {
+          :allow_playback_repeats => true,
+          :record                 => :new_episodes,
+        }
+      end
+    end
+
+    def self.cache_path(path = nil)
+      if path.nil?
+        File.join(Dir.getwd, ".cache", "jekyll-notion", "vcr_cassettes")
+      else
+        File.join(Dir.getwd, path)
+      end
+    end
+
+    def generate(*args)
+      VCR.use_cassette(resource_id) { super(*args) }
+    end
+  end
+end

data/lib/jekyll-notion/generator.rb

@@ -9,6 +9,8 @@ module JekyllNotion
 
       return unless notion_token? && config?
 
+      setup
+
       if fetch_on_watch? || cache_empty?
         read_notion_databases
         read_notion_pages
@@ -78,7 +80,8 @@ module JekyllNotion
 
     def notion_token?
       if ENV["NOTION_TOKEN"].nil? || ENV["NOTION_TOKEN"].empty?
-        Jekyll.logger.warn("Jekyll Notion:", "NOTION_TOKEN not provided. Cannot read from Notion.")
+        Jekyll.logger.warn("Jekyll Notion:",
+                           "Cannot read from Notion becuase NOTION_TOKEN was not provided")
         return false
       end
       true
@@ -86,10 +89,26 @@ module JekyllNotion
 
     def config?
       if config.empty?
-        Jekyll.logger.warn("Jekyll Notion:", "No config provided.")
+        Jekyll.logger.warn("Jekyll Notion:", "No configuration provided")
         return false
       end
       true
     end
+
+    def setup
+      # Cache Notion API responses
+      if ENV["JEKYLL_ENV"] != "test" && cache?
+        JekyllNotion::Cacheable.setup(config["cache_dir"])
+        JekyllNotion::CollectionGenerator.prepend(JekyllNotion::Cacheable)
+        JekyllNotion::PageGenerator.prepend(JekyllNotion::Cacheable)
+        JekyllNotion::DataGenerator.prepend(JekyllNotion::Cacheable)
+      end
+    end
+
+    def cache?
+      return true if config["cache"].nil?
+
+      config["cache"] == true.to_s
+    end
   end
 end

data/lib/jekyll-notion/generators/abstract_generator.rb

@@ -11,5 +11,9 @@ module JekyllNotion
     def generate
       raise "Do not use the AbstractGenerator class. Implement the generate method in a subclass."
     end
+
+    def resource_id
+      @notion_resource.id
+    end
   end
 end

data/lib/jekyll-notion/generators/collection_generator.rb

@@ -40,10 +40,9 @@ module JekyllNotion
 
     def make_filename(page)
       if @notion_resource.collection_name == "posts"
-        "#{page.created_time.to_date}-#{Jekyll::Utils.slugify(page.title,
-                                                              :mode => "latin")}.md"
+        "#{date_for(page)}-#{Jekyll::Utils.slugify(page.title, :mode => "latin")}.md"
       else
-        "#{page.title.downcase.parameterize}.md"
+        "#{Jekyll::Utils.slugify(page.title, :mode => "latin")}.md"
       end
     end
 
@@ -61,5 +60,15 @@ module JekyllNotion
       end
       Jekyll.logger.debug("", "Props => #{collection.docs.last.data.keys.inspect}")
     end
+
+    def date_for(page)
+      # The "date" property overwrites the Jekyll::Document#data["date"] key
+      # which is the date used by Jekyll to set the post date.
+      DateTime.parse(page.props["date"]).to_date
+    rescue TypeError, NoMethodError
+      # Because the "date" property is not required,
+      # it fallbacks to the created_time which is always present.
+      page.created_time.to_date
+    end
   end
 end

data/lib/jekyll-notion/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module JekyllNotion
-  VERSION = "2.3.2"
+  VERSION = "2.4.1"
 end

data/lib/jekyll-notion.rb

@@ -5,6 +5,7 @@ require "notion"
 require "notion_to_md"
 require "logger"
 require "jekyll-notion/generator"
+require "vcr"
 
 NotionToMd::Logger.level = Logger::ERROR
 
@@ -24,4 +25,5 @@ module JekyllNotion
   autoload :AbstractNotionResource, "jekyll-notion/abstract_notion_resource"
   autoload :NotionDatabase, "jekyll-notion/notion_database"
   autoload :NotionPage, "jekyll-notion/notion_page"
+  autoload :Cacheable, "jekyll-notion/cacheable"
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: jekyll-notion
 version: !ruby/object:Gem::Version
-  version: 2.3.2
+  version: 2.4.1
 platform: ruby
 authors:
 - Enrique Arias
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2022-10-05 00:00:00.000000000 Z
+date: 2023-10-14 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: jekyll
@@ -58,6 +58,20 @@ dependencies:
     - - "~>"
       - !ruby/object:Gem::Version
         version: '2.2'
+- !ruby/object:Gem::Dependency
+  name: vcr
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '6.2'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '6.2'
 - !ruby/object:Gem::Dependency
   name: bundler
   requirement: !ruby/object:Gem::Requirement
@@ -125,6 +139,7 @@ files:
 - README.md
 - lib/jekyll-notion.rb
 - lib/jekyll-notion/abstract_notion_resource.rb
+- lib/jekyll-notion/cacheable.rb
 - lib/jekyll-notion/document_without_a_file.rb
 - lib/jekyll-notion/factories/database_factory.rb
 - lib/jekyll-notion/factories/page_factory.rb