jekyll-notion-cms 1.0.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 89eeb4c8a68356250340a7d9d5c5ecab86f0e48d82a2f79dfb25a8126e316204
+  data.tar.gz: 15c7213ec7bcb8d5178b0b237fd38d573fcc180060bd4c7b3ef43beed7c069a0
+SHA512:
+  metadata.gz: 3607b7445372d94c2e307a0a4e97b660d4df71ec910e5062297a1b3bad4579e8d24b611a4e92dcfd9adbf8a4a4090c4adc1342d938b2ccf425fe401b0c29c0bd
+  data.tar.gz: 726d1ad69582b93f779b97b3cca31fb642cdbfe04da56692fb4458ba77f398681f5ca270e15e07bb42179af6909060e21612a4202e2fa734f4f398ed409c0138

data/.rspec

@@ -0,0 +1,3 @@
+--format documentation
+--color
+--require spec_helper

data/.rubocop.yml

@@ -0,0 +1,87 @@
+require:
+  - rubocop-rspec
+
+AllCops:
+  TargetRubyVersion: 2.7
+  NewCops: enable
+  SuggestExtensions: false
+  Exclude:
+    - 'vendor/**/*'
+    - 'spec/fixtures/**/*'
+
+# Naming
+Naming/FileName:
+  Exclude:
+    - 'lib/jekyll-notion-cms.rb'
+
+# Gemspec
+Gemspec/DevelopmentDependencies:
+  Enabled: false
+
+# Metrics
+Metrics/AbcSize:
+  Max: 35
+
+Metrics/BlockLength:
+  Max: 35
+  Exclude:
+    - 'spec/**/*'
+    - '*.gemspec'
+
+Metrics/MethodLength:
+  Max: 45
+
+Metrics/ClassLength:
+  Max: 200
+
+Metrics/ModuleLength:
+  Max: 250
+
+Metrics/CyclomaticComplexity:
+  Max: 25
+
+Metrics/PerceivedComplexity:
+  Max: 12
+
+# Style
+Style/Documentation:
+  Enabled: false
+
+Style/StringLiterals:
+  EnforcedStyle: single_quotes
+
+Style/FrozenStringLiteralComment:
+  Enabled: true
+
+# Layout
+Layout/LineLength:
+  Max: 120
+  Exclude:
+    - 'spec/**/*'
+
+# Lint
+Lint/DuplicateBranch:
+  Enabled: false
+
+# RSpec
+RSpec/ExampleLength:
+  Max: 25
+
+RSpec/MultipleExpectations:
+  Max: 5
+
+RSpec/NestedGroups:
+  Max: 4
+
+RSpec/MultipleMemoizedHelpers:
+  Max: 10
+
+RSpec/MessageSpies:
+  Enabled: false
+
+RSpec/IndexedLet:
+  Enabled: false
+
+# Capybara
+Capybara/RSpec/PredicateMatcher:
+  Enabled: false

data/CHANGELOG.md

@@ -0,0 +1,48 @@
+# Changelog
+
+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).
+
+## [Unreleased]
+
+### Changed
+
+- **BREAKING**: Renamed `skills_by_category` organizer to `items_by_category` for more generic usage
+- **BREAKING**: Output key `skills` renamed to `items` in `items_by_category` organizer
+
+### Added
+
+- Documentation: use cases, examples (projects, services, testimonials, skills)
+- Documentation: automation section with GitHub Actions and n8n workflow templates
+- Architecture diagram
+
+## [1.0.0] - 2026-01-21
+
+### Added
+
+- Initial release of jekyll-notion-cms
+- Configurable collections via `_config.yml`
+- Support for multiple Notion property types:
+  - Title, Rich text, Number, Checkbox
+  - Date, Select, Multi-select, URL
+  - Email, Phone number, Files
+  - Rollup, Formula, Relation
+  - People, Status, Created/Last edited time
+- Multiple data organizers:
+  - `simple_list` - Sorted array of items
+  - `items_by_category` - Items grouped by category (skills, products, etc.)
+  - `grouped_by` - Items grouped by a field
+  - `nested` - Hierarchical tree structure
+- Automatic fallback to Jekyll collections
+- Pagination support for large databases
+- Data file caching to avoid unnecessary regeneration
+- Comprehensive logging
+
+### Security
+
+- Secure handling of Notion API tokens via environment variables
+
+[Unreleased]: https://github.com/maxime-lenne/jekyll-notion-cms/compare/v1.0.0...HEAD
+[1.0.0]: https://github.com/maxime-lenne/jekyll-notion-cms/releases/tag/v1.0.0

data/Gemfile

@@ -0,0 +1,10 @@
+# frozen_string_literal: true
+
+source 'https://rubygems.org'
+
+# Specify your gem's dependencies in jekyll-notion-cms.gemspec
+gemspec
+
+group :development do
+  gem 'pry', '~> 0.14'
+end

data/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024-2026 Maxime Lenne
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

data/README.md

@@ -0,0 +1,362 @@
+# Jekyll Notion CMS
+
+<p align="center">
+  <img src="https://cdn.jsdelivr.net/gh/devicons/devicon/icons/notion/notion-original.svg" alt="Notion" width="80" height="80" />
+  <img src="https://cdn.jsdelivr.net/gh/devicons/devicon/icons/jekyll/jekyll-original.svg" alt="Jekyll" width="80" height="80" />
+  <img src="https://upload.vectorlogo.zone/logos/n8nio/images/b751b1e9-f500-4b33-b8b1-3b8126059c0c.svg" alt="n8n" width="80" height="80" />
+  <img src="https://cdn.jsdelivr.net/gh/devicons/devicon/icons/githubactions/githubactions-original-wordmark.svg" alt="Github Action" width="80" height="80" />
+</p>
+
+<p align="center">
+  <strong>Use Notion as a CMS for your Jekyll static site</strong>
+</p>
+
+<p align="center">
+  <a href="https://badge.fury.io/rb/jekyll-notion-cms"><img src="https://badge.fury.io/rb/jekyll-notion-cms.svg" alt="Gem Version" /></a>
+  <a href="https://github.com/maxime-lenne/jekyll-notion-cms/actions/workflows/ci.yml"><img src="https://github.com/maxime-lenne/jekyll-notion-cms/actions/workflows/ci.yml/badge.svg" alt="CI" /></a>
+  <a href="https://opensource.org/licenses/MIT"><img src="https://img.shields.io/badge/License-MIT-yellow.svg" alt="License: MIT" /></a>
+</p>
+
+---
+
+A configurable Jekyll plugin that fetches content from Notion databases and makes it available as Jekyll data files. Perfect for building landing pages, portfolios, blogs, and resumes with Notion as your content management system.
+
+## Features
+
+- **Configurable Collections**: Define any number of Notion database collections via `_config.yml`
+- **Multiple Organizers**: Support for different data organization patterns (simple list, grouped, skills by category, nested)
+- **All Property Types**: Support for all Notion property types (text, number, date, select, multi-select, relations, rollups, formulas, files, etc.)
+- **Fallback System**: Automatic fallback to Jekyll collections when Notion is unavailable
+- **Pagination**: Handles large databases with automatic pagination
+- **Caching**: Intelligent file caching to avoid unnecessary regenerations
+
+
+## Architecture
+
+<p align="center">
+  <img src="docs/architecture.png" alt="Jekyll Notion CMS Architecture" width="800" />
+</p>
+
+The diagram above shows how Jekyll Notion CMS integrates with your workflow:
+
+1. **Content editing** in Notion databases
+2. **Change detection** via n8n polling or webhooks
+3. **Build trigger** through GitHub Actions workflow_dispatch
+4. **Static site generation** with Jekyll + jekyll-notion-cms
+5. **Deployment** to GitHub Pages (or any static host)
+
+## Use Cases
+
+### Landing Page
+
+Build dynamic landing pages with content managed entirely in Notion:
+
+| Content Type | Notion Database | Description |
+|--------------|-----------------|-------------|
+| **Services** | Services DB | List your offerings with icons, descriptions, and pricing |
+| **Testimonials** | Testimonials DB | Client reviews with photos, quotes, and ratings |
+| **Team** | Team DB | Team member profiles with photos and bios |
+| **FAQ** | FAQ DB | Frequently asked questions organized by category |
+
+### Portfolio
+
+Showcase your work with a portfolio powered by Notion:
+
+| Content Type | Notion Database | Description |
+|--------------|-----------------|-------------|
+| **Projects** | Projects DB | Portfolio pieces with images, descriptions, and links |
+| **Skills** | Skills DB | Technical skills organized by category with proficiency levels |
+| **Certifications** | Certifications DB | Professional certifications and badges |
+
+### Blog
+
+Run a full-featured blog with Notion as your writing tool:
+
+| Content Type | Notion Database | Description |
+|--------------|-----------------|-------------|
+| **Posts** | Blog DB | Articles with rich text, tags, and publication dates |
+| **Categories** | Categories DB | Blog categories for organization |
+| **Authors** | Authors DB | Author profiles for multi-author blogs |
+
+### Resume / CV
+
+Create a dynamic online resume:
+
+| Content Type | Notion Database | Description |
+|--------------|-----------------|-------------|
+| **Experiences** | Experiences DB | Work history with dates, companies, and descriptions |
+| **Education** | Education DB | Academic background and degrees |
+| **Skills** | Skills DB | Technical and soft skills with proficiency |
+| **Languages** | Languages DB | Language proficiencies |
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+```ruby
+gem 'jekyll-notion-cms'
+```
+
+And then execute:
+
+```bash
+bundle install
+```
+
+Or install it yourself as:
+
+```bash
+gem install jekyll-notion-cms
+```
+
+## Quick Start
+
+### 1. Set up your Notion Integration
+
+1. Go to [Notion Developers](https://www.notion.so/my-integrations)
+2. Create a new integration
+3. Copy the Internal Integration Token
+4. Share your Notion databases with the integration
+
+### 2. Configure Environment Variables
+
+```bash
+export NOTION_TOKEN=secret_xxx
+export NOTION_EXPERIENCES_DB=your_database_id
+export NOTION_BLOG_DB=your_blog_database_id
+```
+
+### 3. Add Configuration to `_config.yml`
+
+```yaml
+notion:
+  enabled: true
+
+  collections:
+    experiences:
+      database_env: NOTION_EXPERIENCES_DB
+      data_file: notion_experiences.yml
+      organizer: simple_list
+      sort_by: order
+      properties:
+        - { name: Title, type: title }
+        - { name: Company, type: rich_text }
+        - { name: Start Date, type: date, key: start_date }
+        - { name: Current, type: checkbox }
+        - { name: Tags, type: multi_select }
+
+    blog_posts:
+      database_env: NOTION_BLOG_DB
+      data_file: notion_blog_posts.yml
+      organizer: simple_list
+      sort_by: published_at
+      sort_order: desc
+      properties:
+        - { name: Title, type: title }
+        - { name: Slug, type: rich_text }
+        - { name: Language, type: select }
+        - { name: Published At, type: date, key: published_at }
+        - { name: Status, type: select }
+        - { name: Excerpt, type: rich_text }
+        - { name: Tags, type: multi_select }
+```
+
+### 4. Use Data in Templates
+
+```liquid
+{% for exp in site.data.notion_experiences %}
+  <h3>{{ exp.title }}</h3>
+  <p>{{ exp.company }} - {{ exp.start_date }}</p>
+{% endfor %}
+```
+
+## Examples & Configuration
+
+For detailed examples and configuration reference, see **[Examples & Configuration](docs/EXAMPLES_AND_CONFIGURATION.md)**.
+
+**Examples included:**
+- Projects Database (portfolio, case studies)
+- Services Database (freelancers, agencies)
+- Testimonials Database (client reviews)
+- Skills Database (technical expertise)
+
+**Configuration reference:**
+- Collection options
+- Organizer types (`simple_list`, `items_by_category`, `grouped_by`, `nested`)
+- All 18 property types supported
+- Property configuration syntax
+
+## Fallback System
+
+When Notion is unavailable, the plugin automatically falls back to Jekyll collections:
+
+1. **No `NOTION_TOKEN`**: Uses all Jekyll collections
+2. **Missing database ID**: Uses fallback for that collection
+3. **API Error**: Falls back gracefully with error logging
+
+Create fallback collections in `_collections/`:
+
+```
+_collections/
+├── _experiences/
+│   ├── experience-1.md
+│   └── experience-2.md
+└── _blog_posts/
+    └── my-post.md
+```
+
+## Automation & Deployment
+
+### GitHub Actions Workflow
+
+Copy the workflow template to your repository:
+
+```bash
+cp docs/templates/github-actions_notion-sync.yml .github/workflows/notion-sync.yml
+```
+
+**Full workflow file:** [`docs/templates/github-actions_notion-sync.yml`](docs/templates/github-actions_notion-sync.yml)
+
+```yaml
+name: Notion Sync Workflow
+
+on:
+  workflow_dispatch:
+    inputs:
+      notion_event:
+        description: 'Type of Notion event'
+        required: true
+        type: string
+      page_id:
+        description: 'Notion page ID'
+        required: true
+        type: string
+      database_id:
+        description: 'Notion database ID'
+        required: true
+        type: string
+      updated_at:
+        description: 'Last update timestamp'
+        required: true
+        type: string
+
+permissions:
+  contents: read
+  pages: write
+  id-token: write
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Setup Ruby
+        uses: ruby/setup-ruby@v1
+        with:
+          ruby-version: '3.3'
+          bundler-cache: true
+
+      - name: Build with Jekyll
+        run: bundle exec jekyll build
+        env:
+          JEKYLL_ENV: production
+          NOTION_TOKEN: ${{ secrets.NOTION_TOKEN }}
+          NOTION_SKILLS_DB: ${{ secrets.NOTION_SKILLS_DB }}
+          NOTION_EXPERIENCES_DB: ${{ secrets.NOTION_EXPERIENCES_DB }}
+          NOTION_BLOG_DB: ${{ secrets.NOTION_BLOG_DB }}
+          # Add more database secrets as needed
+
+      - name: Upload artifact
+        uses: actions/upload-pages-artifact@v3
+
+  deploy:
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+    runs-on: ubuntu-latest
+    needs: build
+    steps:
+      - name: Deploy to GitHub Pages
+        id: deployment
+        uses: actions/deploy-pages@v4
+```
+
+### Automatic Sync with n8n
+
+
+Use [n8n](https://n8n.io) to automatically trigger builds when Notion content changes.
+
+**Import the workflow template:** [`docs/templates/n8n-workflow_Notion-database-change-trigger-GitHub-Actions.json`](docs/templates/n8n-workflow_Notion-database-change-trigger-GitHub-Actions.json)
+
+**Workflow steps:**
+
+1. **Notion Trigger** - Polls Notion database for changes (configurable interval)
+2. **GitHub Action** - Triggers `workflow_dispatch` event on your repository
+3. **Notification** (optional) - Sends Telegram/Slack message on deployment
+
+**n8n Configuration:**
+
+| Node | Configuration |
+|------|---------------|
+| Notion Trigger | Database ID, poll interval (e.g., every hour) |
+| GitHub | Repository owner, repo name, workflow ID, branch |
+| Telegram/Slack | Chat ID for notifications (optional) |
+
+**Required credentials:**
+- Notion API integration token
+- GitHub Personal Access Token (with `repo` and `workflow` scopes)
+
+### Manual Trigger
+
+You can also trigger the workflow manually via GitHub CLI:
+
+```bash
+gh workflow run notion-sync.yml \
+  -f notion_event=manual \
+  -f page_id=none \
+  -f database_id=all \
+  -f updated_at=$(date -u +"%Y-%m-%dT%H:%M:%SZ")
+```
+
+Or via the GitHub Actions UI by clicking "Run workflow" on the Actions tab.
+
+## Development
+
+After checking out the repo:
+
+```bash
+# Install dependencies
+bundle install
+
+# Run tests
+bundle exec rspec
+
+# Run linter
+bundle exec rubocop
+
+# Run console
+bundle exec rake console
+```
+
+## Contributing
+
+Bug reports and pull requests are welcome on GitHub at https://github.com/maxime-lenne/jekyll-notion-cms.
+
+1. Fork it
+2. Create your feature branch (`git checkout -b feature/my-feature`)
+3. Commit your changes (`git commit -am 'Add my feature'`)
+4. Push to the branch (`git push origin feature/my-feature`)
+5. Create a Pull Request
+
+## License
+
+The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).
+
+## Author
+
+**Maxime Lenne** - [maxime-lenne.fr](https://maxime-lenne.fr)
+
+- GitHub: [@maxime-lenne](https://github.com/maxime-lenne)
+- LinkedIn: [maximelenne](https://linkedin.com/in/maximelenne)

data/Rakefile

@@ -0,0 +1,26 @@
+# frozen_string_literal: true
+
+require 'bundler/gem_tasks'
+require 'rspec/core/rake_task'
+require 'rubocop/rake_task'
+
+RSpec::Core::RakeTask.new(:spec)
+RuboCop::RakeTask.new
+
+task default: %i[spec rubocop]
+
+desc 'Run all tests and linters'
+task ci: %i[spec rubocop]
+
+desc 'Build and install gem locally'
+task :install_local do
+  sh 'gem build jekyll-notion-cms.gemspec'
+  sh 'gem install jekyll-notion-cms-*.gem'
+end
+
+desc 'Run console with gem loaded'
+task :console do
+  require 'pry'
+  require_relative 'lib/jekyll-notion-cms'
+  Pry.start
+end