jekyll-notion 2.4.3 → 3.0.0.beta1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: a2e9b1115040d4ee01312d20ad5f4941ecc9d3d06f5030e81d923c6c1ebbc42f
-  data.tar.gz: 404ad2116038bdb51c961123954076e5fd141977433c90ec451259e23ab1dadd
+  metadata.gz: ed820907d9684cde0edb6ec147eec63f01c5d0c84ece59e2eae336ffeae89576
+  data.tar.gz: d1007a311273a529246618a538a658ac88e0ac688160294cd730053f721ddb46
 SHA512:
-  metadata.gz: 9541cf17c24c1abda04e6fcead84d6b40e561e41307b8200e53b97d07f86691c5f50fd12616c33b4b1a8d4bd52197ae4e0e94621b409426e370a1837fecef163
-  data.tar.gz: 8ce7987c435b601e21b390424791099f0b63e0c6c3261ba80415d28e4a89965eca0ed6a923a41f0b45d292c9f0a4ba7e924e610fc3376b176a4dd258c9614465
+  metadata.gz: 7492e73cf69027072ce70e458446c27834344e33bccaab9d4e77b5f8f4d6703993b39bde77c96c29658ddfed93e69f49c23882bb4fe803148faa35ca78bca4a4
+  data.tar.gz: 3a0c7bf81c0c2ac03a1b46912dfbb1c499caf5db9621716bfb1a292c697a31dde4b50706b6b6558a9920da69c30ee95a5edf070d7803cd7befac8a20fd376508

data/README.md

@@ -1,58 +1,94 @@
+<img src="https://ik.imagekit.io/gxidvqvc9/jekyll_notion_logo_Thmlxy7GZ.png?updatedAt=1756230501479" width="200">
+
 # jekyll-notion
 
-Import notion pages to jekyll.
+> [!WARNING]
+> The **main branch** is under active development for version 3.
+> For the current **stable release**, please check out the [v2.x.x branch](https://github.com/emoriarty/jekyll-notion/tree/v2.x.x).
 
-You can learn more about how to use jekyll-notion with the following links:
+Import [Notion](https://www.notion.so) pages into
+[Jekyll](https://jekyllrb.com/).
 
-* [Load notion pages in jekyll](https://enrq.me/dev/2022/03/20/load-notion-pages-in-jekyll/)
-* [Managing Jekyll posts in Notion](https://enrq.me/dev/2022/03/24/managing-jekyll-posts-in-notion/)
-* [Embedding videos with jekyll-notion](https://enrq.me/dev/2023/03/31/embedding-videos-with-jekyll-notion/)
+📚 Learn more with these guides:
+- [Load Notion pages in
+Jekyll](https://enrq.me/dev/2022/03/20/load-notion-pages-in-jekyll/)
+- [Managing Jekyll posts in
+Notion](https://enrq.me/dev/2022/03/24/managing-jekyll-posts-in-notion/)
+- [Embedding videos with
+jekyll-notion](https://enrq.me/dev/2023/03/31/embedding-videos-with-jekyll-notion/)
 
 ## Installation
 
-Use gem to install.
-```bash
-$ gem install 'jekyll-notion'
+Install via RubyGems:
+
+``` bash
+gem install jekyll-notion
 ```
 
-Or add it to the `Gemfile`.
-```ruby
+Or add it to your `Gemfile`:
+
+``` ruby
 # Gemfile
 gem 'jekyll-notion'
 ```
 
-And update your jekyll plugins property in `_config.yml`.
+> \[!IMPORTANT\]\
+> If you are using **jekyll-archives**, list `jekyll-notion` *before*
+> `jekyll-archives` in the Gemfile. Otherwise, imported pages will not
+> be picked up.\
+> See the discussion
+> [here](https://github.com/emoriarty/jekyll-notion/issues/95#issuecomment-2732112458).
+
+Then enable the plugin in `_config.yml`:
 
-```yml
+``` yaml
 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](https://developers.notion.com/docs/getting-started).
+Before using the gem, [create a Notion
+integration](https://developers.notion.com/docs/getting-started) and
+generate a secret token.
 
-Once you have your secret token, make sure to export it into an environment variable named `NOTION_TOKEN`.
+Export the token as an environment variable:
 
-```bash
-$ export NOTION_TOKEN=<secret_...>
+``` bash
+export NOTION_TOKEN=<secret_...>
+```
+
+### Environment Variables
+
+The plugin supports the following environment variables for configuration:
+
+- **`NOTION_TOKEN`** (required): Your Notion integration secret token
+- **`JEKYLL_NOTION_CACHE`**: Fallback cache setting when not specified in `_config.yml` (`1`, `true`, `yes` to enable; `0`, `false`, `no` to disable)
+- **`JEKYLL_NOTION_CACHE_DIR`**: Fallback cache directory when not specified in `_config.yml` (defaults to `.cache/jekyll-notion/vcr_cassettes`)
+
+Example usage:
+``` bash
+export NOTION_TOKEN=secret_abc123...
+export JEKYLL_NOTION_CACHE=false
+export JEKYLL_NOTION_CACHE_DIR=/tmp/my-custom-cache
 ```
 
 ### Databases
 
-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.
+Share a [Notion
+database](https://developers.notion.com/docs/working-with-databases),
+then specify its `id` in `_config.yml`:
 
-```yml
+``` yaml
 notion:
   databases:
     - id: 5cfed4de3bdc4f43ae8ba653a7a2219b
 ```
 
-By default, the notion pages in the database will be loaded into the `posts` collection.
+By default, entries will be added to the `posts` collection.
 
-We can also define __multiple databases__ as follows.
+You can also define **multiple databases**:
 
-```yml
+``` yaml
 collections:
   - recipes
   - films
@@ -62,22 +98,26 @@ notion:
     - id: b0e688e199af4295ae80b67eb52f2e2f
     - id: 2190450d4cb34739a5c8340c4110fe21
       collection: recipes
-    - id: e42383cd49754897b967ce453760499f 
+    - 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. 
+After running `jekyll build` or `jekyll serve`, the `posts`, `recipes`,
+and `films` collections will contain pages from the specified databases.
 
 #### Database options
 
-Each dabatase support the following options.
+Each database supports the following options:
 
-* `id`: the notion database unique identifier,
-* `collection`: the collection each page belongs to (posts by default),
-* `filter`: the database [filter property](https://developers.notion.com/reference/post-database-query-filter),
-* `sorts`: the database [sorts criteria](https://developers.notion.com/reference/post-database-query-sort),
+-   `id`: the unique Notion database ID
+-   `collection`: which collection to assign pages to (`posts` by
+    default)
+-   `filter`: a database
+    [filter](https://developers.notion.com/reference/post-database-query-filter)
+-   `sorts`: database [sorting
+    criteria](https://developers.notion.com/reference/post-database-query-sort)
 
-```yml
+``` yaml
 notion:
   databases:
     - id: e42383cd49754897b967ce453760499f
@@ -86,25 +126,29 @@ notion:
       sorts: [{ "timestamp": "created_time", "direction": "ascending" }]
 ```
 
-#### Posts date
+#### Post dates
 
-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).
+By default, the Notion page `created_time` property sets the post
+filename date. This value is used for Jekyll's [`date`
+variable\`](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`.
+Since `created_time` cannot be modified, you can override it by adding a
+custom Notion property named `date` (or `Date`). That property will be
+used instead.
 
 ### Pages
 
-Individual Notion pages can also be loaded into Jekyll. Just define the `page` property as follows.
+You can also load individual Notion pages:
 
-```yml
+``` yaml
 notion:
   pages:
     - id: 5cfed4de3bdc4f43ae8ba653a7a2219b
 ```
 
-As databases, we can set up multiple pages.
+Multiple pages are supported:
 
-```yaml
+``` yaml
 notion:
   pages:
     - id: e42383cd49754897b967ce453760499f
@@ -112,15 +156,19 @@ notion:
     - id: 2190450d4cb34739a5c8340c4110fe21
 ```
 
-The filename of the generated page is the notion page title. Check [below](#page-filename) for more info.
+The generated filename is based on the Notion page title (see [Page
+filename](#page-filename)).
 
-All 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`.
+All page properties are exposed as Jekyll front matter. For example, if
+a page has a `permalink` property set to `/about/`, Jekyll will generate
+`/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.
+Instead of adding Notion pages to collections or `pages`, you can store
+them under the Jekyll **data object** using the `data` option:
 
-```yml
+``` yaml
 notion:
   databases:
     - id: b0e688e199af4295ae80b67eb52f2e2f
@@ -132,91 +180,138 @@ notion:
       data: about
 ```
 
-Page properties and body of the notion page are stored as a hash object.
+Each page is stored as a hash. The page body is available under the
+`content` key.
 
-Data objects can be accessed as follows.
+Example:
 
-```html
+``` html
 <ul>
-{% for film in site.data.films %}
-  <li>{{ film.title }}</li>
-{% endfor %}
+  {% for film in site.data.films %}
+    <li>{{ film.title }}</li>
+  {% endfor %}
 </ul>
-```
 
-Notice, the page body is stored in the key `content`.
-
-```html
 {{ site.data.about.content }}
 ```
 
-The rest of properties are mapped as expected. For more info go to [notion properties](#notion-properties).
+Other properties are mapped normally (see [Notion
+properties](#notion-properties)).
 
-### Watch
+### Cache
 
-By default, databases are only requested during the first build. Subsequent builds use the results from the cache.
+All Notion requests are cached locally with the [VCR](https://github.com/vcr/vcr) gem to speed up rebuilds.
+The first build fetches from the Notion API; subsequent builds reuse the cache.
 
-Set `fetch_on_watch` to true to allow request on each rebuild.
+The cache mechanism provides:
 
-```yml
-notion:
-  fetch_on_watch: true
-  databases:
-    - id: e42383cd49754897b967ce453760499f
+- Per-page cache files that include the Notion page title + ID, making them easy to identify.
+- Page-level deletion: remove a single cached page without affecting others.
+- Databases fetched on every rebuild: new content in Notion is always discovered, while cached pages prevent unnecessary re-fetches.
+
+**Example cached file (title + ID):**
+```bash
+.cache/jekyll-notion/vcr_cassettes/my-page-title-e42383cd49754897b967ce453760499f.yml
 ```
 
-And that's all. Each page in the notion database will be included in the selected collection.
+#### Cache folder
 
-### Cache
+Default: `.cache/jekyll-notion/vcr_cassettes`
 
-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.
+You can override the cache directory in two ways:
 
-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:
+**Option 1: Configuration file** (in `_config.yml`):
+``` yaml
+notion:
+  cache_dir: another/folder
+```
 
-```bash
-.cache/jekyll-notion/vcr_cassetes/e42383cd49754897b967ce453760499f.yml
+**Option 2: Environment variable**:
+``` bash
+export JEKYLL_NOTION_CACHE_DIR=/path/to/custom/cache
 ```
 
-**Note: The `cache` option invalidates the fetch_on_watch feature.**
+The `_config.yml` setting takes precedence over the environment variable.
+Both relative and absolute paths are supported - relative paths are resolved
+from the project root.
 
-#### Cache folder
+#### Cleaning the cache
+
+- Delete the entire cache folder to reset everything.
+- Or delete a single cached page file to refresh only that page.
 
-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.
+#### Disabling the cache
 
-```yaml
+To disable caching entirely:
+
+``` yaml
 notion:
-  cache_dir: another/folder
+  cache: false
 ```
 
-The path must be relative to the working folder.
+Or use the `JEKYLL_NOTION_CACHE` environment variable:
 
-#### Cleaning cache
+```bash
+export JEKYLL_NOTION_CACHE=false  # or 0, no
+```
 
-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.
+## Sensitive data
 
-#### Disabling cache
+The cache stores full request and response payloads from the Notion API.
+This may include sensitive information such as authentication tokens, URLs, or private content.
 
-If you're not interested in the cache or you just want to disable it, set the ˋcache` option to false.
+If you intend to store cached files in version control or share them with others, be mindful of what they contain.
+By default, jekyll-notion automatically redacts the `NOTION_TOKEN` from all cache files.
+If you need to mask additional values, you can configure [VCR filters](https://benoittgt.github.io/vcr/#/configuration/filter_sensitive_data?id=filter-sensitive-data).
 
-```yaml
-notion:
-  cache: false
+For example, add a file `_plugins/vcr_config.rb`:
+
+```ruby
+VCR.configure do |config|
+  # Already handled by jekyll-notion: NOTION_TOKEN
+  # Example of masking a custom header or property:
+  config.filter_sensitive_data("[MASKED]") do |interaction|
+    interaction.request.headers["User-Agent"]&.first
+  end
+end
 ```
 
+This file will be automatically picked up by Jekyll and merged into the VCR configuration provided by jekyll-notion.
+
+You can add filters for headers, query parameters, or any other values you don’t want exposed in the cache.
+
 ## Notion properties
 
-Notion page properties are set for each document in the front matter.
+Notion page properties are mapped into each Jekyll document's front
+matter.
 
-Please, refer to the [notion_to_md](https://github.com/emoriarty/notion_to_md/) gem to learn more.
+See the companion gem
+[notion_to_md](https://github.com/emoriarty/notion_to_md/) for details.
 
 ## Page filename
 
-There are two kinds of documents in Jekyll: posts and others.
+Jekyll distinguishes between **posts** and **other documents**:
+
+-   **Posts**: filenames follow the format
+    `YEAR-MONTH-DAY-title.MARKUP`, where the date comes from the Notion
+    `created_time` (or the `date` property if present).\
+-   **Other documents**: filenames are derived from the Notion page
+    title.
 
-When 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).
+## Testing
 
+Run the test suite:
+
+```bash
+bundle exec rspec                    # Run all tests
+bundle exec rspec spec/path/to/test  # Run specific test file
 ```
-YEAR-MONTH-DAY-title.MARKUP
+
+### Golden Files
+
+Tests use golden files to validate generated output against known-good snapshots. Update snapshots when expected output changes:
+
+```bash
+UPDATE_GOLDEN=1 bundle exec rspec
 ```
 
-The filename for any other document is the page title.

data/lib/jekyll-notion/cacheable.rb

@@ -1,33 +1,64 @@
 # frozen_string_literal: true
 
-#
+require_relative "cassette_manager"
 
 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,
-        }
+    class << self
+      def configure(cache_dir:, cache_enabled:)
+        @cache_dir = cache_dir
+        @cache_enabled = cache_enabled
+
+        configure_vcr
+      end
+
+      def cache_dir
+        # Always return VCR's configured directory to ensure consistency
+        # between CassetteManager operations and VCR cassette storage
+        VCR.configuration.cassette_library_dir
+      end
+
+      def enabled?
+        @cache_enabled
       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)
+      private
+
+      def configure_vcr
+        # Determine the directory to use based on configuration and environment
+        target_dir = @cache_dir || ENV["JEKYLL_NOTION_CACHE_DIR"] || File.join(Dir.pwd, ".cache",
+                                                                               "jekyll-notion", "vcr_cassettes")
+
+        VCR.configure do |config|
+          config.cassette_library_dir = target_dir
+          config.hook_into :faraday # Faraday is used by notion-ruby-client gem
+          config.filter_sensitive_data("<REDACTED>") { ENV.fetch("NOTION_TOKEN", nil) }
+          config.allow_http_connections_when_no_cassette = true
+          config.default_cassette_options = {
+            :allow_playback_repeats => true,
+            :record                 => :new_episodes,
+          }
+        end
       end
     end
 
-    def generate(*args)
-      VCR.use_cassette(resource_id) { super(*args) }
+    def call
+      return super unless JekyllNotion::Cacheable.enabled?
+
+      cassette_manager = CassetteManager.new(JekyllNotion::Cacheable.cache_dir)
+      cassette_name = cassette_manager.cassette_name_for(id)
+      result = nil
+
+      VCR.use_cassette(
+        cassette_name,
+        :record                 => :new_episodes,
+        :allow_playback_repeats => true
+      ) do
+        result = super
+      end
+
+      cassette_manager.update_after_call(id, result)
+      result
     end
   end
 end

data/lib/jekyll-notion/cassette_manager.rb

@@ -0,0 +1,107 @@
+# frozen_string_literal: true
+
+require "yaml"
+require "fileutils"
+
+module JekyllNotion
+  class CassetteManager
+    INDEX_BASENAME = ".pages_index.yml"
+    PAGES_DIR = "pages"
+
+    def initialize(cache_dir)
+      @cache_dir = cache_dir
+    end
+
+    def cassette_name_for(id)
+      sanitized_id = sanitize_id(id)
+
+      # a) index mapping wins
+      if (pretty = load_index_yaml[sanitized_id]) && File.exist?(cassette_path(pretty))
+        return pretty
+      end
+
+      # b) any existing "*-id.yml" (handles prior runs / title changes)
+      if (found = find_existing_by_id(sanitized_id))
+        return found
+      end
+
+      # c) fallback to plain id (first run)
+      "#{PAGES_DIR}/#{sanitized_id}"
+    end
+
+    def update_after_call(id, result)
+      return unless (title = extract_title(result)).to_s != ""
+
+      sanitized_id = sanitize_id(id)
+      current_cassette = cassette_name_for(sanitized_id)
+      pretty_name = "#{PAGES_DIR}/#{sanitize_title(title)}-#{sanitized_id}"
+
+      rename_cassette_if_needed(:from => current_cassette, :to => pretty_name)
+      update_index_yaml(:id => sanitized_id, :pretty => pretty_name)
+    end
+
+    private
+
+    attr_reader :cache_dir
+
+    def cassette_path(name)
+      File.join(cache_dir, "#{name}.yml")
+    end
+
+    def find_existing_by_id(id)
+      matches = Dir[File.join(cache_dir, "pages", "*-#{id}.yml")]
+      return nil if matches.empty?
+
+      File.join(PAGES_DIR, File.basename(matches.first, ".yml"))
+    end
+
+    def rename_cassette_if_needed(from:, to:)
+      return if from == to
+
+      src = cassette_path(from)
+      dst = cassette_path(to)
+      return unless File.exist?(src)
+      return if File.exist?(dst)
+
+      FileUtils.mkdir_p(File.dirname(dst))
+      FileUtils.mv(src, dst)
+    rescue SystemCallError
+      nil
+    end
+
+    def index_path
+      File.join(cache_dir, INDEX_BASENAME)
+    end
+
+    def load_index_yaml
+      return {} unless File.exist?(index_path)
+
+      YAML.safe_load(File.read(index_path), :permitted_classes => [], :aliases => false) || {}
+    rescue Psych::SyntaxError
+      {}
+    end
+
+    def update_index_yaml(id:, pretty:)
+      idx = load_index_yaml
+      return if idx[id] == pretty
+
+      FileUtils.mkdir_p(File.dirname(index_path))
+      tmp = "#{index_path}.tmp"
+      idx[id] = pretty
+      File.write(tmp, idx.to_yaml)
+      FileUtils.mv(tmp, index_path)
+    end
+
+    def sanitize_title(str)
+      Jekyll::Utils.slugify(str)
+    end
+
+    def sanitize_id(id)
+      id.delete("-")
+    end
+
+    def extract_title(metadata)
+      metadata.title
+    end
+  end
+end