jekyll-notion-cms 1.0.1 → 1.0.3

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 68a78b984aaaa3dddb7132d791884c84b01698e2c0f2b49c3333e2637e83e67f
-  data.tar.gz: 2d83bc41a51f82b90c8dd9fc6a76be86eb35ea627d0aa74d9be67381868bb792
+  metadata.gz: 33cff8a4d2a08b099224d2db5605438b6a49e3a87c83b1d18f3679d19def3a31
+  data.tar.gz: 6efe8bd404d78a1816e0f4ed5f0cfa4dbc0f2820d3bc363996ae8e3d82bdd7f9
 SHA512:
-  metadata.gz: c390711580fc795641e3392babe4c73e078c0b909492797f7650fa7bf66608b2d6c88c51cb07c23e71f843e3c39305f5d69119516e66289dfde9201a90ff54ae
-  data.tar.gz: 9afbc03649b5f2d6359d7d0c4670edc2eb06ae630542e0e5d9bfee536241b2e97c8c24e3dc63e04842b5b2ef91b0b91cfa35d88f9cc5b74ce49ed9576a859a0f
+  metadata.gz: 24a0b92c12b7f0c2fce898067cbee813d9dbd087697e11a769342f51d8698760aacd2f9d4fc5328641d198e7e5d57f6c4e160a90892eb6cfea760382f8166296
+  data.tar.gz: 5c87441340d94046ec3745bc92d20fdb6c4517f0835e7736b45751fc984b616dcfd083f43b887ef0017348511b3432acc08639ec142098a742231b1b7923c14b

data/CHANGELOG.md

@@ -5,6 +5,28 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [1.0.3] - 2026-09-27
+
+### Fixed
+
+- `items_by_category` adds an item related to several categories to each of them
+  - Before, the item was filed under a merged category such as `["Backend", "Frontend"]`
+  - Each category takes its own icon, color and order from the rollups
+- Unchanged empty collections are no longer rewritten on every build
+  - An empty collection dumps to a single line (`--- []`) that the previous check missed,
+    which made `jekyll serve` regenerate in a loop
+- The fallback keeps data files imported from Notion instead of overwriting them
+  - Without `NOTION_TOKEN`, or when a database cannot be fetched, the last Notion data stays in `_data/`
+  - Files written by the fallback now say so in their header, and are still regenerated
+  - Delete a data file to rebuild it from the Jekyll collection
+
+## [1.0.2] - 2026-01-26
+
+### Fixed
+
+- Category order now correctly handles array values from rollup properties
+  - Fixes sorting of categories when `Category Order` returns an array instead of a single value
+
 ## [1.0.1] - 2026-01-22
 
 ### Fixed
@@ -42,5 +64,6 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 - Secure handling of Notion API tokens via environment variables
 
+[1.0.2]: https://github.com/maxime-lenne/jekyll-notion-cms/releases/tag/v1.0.2
 [1.0.1]: https://github.com/maxime-lenne/jekyll-notion-cms/releases/tag/v1.0.1
 [1.0.0]: https://github.com/maxime-lenne/jekyll-notion-cms/releases/tag/v1.0.0

data/docs/EXAMPLES_AND_CONFIGURATION.md

@@ -214,15 +214,19 @@ notion:
 
 Showcase your technical expertise.
 
-**Notion Database Structure:**
+**Notion Database Structure** (`items_by_category` reads these exact property names — see
+[`items_by_category`](#organizer-types) for details):
 
 | Property | Type | Description |
 |----------|------|-------------|
 | Name | Title | Skill name |
-| Category | Select | Skill category (Backend, Frontend, etc.) |
-| Level | Select/Number | Proficiency level |
-| Icon | Rich text | Icon class or URL |
+| Category | Rollup | Category name, rolled up from a related Categories database |
+| Icon | Rollup | Category icon, rolled up from Categories |
+| Color | Rollup | Skill color |
+| Category Order | Rollup | Category display order, rolled up from Categories |
+| Level | Number | Proficiency level |
 | Years | Number | Years of experience |
+| Featured | Checkbox | Highlight this skill |
 | Order | Number | Display order within category |
 
 **Configuration:**
@@ -234,15 +238,6 @@ notion:
       database_env: NOTION_SKILLS_DB
       data_file: notion_skills.yml
       organizer: items_by_category
-      properties:
-        - { name: Name, type: title }
-        - { name: Category, type: rollup }
-        - { name: Level, type: number }
-        - { name: Icon, type: rich_text }
-        - { name: Years, type: number }
-        - { name: Order, type: number }
-        - { name: Category Icon, type: rollup, key: category_icon }
-        - { name: Category Order, type: rollup, key: category_order }
 ```
 
 **Template Usage:**
@@ -256,8 +251,11 @@ notion:
     </h3>
     <div class="skills-grid">
       {% for item in category[1].items %}
-        <div class="skill">
-          <span class="skill-name">{{ item.name }}</span>
+        <div class="skill" style="--skill-color: {{ item.color }}">
+          <span class="skill-name">
+            {{ item.name }}
+            {% if item.featured %}<span class="badge">★</span>{% endif %}
+          </span>
           <div class="skill-bar">
             <div class="skill-level" style="width: {{ item.level }}%"></div>
           </div>
@@ -305,16 +303,43 @@ Groups items by their category. Useful for skills, products, team members, or an
 organizer: items_by_category
 ```
 
+> **Note:** unlike the other organizers, `items_by_category` does **not** use the `properties:`
+> list — it reads a fixed set of property names directly from each page. Your database must use
+> these exact names:
+>
+> | Property | Type | Used for |
+> |----------|------|----------|
+> | `Name` | Title | Item name |
+> | `Category` | Rollup | Category name (groups items together) |
+> | `Icon` | Rollup | Category icon |
+> | `Color` | Rollup | Item color |
+> | `Category Order` | Rollup | Category display order |
+> | `Level` | Number | Item level |
+> | `Years` | Number | Item years |
+> | `Featured` | Checkbox | Item featured flag |
+> | `Order` | Number | Item display order within its category |
+>
+> `Category`, `Icon` and `Category Order` are typically rollups from a *Categories* database via
+> a relation field, so all items in the same category share the same icon/order.
+
 Output structure:
 ```yaml
 Backend:
   title: Backend
+  category: Backend
+  subcategory: null
   icon: code
   order: 1
   items:
     - name: Ruby
       level: 90
       years: 10
+      description: null
+      icon: null
+      color: blue
+      featured: true
+      order: 1
+      id: abc123
 ```
 
 #### `grouped_by`

data/docs/TASKS.md

@@ -0,0 +1,26 @@
+# Tasks
+
+## To do
+
+### Rollup with a single value returns a scalar instead of an array
+
+`PropertyExtractors.extract_rollup_array` returns the value alone when a rollup has one item, and an
+array otherwise (since 1.0.1). A property meant to be a list, such as the `Skills` of an experience,
+is then a string for items with a single skill.
+
+Templates that iterate with Liquid do not notice, but anything that expects an array breaks: for
+example `{{ experience.skills | jsonify }}` followed by `.map()` in JavaScript fails with
+`skills.slice(...).map is not a function`.
+
+**Proposal (1.1.0):** add an opt-in option on the property, so existing sites keep their behavior:
+
+```yaml
+properties:
+  - { name: Skills, type: rollup, array: true }
+```
+
+With `array: true`, the extractor always returns an array: `[]` when empty, `[value]` for a single
+value. Document it in the README and `docs/EXAMPLES_AND_CONFIGURATION.md`, and cover the three cases
+(empty, one value, several values) in `property_extractors_spec.rb`.
+
+A default change (always an array) would be a breaking change and belongs to 2.0.

data/lib/jekyll_notion_cms/data_organizers.rb

@@ -62,51 +62,99 @@ module JekyllNotionCMS
       items_by_category = {}
 
       notion_data['results'].each do |page|
-        properties = page['properties']
-
-        name = PropertyExtractors.extract(properties, 'Name', 'title')
-        next if name.nil? || name.empty?
-
-        level = PropertyExtractors.extract(properties, 'Level', 'number')
-        years = PropertyExtractors.extract(properties, 'Years', 'number')
-        featured = PropertyExtractors.extract(properties, 'Featured', 'checkbox')
-        order = PropertyExtractors.extract(properties, 'Order', 'number')
-        category_name = PropertyExtractors.extract(properties, 'Category', 'rollup') || 'Other'
-        category_icon = PropertyExtractors.extract(properties, 'Icon', 'rollup')
-        category_color = PropertyExtractors.extract(properties, 'Color', 'rollup')
-        category_order = PropertyExtractors.extract(properties, 'Category Order', 'rollup')
-
-        items_by_category[category_name] ||= {
-          'title' => category_name,
-          'category' => category_name,
-          'subcategory' => nil,
-          'icon' => category_icon,
-          'order' => category_order || 999,
-          'items' => []
-        }
+        process_category_page(page, items_by_category)
+      end
+
+      sort_categories_and_items(items_by_category)
+    end
+
+    # Process a single page for category organization
+    def process_category_page(page, items_by_category)
+      properties = page['properties']
+      name = PropertyExtractors.extract(properties, 'Name', 'title')
+      return if name.nil? || name.empty?
 
-        items_by_category[category_name]['items'] << {
-          'name' => name,
-          'level' => level,
-          'years' => years,
-          'description' => nil,
-          'icon' => nil,
-          'color' => category_color,
-          'featured' => featured,
-          'order' => order || 999,
-          'id' => page['id']
+      split_categories(extract_category_data(properties)).each do |category_data|
+        category_name = category_data[:name]
+
+        items_by_category[category_name] ||= build_category_hash(category_data)
+        items_by_category[category_name]['items'] << build_category_item(page, properties, name, category_data)
+      end
+    end
+
+    # An item related to several categories gets arrays from its rollups.
+    # Split them into one entry per category, pairing each name with its own icon, color and order.
+    def split_categories(category_data)
+      names = category_data[:name]
+      return [category_data] unless names.is_a?(Array) && names.size > 1
+
+      names.each_with_index.map do |category_name, index|
+        {
+          name: category_name,
+          icon: value_for_category(category_data[:icon], index, names.size),
+          color: value_for_category(category_data[:color], index, names.size),
+          order: value_for_category(category_data[:order], index, names.size)
         }
       end
+    end
+
+    # Rollups drop empty values, so an array only lines up with the categories when the sizes match
+    def value_for_category(value, index, category_count)
+      return value unless value.is_a?(Array)
+
+      value.size == category_count ? value[index] : nil
+    end
+
+    # Extract category-related data from properties
+    def extract_category_data(properties)
+      {
+        name: PropertyExtractors.extract(properties, 'Category', 'rollup') || 'Other',
+        icon: PropertyExtractors.extract(properties, 'Icon', 'rollup'),
+        color: PropertyExtractors.extract(properties, 'Color', 'rollup'),
+        order: PropertyExtractors.extract(properties, 'Category Order', 'rollup')
+      }
+    end
+
+    # Build the category hash structure
+    def build_category_hash(category_data)
+      order = category_data[:order]
+      {
+        'title' => category_data[:name],
+        'category' => category_data[:name],
+        'subcategory' => nil,
+        'icon' => category_data[:icon],
+        'order' => (order.is_a?(Array) ? order.first : order) || 999,
+        'items' => []
+      }
+    end
+
+    # Build an item hash for category organization
+    def build_category_item(page, properties, name, category_data)
+      {
+        'name' => name,
+        'level' => PropertyExtractors.extract(properties, 'Level', 'number'),
+        'years' => PropertyExtractors.extract(properties, 'Years', 'number'),
+        'description' => nil,
+        'icon' => nil,
+        'color' => category_data[:color],
+        'featured' => PropertyExtractors.extract(properties, 'Featured', 'checkbox'),
+        'order' => PropertyExtractors.extract(properties, 'Order', 'number') || 999,
+        'id' => page['id']
+      }
+    end
 
-      # Sort categories by order
-      items_by_category = items_by_category.sort_by { |_, data| data['order'].to_i }.to_h
+    # Sort categories and their items
+    def sort_categories_and_items(items_by_category)
+      sorted = items_by_category.sort_by do |_, data|
+        order = data['order']
+        (order.is_a?(Array) ? order.first : order).to_i
+      end.to_h
 
-      # Sort items within each category
-      items_by_category.each_value do |data|
+      sorted.each_value do |data|
         data['items'].sort_by! { |item| item['order'].to_i }
       end
 
-      items_by_category
+      sorted
     end
 
     # Organize items grouped by a field

data/lib/jekyll_notion_cms/generator.rb

@@ -9,6 +9,9 @@ module JekyllNotionCMS
     safe true
     priority :highest
 
+    NOTION_HEADER = 'data imported from Notion'
+    FALLBACK_HEADER = 'data generated from the Jekyll collection (Notion fallback)'
+
     def generate(site)
       @site = site
       @config = site.config['notion'] || {}
@@ -78,28 +81,22 @@ module JekyllNotionCMS
     end
 
     # Create a YAML data file
-    def create_data_file(data, file_name, collection_name)
+    # @param source [Symbol] :notion or :fallback, recorded in the header
+    def create_data_file(data, file_name, collection_name, source: :notion)
       data_dir = File.join(@site.source, '_data')
       FileUtils.mkdir_p(data_dir)
 
       data_file = File.join(data_dir, file_name)
       new_content = data.to_yaml
 
-      # Skip if content unchanged
-      if File.exist?(data_file)
-        existing_content = File.read(data_file)
-        yaml_start = existing_content.index("---\n")
-        if yaml_start
-          existing_yaml = existing_content[yaml_start..]
-          if existing_yaml.strip == new_content.strip
-            Jekyll.logger.info 'NotionCMS:', "#{collection_name} data unchanged, skipping"
-            return
-          end
-        end
+      if File.exist?(data_file) && yaml_body(File.read(data_file)) == new_content.strip
+        Jekyll.logger.info 'NotionCMS:', "#{collection_name} data unchanged, skipping"
+        return
       end
 
+      header = source == :fallback ? FALLBACK_HEADER : NOTION_HEADER
       File.open(data_file, 'w') do |file|
-        file.write("# #{collection_name.capitalize} data imported from Notion\n")
+        file.write("# #{collection_name.capitalize} #{header}\n")
         file.write("# Auto-generated by jekyll-notion-cms - Do not edit manually\n")
         file.write("# Last updated: #{Time.now.strftime('%Y-%m-%d %H:%M:%S')}\n\n")
         file.write(new_content)
@@ -108,6 +105,29 @@ module JekyllNotionCMS
       Jekyll.logger.info 'NotionCMS:', "#{collection_name} written to _data/#{file_name}"
     end
 
+    # YAML part of a data file, without the comment header.
+    # Works for single-line documents such as "--- []" that an empty collection produces.
+    def yaml_body(content)
+      content.lines.drop_while { |line| line.start_with?('#') || line.strip.empty? }.join.strip
+    end
+
+    # Without Notion, keep the last data imported from it: Jekyll already loaded the file into site.data
+    def keep_notion_data?(data_file, collection_name)
+      return false unless notion_data_file?(File.join(@site.source, '_data', data_file))
+
+      Jekyll.logger.info 'NotionCMS:', "Keeping Notion data in _data/#{data_file} for #{collection_name}"
+      true
+    end
+
+    # True when the file holds data imported from Notion rather than a previous fallback.
+    # Older versions wrote the Notion header for fallback data too, so also look for collection ids.
+    def notion_data_file?(data_file)
+      return false unless File.exist?(data_file)
+
+      content = File.read(data_file)
+      content.lines.first.to_s.include?(NOTION_HEADER) && !content.match?(/\bid: collection_\d+\b/)
+    end
+
     # Use fallback for all collections
     def use_all_collections_fallback
       @collections_config.each do |collection_name, config|
@@ -120,6 +140,9 @@ module JekyllNotionCMS
       Jekyll.logger.info 'NotionCMS:', "Using fallback for #{collection_name}"
 
       data_file = config['data_file']
+
+      return if keep_notion_data?(data_file, collection_name)
+
       data_key = data_file.sub('.yml', '').sub('.yaml', '')
       properties_config = config['properties'] || []
 
@@ -137,7 +160,7 @@ module JekyllNotionCMS
 
       organized_data = DataOrganizers.organize(mock_data, config)
       @site.data[data_key] = organized_data
-      create_data_file(organized_data, data_file, collection_name)
+      create_data_file(organized_data, data_file, collection_name, source: :fallback)
 
       count = organized_data.is_a?(Hash) ? organized_data.size : organized_data.length
       Jekyll.logger.info 'NotionCMS:', "#{collection_name} fallback applied (#{count} items)"

data/lib/jekyll_notion_cms/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module JekyllNotionCMS
-  VERSION = '1.0.1'
+  VERSION = '1.0.3'
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: jekyll-notion-cms
 version: !ruby/object:Gem::Version
-  version: 1.0.1
+  version: 1.0.3
 platform: ruby
 authors:
 - Maxime Lenne
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2026-01-22 00:00:00.000000000 Z
+date: 2026-09-26 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: jekyll
@@ -146,10 +146,9 @@ files:
 - Rakefile
 - docs/Download_on_the_App_Store_Badge_FR_RGB_wht_100217.svg
 - docs/EXAMPLES_AND_CONFIGURATION.md
+- docs/TASKS.md
 - docs/architecture.excalidraw
 - docs/architecture.png
-- docs/templates/architecture.excalidraw
-- docs/templates/architecture.png
 - docs/templates/github-actions_notion-sync.yml
 - docs/templates/n8n-workflow_Notion-database-change-trigger-GitHub-Actions.json
 - lib/jekyll-notion-cms.rb