bridgetown_directus 0.2.0 → 0.4.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: dd3625cab0b39f5374ad7a3647e5b6e369bed783f05412cb38e15e8f10208908
-  data.tar.gz: a99f097216b2c9239188563a288b0df5752709782c29bfe15673edd73fd6c80d
+  metadata.gz: 2212f8e06630de61f4abdc8f50fb65339d3928e9a39e6658fd16f5af37986fdd
+  data.tar.gz: 2e02c25a8dcf030d9497caab17a1970c1170151ef777c26538ef2d0f47fb06c2
 SHA512:
-  metadata.gz: d70b609eab2f9c4015c4e8898324fe046f8a62673c51d11057ec166372cceb7dfc3cba9793b1a37e3dd175f150d1d2dbc2c7c371427e740b61303630228793f0
-  data.tar.gz: 1dafe4be86342c4196ca93700035ad75f99b0a6a7d0ab78f0592f8ec0a76e51a223b7b63a7f46bf1b0568593b8322b0428f95e5329f38788c55d0a9b07907a9a
+  metadata.gz: 8843466b19c819f8f8cbc3e36188524f4f46774f95ee79b9cd4b2042fd39a38a640accc54addae8666e0249384619ec23ea3c2379daf5d91c0085f3e8019009a
+  data.tar.gz: bc119472aa06bfebf3a09357f622224248f4405b5f5bb8d895c215e71b4ddff7d7be2064eac98940dc3c8ebf6857d617ec6529004b7f4cd5da8430930917c73c

data/.github/workflows/ci.yml

@@ -0,0 +1,23 @@
+name: CI
+
+on:
+  push:
+    branches:
+      - main
+  pull_request:
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: ruby/setup-ruby@v1
+        with:
+          ruby-version: "3.4"
+          bundler-cache: true
+      - name: Run tests
+        run: bundle exec rake test

data/.github/workflows/release-please.yml

@@ -0,0 +1,21 @@
+name: Release Please
+
+on:
+  push:
+    branches:
+      - main
+  workflow_dispatch:
+
+permissions:
+  contents: write
+  pull-requests: write
+
+jobs:
+  release-please:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: googleapis/release-please-action@v4
+        with:
+          token: ${{ secrets.RELEASE_PLEASE_TOKEN }}
+          config-file: .release-please-config.json
+          manifest-file: .release-please-manifest.json

data/.github/workflows/release.yml

@@ -0,0 +1,28 @@
+name: Release
+
+on:
+  push:
+    tags:
+      - "bridgetown_directus/v*"
+  workflow_dispatch:
+
+permissions:
+  contents: read
+  id-token: write
+
+jobs:
+  publish:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: ruby/setup-ruby@v1
+        with:
+          ruby-version: "3.4"
+          bundler-cache: true
+      - name: Run tests
+        run: bundle exec rake test
+      - name: Build gem
+        run: bundle exec rake build
+      - uses: rubygems/configure-rubygems-credentials@v1.0.0
+      - name: Push gem
+        run: gem push pkg/*.gem

data/.gitignore

@@ -38,3 +38,6 @@ test/dest
 .bridgetown-webpack
 
 .env
+
+# MacOS
+.DS_Store

data/.release-please-config.json

@@ -0,0 +1,10 @@
+{
+  "packages": {
+    ".": {
+      "release-type": "ruby",
+      "package-name": "bridgetown_directus",
+      "changelog-path": "CHANGELOG.md",
+      "include-v-in-tag": true
+    }
+  }
+}

data/.release-please-manifest.json

@@ -0,0 +1,3 @@
+{
+  ".": "0.4.1"
+}

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).
 
+## [0.4.1](https://github.com/Munkun-Estudio/bridgetown_directus/compare/bridgetown_directus/v0.4.0...bridgetown_directus/v0.4.1) (2026-02-16)
+
+
+### Bug Fixes
+
+* match release-please tag format in release workflow ([70bd081](https://github.com/Munkun-Estudio/bridgetown_directus/commit/70bd08125477acb33f10e06de5fd41ba889d472a))
+
+## [0.4.0](https://github.com/Munkun-Estudio/bridgetown_directus/compare/bridgetown_directus/v0.3.0...bridgetown_directus/v0.4.0) (2026-02-16)
+
+
+### Features
+
+* add data collections, singleton support, flatten_m2m, and BridgetownDirectus.configure API ([31e99ac](https://github.com/Munkun-Estudio/bridgetown_directus/commit/31e99ac31463b944d20de1e81931219d2c0de59a))
+* make SSL verify configurable via Configuration#ssl_verify ([6cb9033](https://github.com/Munkun-Estudio/bridgetown_directus/commit/6cb90331b0b2e99bd26ecde862c26d6969b0fbf6))
+
+## [0.3.0](https://github.com/Munkun-Estudio/bridgetown_directus/compare/bridgetown_directus-v0.2.0...bridgetown_directus/v0.3.0) (2026-01-27)
+
+
+### Features
+
+* improve builder mapping and release automation ([b87c719](https://github.com/Munkun-Estudio/bridgetown_directus/commit/b87c719cfec175a86bc1f9388c308c496035d2cf))
+
 ## [Unreleased]
 
 - ...

data/README.md

@@ -2,117 +2,223 @@
 
 [![Gem Version](https://badge.fury.io/rb/bridgetown_directus.svg)](https://badge.fury.io/rb/bridgetown_directus)
 
-This Bridgetown plugin integrates with [Directus](https://directus.io/), a flexible headless CMS. The plugin allows Bridgetown to pull content from a Directus API during the build process and generate static content in your site. It supports both single-language and multilingual content through Directus translations.
+A [Bridgetown](https://www.bridgetownrb.com/) plugin that syncs content from [Directus](https://directus.io/) at build time. It fetches collections from the Directus API and either generates static Markdown files or injects data directly into `site.data`.
 
 ## Features
 
-- Fetch content from **multiple Directus collections** during the build process
-- Support for **flexible field mapping** and custom converters
-- Support for **multilingual content** via Directus translations
-- **Experimental**: Advanced **filtering, sorting, and pagination** options
-- Simple configuration for any Bridgetown collection (posts, pages, or custom types)
+- **Output collections** — fetch Directus items and generate Markdown files (posts, pages, custom types)
+- **Data collections** — fetch Directus items and inject into `site.data` (no file generation)
+- **Singletons** — single-object collections (e.g. site settings)
+- **M2M junction flattening** — unwrap Directus many-to-many junction objects automatically
+- **Flexible field mapping** with custom converters
+- **Multilingual content** via Directus translations
+- **Configurable SSL verification** for environments with strict OpenSSL
+- **Graceful skip** — build succeeds even without Directus credentials configured
 
 ## Installation
 
-Before installing the plugin, make sure you have an [Auth Token](https://docs.directus.io/reference/authentication.html#access-tokens) in your Directus instance.
+### Recommended (Bridgetown Automation)
 
-### Recommended Installation (Bridgetown Automation)
+```bash
+bin/bridgetown apply https://github.com/munkun-estudio/bridgetown_directus
+```
 
-1. Run the plugin's automation setup:
+### Manual
 
-   ```bash
-   bin/bridgetown apply https://github.com/munkun-estudio/bridgetown_directus
-   ```
+```ruby
+bundle add "bridgetown_directus"
+```
 
-   This will:
-   - Prompt for your Directus API URL, token, Directus collection name, and Bridgetown collection name
-   - Generate a minimal `config/initializers/bridgetown_directus.rb`
-   - All further customization is done in Ruby, not YAML
+```bash
+bundle install
+```
 
-### Manual Installation
+## Configuration
 
-1. Add the gem to your Gemfile:
+### Basic Setup
 
-   ```ruby
-   bundle add "bridgetown_directus"
-   ```
+```ruby
+# config/initializers.rb
+init :bridgetown_directus
 
-2. Run `bundle install` to install the gem.
-3. Create `config/initializers/bridgetown_directus.rb` (see below for configuration).
+BridgetownDirectus.configure do |directus|
+  directus.api_url = ENV["DIRECTUS_API_URL"]
+  directus.token   = ENV["DIRECTUS_API_TOKEN"]
 
-## Configuration
+  directus.register_collection(:posts) do |c|
+    c.endpoint = "blog_posts"
+    c.layout   = "post"
+  end
+end
+```
+
+The plugin reads `DIRECTUS_API_URL` and `DIRECTUS_API_TOKEN` from the environment by default. If neither is set, the build skips Directus sync gracefully.
 
-### Minimal Example
+### Data Collections
+
+Data collections populate `site.data` without generating files. Useful for navigation, settings, or any shared data.
 
 ```ruby
-# config/initializers/bridgetown_directus.rb
-init :bridgetown_directus do |directus|
-  directus.api_url = ENV["DIRECTUS_API_URL"] || "https://your-directus-instance.com"
-  directus.token = ENV["DIRECTUS_API_TOKEN"] || "your-token"
+directus.register_collection(:navigation) do |c|
+  c.endpoint      = "navigation_items"
+  c.resource_type = :data
+  c.default_query = {
+    sort: "sort",
+    filter: { status: { _eq: "published" } }.to_json
+  }
+end
+```
 
-  directus.register_collection(:posts) do |c|
-    c.endpoint = "posts"
-    c.layout = "post" # Use the singular layout for individual pages
-    # Minimal mapping (optional):
-    c.field :id, "id"
-    c.field :title, "title"
-    # To enable translations, uncomment and edit:
-    # c.enable_translations([:title, :content])
-  end
+Access in templates via `site.data.navigation`.
+
+### Singletons
+
+For collections that contain a single record (e.g. site settings):
+
+```ruby
+directus.register_collection(:site_settings) do |c|
+  c.endpoint      = "site_settings"
+  c.resource_type = :data
+  c.singleton     = true
 end
 ```
 
-For custom collections, create a layout file at `src/_layouts/[singular].erb` (e.g., `staff_member.erb`) to control the page rendering.
+Returns a single hash instead of an array. Access via `site.data.site_settings`.
 
-**By default, all Directus fields will be written to the front matter of generated Markdown files.**
-You only need to declare fields with `c.field` if you want to:
-- Rename a field in the output
-- Transform/convert a field value (e.g., format a date, generate a slug, etc.)
-- Set a default value if a field is missing
+### Output Collections
 
-#### Example: Customizing a Field
+Generate Markdown files for posts, pages, or custom collection types:
+
+```ruby
+directus.register_collection(:events) do |c|
+  c.endpoint      = "events"
+  c.resource_type = :custom_collection
+  c.layout        = "event"
+  c.default_query = {
+    filter: { status: { _eq: "published" } }.to_json
+  }
+end
+```
+
+Generated files include `directus_generated: true` in front matter. Only these files are cleaned up on rebuild — user-authored files are never deleted.
+
+### M2M Junction Flattening
+
+Directus returns many-to-many relationships wrapped in junction objects:
+
+```json
+[{ "raus_stats_id": { "id": 1, "value": "8+" } }]
+```
+
+Use `flatten_m2m` to unwrap them:
+
+```ruby
+directus.register_collection(:pages) do |c|
+  c.endpoint      = "pages"
+  c.resource_type = :data
+  c.default_query = {
+    fields: "id,title,sections.stats.raus_stats_id.*"
+  }
+  c.flatten_m2m "sections.stats", key: "raus_stats_id"
+end
+```
+
+After flattening:
+
+```json
+[{ "id": 1, "value": "8+" }]
+```
+
+### Field Mapping
+
+All Directus fields are included in the output by default. Use `c.field` only when you need to rename or transform a value:
 
 ```ruby
 c.field :slug, "slug" do |value|
-  value || "staff_member-#{SecureRandom.hex(4)}"
+  value || "fallback-#{SecureRandom.hex(4)}"
 end
 ```
 
 ### Translations
 
-To enable translations for specific fields, add this inside your collection block:
-
 ```ruby
 c.enable_translations([:title, :content])
 ```
 
-- You can list any field that exists in your Directus collection, even if it's not declared above with `c.field`.
-- Only declare a field with `c.field` if you want to rename, transform, or set a default for it.
+### SSL Verification
+
+If your local OpenSSL (3.6+) fails with CRL verification errors, you can disable SSL verification:
+
+```ruby
+directus.ssl_verify = false
+```
+
+This is a client-side issue with recent OpenSSL versions that enforce CRL checking but cannot auto-download CRLs during the TLS handshake. It typically only affects local development — CI/CD environments use standard OpenSSL builds without this issue.
 
-### File Generation & Cleanup
+Default: `true`.
 
-- **Generated files**: The plugin writes Markdown files to `src/_[bridgetown_collection]/` (e.g., `src/_staff_members/`).
-- **Safety**: Only files with the `directus_generated: true` flag in their front matter are deleted during cleanup. User-authored files are never removed.
+### Debug Logging
 
-### Advanced Configuration
+```bash
+BRIDGETOWN_DIRECTUS_LOG=1 bin/bt build
+```
 
-See the plugin source and inline documentation for advanced features such as:
-- Multiple collections
-- Custom layouts per collection
-- Filtering, sorting, and pagination via `c.default_query` (**experimental**; not fully tested in production—see notes below)
-- Selective field output
+### Environment Variables
 
-**Note:** Filtering, sorting, and pagination via `c.default_query` is experimental and not yet fully tested in real Bridgetown projects. Please report issues or contribute test cases if you use this feature!
+| Variable | Description |
+| -------- | ----------- |
+| `DIRECTUS_API_URL` | Directus instance URL |
+| `DIRECTUS_API_TOKEN` | Static access token |
+| `DIRECTUS_TOKEN` | Legacy fallback for token |
+| `BRIDGETOWN_DIRECTUS_LOG` | Set to `1` for verbose logging |
+
+## Full Example
+
+```ruby
+# config/initializers.rb
+init :bridgetown_directus
+
+BridgetownDirectus.configure do |directus|
+  directus.api_url    = ENV["DIRECTUS_API_URL"]
+  directus.token      = ENV["DIRECTUS_API_TOKEN"]
+  directus.ssl_verify = false
+
+  # Data-only: populates site.data
+  directus.register_collection(:site_settings) do |c|
+    c.endpoint      = "site_settings"
+    c.resource_type = :data
+    c.singleton     = true
+  end
 
-### Migrating from 0.1.x
+  directus.register_collection(:navigation) do |c|
+    c.endpoint      = "navigation_items"
+    c.resource_type = :data
+    c.default_query = { sort: "sort" }
+  end
 
-- **YAML config is no longer used.** All configuration is now in Ruby in `config/initializers/bridgetown_directus.rb`.
-- Field mapping, transformation, and translations are handled in the initializer.
-- All Directus fields are output by default; use `c.field` for customization.
-- **Upgrading?** The `resource_type` option is no longer required. Use the Bridgetown collection name and layout instead. See the [CHANGELOG](CHANGELOG.md) for details.
+  # Output: generates Markdown files
+  directus.register_collection(:events) do |c|
+    c.endpoint      = "events"
+    c.resource_type = :custom_collection
+    c.layout        = "event"
+    c.default_query = {
+      filter: { status: { _eq: "published" } }.to_json
+    }
+  end
+end
+```
 
----
+## Migrating from 0.2.x
 
-For more details and advanced usage, see the [plugin README](https://github.com/Munkun-Estudio/bridgetown_directus).
+- Configuration now uses `BridgetownDirectus.configure` block after `init :bridgetown_directus`
+- New `resource_type: :data` for collections that inject into `site.data`
+- New `singleton: true` for single-record collections
+- New `flatten_m2m` for M2M junction unwrapping
+- Build no longer fails when Directus credentials are missing — it skips gracefully
+- SSL verification is configurable via `ssl_verify`
 
 See [CHANGELOG.md](CHANGELOG.md) for upgrade notes and detailed changes.
+
+## License
+
+See [LICENSE](LICENSE) for details.

data/RELEASING.md

@@ -0,0 +1,109 @@
+# Releasing `bridgetown_directus`
+
+This document explains the release workflow for this gem and how to recover if automation fails.
+
+## Overview
+
+There are three parts:
+
+1. **release-please** creates a release PR and a `vX.Y.Z` tag.
+2. **Release** workflow publishes the gem to RubyGems.
+3. **CI** runs tests on PRs and pushes.
+
+## Normal automated release flow (recommended)
+
+1. **Make changes on a branch** and merge to `main` with a Conventional Commit title:
+   - `fix:` → patch (e.g., `0.3.1`)
+   - `feat:` → minor (e.g., `0.4.0`)
+   - `feat!:` or `BREAKING CHANGE:` → major (e.g., `1.0.0`)
+2. `release-please` runs on push to `main` and **opens a release PR**.
+3. Merge the release PR:
+   - `release-please` **creates a tag** `vX.Y.Z` and a GitHub Release.
+4. The **Release workflow** runs on the tag and **publishes to RubyGems** via Trusted Publishing.
+
+### Requirements for the automated flow
+
+- A **PAT** stored as the repo secret `RELEASE_PLEASE_TOKEN` so the tag created by release-please triggers other workflows.
+- RubyGems **Trusted Publisher** configured for this repo/workflow (see below).
+
+## Workflows (GitHub Actions)
+
+### CI
+
+File: `.github/workflows/ci.yml`  
+Runs tests on PRs and pushes.
+
+### Release Please
+
+File: `.github/workflows/release-please.yml`  
+Creates release PRs and tags.
+
+Important: it uses a PAT:
+
+```yaml
+token: ${{ secrets.RELEASE_PLEASE_TOKEN }}
+```
+
+### Release
+
+File: `.github/workflows/release.yml`  
+Runs tests and publishes using OIDC (Trusted Publishing).
+
+## Secrets you need
+
+1. **RELEASE_PLEASE_TOKEN** (GitHub PAT, classic token with `repo` scope)
+   - Used by release-please to create tags that trigger the Release workflow.
+
+> NOTE: You no longer need `RUBYGEMS_API_KEY` once Trusted Publishing is configured.
+
+## RubyGems Trusted Publishing setup
+
+1. Go to RubyGems → your gem → **Trusted Publishers** → **Create**.
+2. Fill in:
+   - Owner: `Munkun-Estudio`
+   - Repo: `bridgetown_directus`
+   - Workflow file: `release.yml`
+   - Environment: leave blank (unless you use one in GitHub)
+3. Save.
+
+After this, GitHub can publish without API keys or OTP.
+
+## Local release (manual fallback)
+
+Use this if the Release workflow fails or you need to publish immediately:
+
+```bash
+cd /Users/pablo/projects/bridgetown_directus
+bundle install
+bundle exec rake build
+ls pkg
+gem push pkg/bridgetown_directus-X.Y.Z.gem
+```
+
+If RubyGems MFA is enabled, you will be prompted for an OTP.
+
+## Troubleshooting
+
+### Release PR merged but gem not published
+
+Likely cause: tag created by `release-please` didn’t trigger the Release workflow.
+Fix: ensure `RELEASE_PLEASE_TOKEN` is set and the workflow uses it.
+
+### Release workflow failed with MFA/OTP
+
+You are not using Trusted Publishing. Configure it as above, then re-run the Release workflow.
+
+### Tag exists but no Release workflow run
+
+1. Verify the tag is `vX.Y.Z`.
+2. Go to **Actions → Release → Run workflow** (manual run).
+3. If it still fails, check the workflow logs.
+
+## Version file
+
+`lib/bridgetown_directus/version.rb` is updated by release-please.
+Do **not** bump it manually if you use release-please.
+
+## Changelog
+
+`CHANGELOG.md` is updated by release-please. Keep entries under `Unreleased` if editing manually.

data/lib/bridgetown_directus/builder.rb

@@ -1,5 +1,7 @@
 # frozen_string_literal: true
 
+require "date"
+require "fileutils"
 require "yaml"
 
 module BridgetownDirectus
@@ -7,17 +9,16 @@ module BridgetownDirectus
     def build
       config = site.config.bridgetown_directus
       return if site.ssr?
+      return unless config&.api_url && config&.token
+
+      client = Client.new(api_url: config.api_url, token: config.token, ssl_verify: config.ssl_verify)
 
       config.collections.each_value do |collection_config|
-        next unless [:posts, :pages, :custom_collection].include?(collection_config.resource_type)
-
-        process_collection(
-          client: Client.new(
-            api_url: config.api_url,
-            token: config.token
-          ),
-          collection_config: collection_config
-        )
+        if collection_config.data?
+          process_data_collection(client: client, collection_config: collection_config)
+        elsif [:posts, :pages, :custom_collection].include?(collection_config.resource_type)
+          process_collection(client: client, collection_config: collection_config)
+        end
       end
     end
 
@@ -35,23 +36,84 @@ module BridgetownDirectus
       end
     end
 
-    # Write a Directus item as a Markdown file in the correct Bridgetown collection directory
-    def write_directus_file(item, collection_dir, layout = nil, api_url = nil)
-      require "fileutils"
-      FileUtils.mkdir_p(collection_dir)
-      slug = item["slug"] || item["id"].to_s
-      filename = build_filename(collection_dir, slug)
-      item = transform_item_fields(item, api_url, layout)
-      item["directus_generated"] = true # Add flag to front matter
-      content = item.delete("body") || ""
-      front_matter = generate_front_matter(item)
-      write_markdown_file(filename, front_matter, content)
+    def build_directus_payload(item, collection_dir, collection_config, api_url = nil)
+      mapped_item = apply_data_mapping(item, collection_config)
+      slug = normalize_slug(mapped_item)
+      mapped_item["slug"] = slug
+      filename = build_filename(collection_dir, collection_config, mapped_item, slug)
+      mapped_item = transform_item_fields(mapped_item, api_url, collection_config.layout)
+      mapped_item["directus_generated"] = true # Add flag to front matter
+      content = mapped_item.delete("body") || ""
+      front_matter = generate_front_matter(mapped_item)
+      payload = render_markdown(front_matter, content)
+      [filename, payload]
     end
 
-    def build_filename(collection_dir, slug)
+    def build_filename(collection_dir, collection_config, item, slug)
+      if collection_config.resource_type == :posts || collection_config.name.to_s == "posts"
+        post_date = extract_post_date(item)
+        if post_date
+          return File.join(collection_dir, "#{post_date.strftime("%Y-%m-%d")}-#{slug}.md")
+        end
+      end
+
       File.join(collection_dir, "#{slug}.md")
     end
 
+    def normalize_slug(item)
+      slug = item["slug"] || item[:slug]
+      slug = slug.to_s.strip
+      return slug unless slug.empty?
+
+      title = item["title"] || item[:title]
+      if title && defined?(Bridgetown::Utils) && Bridgetown::Utils.respond_to?(:slugify)
+        slug = Bridgetown::Utils.slugify(title.to_s)
+      else
+        slug = title.to_s.downcase.gsub(/[^a-z0-9]+/, "-").gsub(/^-|-$/, "")
+      end
+
+      slug = slug.strip
+      return slug unless slug.empty?
+
+      id = item["id"] || item[:id]
+      id.to_s
+    end
+
+    def apply_data_mapping(item, collection_config)
+      mapped_item = item.dup
+      return mapped_item unless collection_config.fields.any? || collection_config.translations_enabled
+
+      mapped_fields = if collection_config.translations_enabled
+                        DataMapper.map_translations(collection_config, item, resolve_locale)
+                      else
+                        DataMapper.map(collection_config, item)
+                      end
+
+      mapped_item.merge!(mapped_fields)
+      mapped_item
+    end
+
+    def resolve_locale
+      return site.locale if site.respond_to?(:locale) && site.locale
+
+      config_locale = site.config["locale"] || site.config[:locale]
+      return config_locale.to_sym if config_locale
+
+      :en
+    end
+
+    def extract_post_date(item)
+      raw = item["date"] || item[:date] || item["published_at"] || item[:published_at] || item["date_created"]
+      item["date"] ||= item["published_at"] if item["published_at"] && !item["date"]
+      return nil unless raw
+
+      return raw.to_date if raw.respond_to?(:to_date)
+
+      Date.parse(raw.to_s)
+    rescue ArgumentError
+      nil
+    end
+
     def transform_item_fields(item, api_url, layout)
       item = item.dup
       if item["image"] && api_url && !item["image"].to_s.start_with?("http://", "https://")
@@ -66,19 +128,69 @@ module BridgetownDirectus
       yaml.sub(%r{^---\s*\n}, "") # Remove leading --- if present
     end
 
-    def write_markdown_file(filename, front_matter, content)
-      File.write(filename, "---\n#{front_matter}---\n\n#{content}")
+    def render_markdown(front_matter, content)
+      "---\n#{front_matter}---\n\n#{content}"
+    end
+
+    def write_markdown_file(filename, payload)
+      FileUtils.mkdir_p(File.dirname(filename))
+      File.write(filename, payload)
+    end
+
+    def file_unchanged?(filename, payload)
+      return false unless File.exist?(filename)
+
+      File.read(filename) == payload
+    rescue StandardError
+      false
     end
 
     # Remove only plugin-generated Markdown files in the target directory before writing new ones
-    def clean_collection_directory(collection_dir)
-      require "yaml"
+    def clean_collection_directory(collection_dir, keep_files: [])
+      keep_set = keep_files.map { |file| File.expand_path(file) }.to_h { |file| [file, true] }
+
+      deleted = 0
       Dir.glob(File.join(collection_dir, "*.md")).each do |file|
+        next if keep_set[File.expand_path(file)]
+
         fm = File.read(file)[%r{\A---.*?---}m]
-        File.delete(file) if fm && YAML.safe_load(fm)["directus_generated"]
+        if fm && YAML.safe_load(fm, permitted_classes: [Date, Time, DateTime])["directus_generated"]
+          File.delete(file)
+          deleted += 1
+        end
       rescue StandardError => e
         warn "[BridgetownDirectus] Could not check/delete #{file}: #{e.message}"
       end
+
+      deleted
+    end
+
+    # Fetch a data-only collection and inject into site.data (no file generation)
+    def process_data_collection(client:, collection_config:)
+      endpoint = collection_config.endpoint || collection_config.name.to_s
+      begin
+        response = client.fetch_collection(endpoint, collection_config.default_query)
+      rescue StandardError => e
+        warn "Error fetching data collection '#{endpoint}': #{e.message}"
+        return
+      end
+
+      process_data_collection_with_data(response, collection_config)
+    end
+
+    # Process already-fetched data for a data collection (also used in tests)
+    def process_data_collection_with_data(response, collection_config)
+      data = sanitize_keys(response)
+
+      if collection_config.singleton
+        data = data.is_a?(Array) ? data.first : data
+      end
+
+      # Apply M2M flattening if configured
+      apply_m2m_flattenings!(data, collection_config)
+
+      site.data[collection_config.name.to_s] = data
+      log_directus("Loaded data collection: #{collection_label(collection_config)}#{collection_config.singleton ? ' (singleton)' : " (#{Array(data).size} items)"}")
     end
 
     def process_collection(client:, collection_config:)
@@ -90,14 +202,79 @@ module BridgetownDirectus
         return
       end
       collection_dir = collection_directory(collection_config.name)
-      clean_collection_directory(collection_dir)
+      FileUtils.mkdir_p(collection_dir)
       api_url = site.config.bridgetown_directus.api_url
       sanitized_response = sanitize_keys(response)
-      sanitized_response.each do |item|
-        write_directus_file(item, collection_dir, collection_config.layout, api_url)
+      payloads = sanitized_response.to_h do |item|
+        build_directus_payload(item, collection_dir, collection_config, api_url)
+      end
+      log_directus("Generating #{collection_label(collection_config)} (#{payloads.size} items)")
+      deleted = clean_collection_directory(collection_dir, keep_files: payloads.keys)
+      written = 0
+      skipped = 0
+      payloads.each do |filename, payload|
+        if file_unchanged?(filename, payload)
+          skipped += 1
+          next
+        end
+
+        write_markdown_file(filename, payload)
+        written += 1
+      end
+      log_directus("Updated #{collection_label(collection_config)}: wrote #{written}, skipped #{skipped}, deleted #{deleted}")
+    end
+
+    # Apply M2M junction flattening to fetched data.
+    # Walks the configured dot-paths and unwraps junction objects.
+    def apply_m2m_flattenings!(data, collection_config)
+      return if collection_config.m2m_flattenings.empty?
+
+      items = data.is_a?(Array) ? data : [data].compact
+      collection_config.m2m_flattenings.each do |flattening|
+        path_parts = flattening[:path].split(".")
+        junction_key = flattening[:key]
+        items.each { |item| flatten_at_path!(item, path_parts, junction_key) }
+      end
+    end
+
+    # Recursively walk a dot-path and flatten the M2M array at the leaf.
+    def flatten_at_path!(obj, path_parts, junction_key)
+      return unless obj.is_a?(Hash)
+
+      key = path_parts.first
+      remaining = path_parts[1..]
+
+      if remaining.empty?
+        # We're at the leaf — flatten the junction array
+        return unless obj[key].is_a?(Array)
+
+        obj[key] = obj[key].filter_map { |junction| junction[junction_key] if junction.is_a?(Hash) }
+      else
+        # Intermediate path — recurse into nested object(s)
+        target = obj[key]
+        if target.is_a?(Array)
+          target.each { |nested| flatten_at_path!(nested, remaining, junction_key) }
+        elsif target.is_a?(Hash)
+          flatten_at_path!(target, remaining, junction_key)
+        end
       end
     end
 
+    def log_directus(message)
+      return unless directus_logging_enabled?
+
+      Utils.log_directus(message)
+    end
+
+    def directus_logging_enabled?
+      flag = ENV["BRIDGETOWN_DIRECTUS_LOG"]
+      flag && !flag.to_s.strip.empty? && flag.to_s != "0"
+    end
+
+    def collection_label(collection_config)
+      collection_config.name.to_s.tr("_", " ").split.map(&:capitalize).join(" ")
+    end
+
     # Recursively sanitize keys to avoid illegal instance variable names (Ruby 3.4+)
     def sanitize_keys(obj)
       case obj

data/lib/bridgetown_directus/client.rb

@@ -8,9 +8,10 @@ module BridgetownDirectus
   class Client
     attr_reader :api_url, :token
 
-    def initialize(api_url:, token:)
+    def initialize(api_url:, token:, ssl_verify: true)
       @api_url = api_url
       @token = token
+      @ssl_verify = ssl_verify
       return unless @token.nil? || @api_url.nil?
 
       raise StandardError, "Invalid Directus configuration: missing API token or URL"
@@ -45,7 +46,7 @@ module BridgetownDirectus
     private
 
     def connection
-      @connection ||= Faraday.new(url: @api_url) do |faraday|
+      @connection ||= Faraday.new(url: @api_url, ssl: { verify: @ssl_verify }) do |faraday|
         faraday.headers["Authorization"] = "Bearer #{@token}"
         faraday.headers["Content-Type"] = "application/json"
         faraday.adapter Faraday.default_adapter

data/lib/bridgetown_directus/configuration.rb

@@ -43,11 +43,33 @@ module BridgetownDirectus
         @translations_enabled = false
         @translatable_fields = []
         @endpoint = nil
+        @singleton = false
+        @m2m_flattenings = []
       end
 
       # Set up accessors for collection configuration properties
       attr_accessor :endpoint, :fields, :default_query, :resource_type, :layout,
-                    :translations_enabled, :translatable_fields
+                    :translations_enabled, :translatable_fields, :singleton
+      attr_reader :m2m_flattenings
+
+      # Register a many-to-many junction to flatten after fetching.
+      # Directus returns M2M data wrapped in junction objects like:
+      #   [{"raus_stats_id": {"id": 1, "value": "8+"}}]
+      # This unwraps them to:
+      #   [{"id": 1, "value": "8+"}]
+      #
+      # @param path [String] Dot-separated path to the M2M field (e.g. "sections.stats")
+      # @param key [String] The junction key containing the actual related item
+      # @return [void]
+      def flatten_m2m(path, key:)
+        @m2m_flattenings << { path: path, key: key }
+      end
+
+      # Check if this collection is a data-only collection
+      # @return [Boolean]
+      def data?
+        @resource_type == :data
+      end
 
       # Define a field mapping with optional converter
       # @param bridgetown_field [Symbol] The field name in Bridgetown

data/lib/bridgetown_directus/data_mapper.rb

@@ -113,7 +113,15 @@ module BridgetownDirectus
           # Get the Directus field name for this Bridgetown field
           field_config = collection_config.fields[field]
 
-          directus_field = field_config.is_a?(Hash) ? field_config[:directus_field] : field_config.to_s
+          directus_field = if field_config.nil?
+                             field.to_s
+                           elsif field_config.is_a?(Hash)
+                             field_config[:directus_field]
+                           else
+                             field_config.to_s
+                           end
+
+          directus_field = field.to_s if directus_field.to_s.empty?
 
           # Check if the translation has this field
           next unless translation[directus_field]

data/lib/bridgetown_directus/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module BridgetownDirectus
-  VERSION = "0.2.0"
+  VERSION = "0.4.1"
 end

data/lib/bridgetown_directus.rb

@@ -8,25 +8,53 @@ require_relative "bridgetown_directus/configuration"
 require_relative "bridgetown_directus/builder"
 
 module BridgetownDirectus
-  # Bridgetown initializer for the plugin
-  Bridgetown.initializer :bridgetown_directus do |config|
-    # Only assign config.bridgetown_directus if not already set
-    config.bridgetown_directus ||= Configuration.new
+  # Bridgetown initializer for the plugin.
+  #
+  # Usage in config/initializers.rb:
+  #
+  #   init :bridgetown_directus do
+  #     api_url ENV["DIRECTUS_API_URL"]
+  #     token   ENV["DIRECTUS_API_TOKEN"]
+  #   end
+  #
+  # Then configure collections separately:
+  #
+  #   BridgetownDirectus.configure do |directus|
+  #     directus.register_collection(:posts) { |c| ... }
+  #   end
+  #
+  Bridgetown.initializer :bridgetown_directus do |config, **kwargs|
+    bd_config = Configuration.instance
 
-    # Set up configuration directly (leave to user initializer if possible)
-    config.bridgetown_directus.api_url ||= ENV["DIRECTUS_API_URL"] || "[https://studio.munkun.com](https://studio.munkun.com)"
-    config.bridgetown_directus.token ||= ENV["DIRECTUS_TOKEN"] || "t1P6YstcUslmf-KJFbc6Kyg0bomMxkXY"
+    # Apply keyword args from init block (e.g. api_url, token)
+    bd_config.api_url ||= kwargs[:api_url]&.to_s || ENV["DIRECTUS_API_URL"]
+    bd_config.token   ||= kwargs[:token]&.to_s || ENV["DIRECTUS_API_TOKEN"] || ENV["DIRECTUS_TOKEN"]
+
+    # Store on the Bridgetown config so the Builder can access it
+    config.bridgetown_directus = bd_config
 
     # Register the builder
     config.builder BridgetownDirectus::Builder
   end
 
+  # Global configuration singleton. Call BridgetownDirectus.configure to register collections.
   class Configuration
-    attr_accessor :api_url, :token
+    attr_accessor :api_url, :token, :ssl_verify
     attr_reader :collections
 
     def initialize
       @collections = {}
+      @ssl_verify = true
+    end
+
+    # Returns the singleton Configuration instance
+    def self.instance
+      @instance ||= new
+    end
+
+    # Reset the singleton (useful in tests)
+    def self.reset!
+      @instance = nil
     end
 
     def register_collection(name, &block)
@@ -36,4 +64,15 @@ module BridgetownDirectus
       collection
     end
   end
+
+  # Configure the plugin. Call this after `init :bridgetown_directus`.
+  #
+  #   BridgetownDirectus.configure do |directus|
+  #     directus.api_url = ENV["DIRECTUS_API_URL"]
+  #     directus.register_collection(:posts) { |c| ... }
+  #   end
+  #
+  def self.configure
+    yield Configuration.instance if block_given?
+  end
 end

metadata

@@ -1,13 +1,13 @@
 --- !ruby/object:Gem::Specification
 name: bridgetown_directus
 version: !ruby/object:Gem::Version
-  version: 0.2.0
+  version: 0.4.1
 platform: ruby
 authors:
 - Munkun
 bindir: bin
 cert_chain: []
-date: 2025-04-16 00:00:00.000000000 Z
+date: 1980-01-02 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: bridgetown
@@ -160,12 +160,18 @@ executables: []
 extensions: []
 extra_rdoc_files: []
 files:
+- ".github/workflows/ci.yml"
+- ".github/workflows/release-please.yml"
+- ".github/workflows/release.yml"
 - ".gitignore"
+- ".release-please-config.json"
+- ".release-please-manifest.json"
 - ".rubocop.yml"
 - CHANGELOG.md
 - Gemfile
 - LICENSE.txt
 - README.md
+- RELEASING.md
 - Rakefile
 - bridgetown.automation.rb
 - bridgetown_directus.gemspec
@@ -201,7 +207,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.6.2
+rubygems_version: 3.6.9
 specification_version: 4
 summary: Use Directus as headless CMS for Bridgetown
 test_files: []