bridgetown_directus 0.1.3 → 0.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: b86e165473c96ffa32fc96cf04ec0b5564169bcdd53866489c6f806f16235dfe
-  data.tar.gz: c7ea854a2e0263589a31d467b164f061fe15399126a90de273b4c1b8a6366226
+  metadata.gz: 6834fa39c0868873782728053787ca9fbcbd0defb231b70621c8737ba6e996ee
+  data.tar.gz: 9dfb896e01a1a7e48d0a6db38b41c12a092195650ea8945083b417d34a76bda6
 SHA512:
-  metadata.gz: 80a9bfad8a419d19159a2f0a6f7538afc142837a3baff3737bd9c1c5f127f039d7990432ace15dffea1cf3b474129a23335919e1c9e6fa975e4df653ecf83e67
-  data.tar.gz: '098a9aeb10f146c6a30ee1a60d428390d52998e3bf438735b95f5de0b7fbd0afdfbb61f3982f816c1c12b43224b71afcda6f1783aaf8cb4a52a9b9b1ad545aab'
+  metadata.gz: e2394537291cd18e7887344e9d37c21973eafc19ec2b89dfc38d7c6796011ac8d22ca4777bacf052cf5f4e5cd2ba1dd26019a897cf0a0d26a901fec4aaafba5e
+  data.tar.gz: a72244a4b1bf68e1e4d8834c5c0548c4a2a3287267a040f3133b5b5cca2a67432948adbc8c0abaf2bb577d852023300aa7dd80c765c374e8c17f72771ed63625

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,20 @@
+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:
+          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:
+      - "v*"
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+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
+      - name: Push gem
+        env:
+          GEM_HOST_API_KEY: ${{ secrets.RUBYGEMS_API_KEY }}
+        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.3.0"
+}

data/CHANGELOG.md

@@ -5,10 +5,27 @@ 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.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]
 
 - ...
 
+## [0.2.0] - 2025-04-16
+
+- BREAKING: Simplified configuration—`resource_type` is no longer required. Use the Bridgetown collection name and layout instead.
+- Automation now prompts for both Directus and Bridgetown collection names and sets up the initializer accordingly.
+- Generated files are now flagged with `directus_generated: true` in front matter for safe cleanup.
+- Only plugin-generated files (with this flag) are deleted during cleanup; user-authored files are preserved.
+- Layouts for custom collections are now singular (e.g., `staff_member.erb`).
+- README and example configuration updated for new conventions.
+- Test suite updated for custom collections and file safety logic.
+
 ## [0.1.0] - 2024-09-27
 
 - First version

data/README.md

@@ -2,16 +2,19 @@
 
 [![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/), which is among other things a [headless CMS](https://en.wikipedia.org/wiki/Headless_content_management_system). 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.
+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.
 
 ## Features
 
-- Fetch **published posts** from Directus during the build process
-- Support for **multilingual content** through Directus translations
+- 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)
 
 ## 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.
+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 Installation (Bridgetown Automation)
 
@@ -21,11 +24,10 @@ Before installing the plugin make sure you have an [Auth Token](https://docs.dir
    bin/bridgetown apply https://github.com/munkun-estudio/bridgetown_directus
    ```
 
-2. The setup will guide you through:
-   - Providing the Directus API URL and Auth Token
-   - Specifying your content collection name
-   - Enabling/disabling translations support
-   - Configuring translatable fields (if translations enabled)
+   This will:
+   - Prompt for your Directus API URL, token, Directus collection name, and Bridgetown collection name
+   - Generate a minimal `config/initializers.rb`
+   - All further customization is done in Ruby, not YAML
 
 ### Manual Installation
 
@@ -35,140 +37,97 @@ Before installing the plugin make sure you have an [Auth Token](https://docs.dir
    bundle add "bridgetown_directus"
    ```
 
-2. Run bundle install to install the gem.
-3. Add the plugin configuration to your config/initializers.rb file:
-
-   ```ruby
-   init :"bridgetown_directus" do
-     api_url "https://your-directus-instance.com"
-     token ENV['DIRECTUS_AUTH_TOKEN'] || "your_token"
-     collection config.directus["collection"]
-     mappings config.directus["mappings"]
-   end
-   ```
-
-4. Configure your bridgetown.config.yml:
-
-   ```yaml
-   directus:
-     collection: "posts"
-     mappings:
-       title: "title"           # Required field
-       content: "body"          # Required field
-       slug: "slug"             # Optional, will be auto-generated if not provided
-       date: "date"             # Optional, defaults to current date/time if not provided
-       category: "category"     # Optional
-       excerpt: "excerpt"       # Optional, defaults to content excerpt if not provided
-       image: "image"           # Optional, URL for the image associated with the post
-     translations:
-       enabled: false          # Set to true for multilingual support
-       fields:                 # Only required if translations are enabled
-         - title
-         - excerpt
-         - body
-   ```
+2. Run `bundle install` to install the gem.
+3. Create `config/initializers.rb` (see below for configuration).
 
 ## Configuration
 
-### Basic Configuration
-
-You can configure the plugin either through environment variables or direct configuration:
-
-1. Using environment variables:
+### Minimal Example
 
-   ```bash
-   export DIRECTUS_API_URL="https://your-directus-instance.com"
-   export DIRECTUS_AUTH_TOKEN="your-token"
-   ```
-
-2. Or through bridgetown.config.yml as shown in the installation section.
-
-### Translations Configuration
+```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"
 
-To enable multilingual support:
-
-1. In your bridgetown.config.yml, set translations.enabled to true:
-
-   ```yaml
-   directus:
-     # ... other config ...
-     translations:
-       enabled: true
-       fields:
-         - title
-         - excerpt
-         - body
-   ```
+  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
+end
+```
 
-2. Ensure your Directus collection has translations enabled and configured for the specified fields.
+For custom collections, create a layout file at `src/_layouts/[singular].erb` (e.g., `staff_member.erb`) to control the page rendering.
 
-3. The plugin will automatically:
+**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:
 
-- Generate posts for each available language
-- Create appropriate URLs based on locale
-- Handle fallback content if translations are missing
+- 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
 
-## Usage
+Mapped fields are merged into the full Directus payload, so you still retain access to original fields unless you override them.
 
-Once the plugin is installed and configured, it will fetch posts from your Directus instance during each build. These posts will be generated as in-memory resources, meaning they are not written to disk but are treated as normal posts by Bridgetown.
+### Environment Variables
 
-### Directus Setup
+- `DIRECTUS_API_URL` (required unless you set `directus.api_url` in config)
+- `DIRECTUS_API_TOKEN` (required unless you set `directus.token` in config)
+- `DIRECTUS_TOKEN` (legacy fallback; supported for backward compatibility)
 
-#### Basic Collection Setup
+#### Example: Customizing a Field
 
-Create a collection in your Directus instance with these fields:
+```ruby
+c.field :slug, "slug" do |value|
+  value || "staff_member-#{SecureRandom.hex(4)}"
+end
+```
 
-- **title**: The title of the post (Text field)
-- **body**: The content of the post (Rich Text or Text field)
-- **slug**: Optional. A unique slug for the post (Text field)
-- **date**: Optional. The publish date (Datetime field)
-- **status**: Optional. The status of the post (Option field with values like "published", "draft", etc.)
-- **category**: Optional. The category for the post (Text field)
-- **excerpt**: Optional. A short excerpt (Text field)
-- **image**: Optional. An image associated with the post (File/Media field)
+### Translations
 
-Make sure the **status** field uses `"published"` for posts that you want to be visible on your site.
+To enable translations for specific fields, add this inside your collection block:
 
-#### Image Permissions
+```ruby
+c.enable_translations([:title, :content])
+```
 
-If your posts contain images, and you want to display them in your Bridgetown site, you'll need to ensure that the **directus_files** collection has the appropriate permissions for public access.
+- 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.
 
-1. **Public Role Configuration:**
-   - In Directus, navigate to **Settings** > **Roles & Permissions**.
-   - Select the **Public** role (or create a custom role if needed).
-   - Under the **Collections** tab, locate the **directus_files** collection.
-   - Set the **read** permission to **enabled** so that the images can be accessed publicly.
+### File Generation & Cleanup
 
-2. **Image Uploads and Management:**
-   - When users upload images to posts, ensure that the images are associated with the **directus_files** collection.
-   - By default, Directus will store image URLs, which the plugin can reference directly. Ensure that the **image** field or URL is added to the **body** field (or wherever applicable).
+- **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.
+- **Posts**: If `date` or `published_at` is present, filenames are generated as `YYYY-MM-DD-slug.md` to preserve date-based permalinks.
 
-### Fetching Posts
+### Debug Logging
 
-Posts are fetched from Directus during each build and treated as Bridgetown resources. These resources are available in your site just like regular posts, and you can access them through your templates or layouts.
+Set `BRIDGETOWN_DIRECTUS_LOG=1` to print per-collection activity logs during builds.
 
-By default, only posts with a status of "published" are fetched from Directus.
+### Advanced Configuration
 
-## TODO List
+See the plugin source and inline documentation for advanced features such as:
 
-Here are features that are planned for future versions of the plugin:
+- 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
 
-- [ ] Support for Additional Content Types: Extend the plugin to handle other Directus collections and custom content types.
-- [ ] Custom Field Mapping via DSL: Implement a DSL for more advanced field mapping.
-- [ ] Asset Handling: Add functionality to download and manage images and other assets.
-- [ ] Caching & Incremental Builds: Implement caching to improve build performance when fetching content.
-- [ ] Draft Previews: Add support for previewing unpublished (draft) posts.
+**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!
 
-## Testing
+### Migrating from 0.1.x
 
-Testing isn't fully set up yet, but contributions and improvements are welcome.
+- **YAML config is no longer used.** All configuration is now in Ruby in `config/initializers.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.
 
-## Contributing
+---
 
-We welcome contributions! To contribute:
+For more details and advanced usage, see the [plugin README](https://github.com/Munkun-Estudio/bridgetown_directus).
 
-1. Fork the repository
-2. Create a new branch (git checkout -b feature-branch)
-3. Make your changes
-4. Push to the branch (git push origin feature-branch)
-5. Open a Pull Request
+See [CHANGELOG.md](CHANGELOG.md) for upgrade notes and detailed changes.

data/Rakefile

@@ -4,7 +4,7 @@ require "rake/testtask"
 Rake::TestTask.new(:test) do |t|
   t.libs << "test"
   t.libs << "lib"
-  t.test_files = FileList["test/**/test_*.rb"]
+  t.test_files = FileList["test/**/*_test.rb"]
   t.warning = false
 end
 

data/bridgetown.automation.rb

@@ -2,61 +2,63 @@ say_status :directus, "Installing the bridgetown_directus plugin..."
 
 # Prompt the user for Directus API URL and Auth Token
 api_url = ask("What's your Directus instance URL? (Example: https://your-instance.example.com)")
-auth_token = ask("What's your Directus API auth token? (Leave blank to use ENV['DIRECTUS_AUTH_TOKEN'])")
-collection = ask("What's the name of the collection (Directus Model)? (Example: posts)")
-
-# Ask if translations should be enabled with a default of 'n'
-translations_enabled_input = ask("Do you want to enable translations? (y/n) default:", :yellow, default: "n")
-translations_enabled = translations_enabled_input.strip.downcase.start_with?("y")
-
-# Prepare the translations YAML block based on the user’s response
-translations_yaml = if translations_enabled
-  translatable_fields_input = ask("List the translatable fields separated by commas (e.g., title, excerpt, content)")
-  translatable_fields = translatable_fields_input.split(',').map(&:strip)
-
-  "  translations:\n    enabled: true\n    fields:\n#{translatable_fields.map { |field| "      - #{field}" }.join("\n")}"
-else
-  "  translations:\n    enabled: false"
-end
+auth_token = ask("What's your Directus API auth token? (Leave blank to use ENV['DIRECTUS_API_TOKEN'])")
+directus_collection = ask("What's the Directus collection name (API endpoint/model)? (Example: posts)")
+bridgetown_collection = ask("What's the Bridgetown collection name (used for folder and resource)? (Example: posts)")
 
 # Add the bridgetown_directus gem
 add_gem "bridgetown_directus"
 
-# Add Directus configuration to config/initializers.rb
-add_initializer :bridgetown_directus do
+# Add minimal Directus configuration to config/initializers.rb in the idiomatic Bridgetown plugin style
+add_initializer :bridgetown_directus do |directus|
   <<~RUBY
-  do
-    api_url "#{api_url}"
-    token "#{auth_token.present? ? auth_token : "<%= ENV['DIRECTUS_AUTH_TOKEN'] %>"}"
-    collection config.directus["collection"]
-    mappings config.directus["mappings"]
-  end
-  RUBY
-end
+    # This block was generated by bridgetown_directus automation.
+    # All Directus configuration is now handled here (not in YAML).
+    # Set DIRECTUS_API_URL and DIRECTUS_API_TOKEN in your .env or shell environment.
+    #
+    # By default, ALL fields from Directus will be written to the front matter of generated Markdown files.
+    # You only need to declare fields here 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
+    #
+    # Example: To customize or transform fields, use the c.field declaration:
+    #   # require "securerandom" # Uncomment if you use SecureRandom in your mapping
+    #   c.field :slug, "slug" do |value|
+    #     value || "post-#{SecureRandom.hex(4)}"
+    #   end
+    #
+    # ---
+    # TRANSLATIONS:
+    # To enable translations for specific fields, add this line inside your collection block:
+    #   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.
+    # Declaring a field with c.field is only required if you want to rename, transform, or set a default for it.
+    # ---
+
+    directus.api_url = ENV["DIRECTUS_API_URL"] || "#{api_url}"
+    directus.token = ENV["DIRECTUS_API_TOKEN"] || "#{auth_token}"
 
-# Append the configuration to bridgetown.config.yml
-append_to_file "bridgetown.config.yml" do
-  <<~YAML
-
-directus:
-  collection: "#{collection}"
-  mappings:
-    title: "title"           # Required field
-    content: "body"          # Required field
-    slug: "slug"             # Optional, will be auto-generated if not provided
-    date: "date"             # Optional, defaults to the current date/time if not provided
-    category: "category"     # Optional
-    excerpt: "excerpt"       # Optional, defaults to content excerpt if not provided
-    image: "image"           # Optional, URL for the image associated with the post
-#{translations_yaml}
-  YAML
+    directus.register_collection(:#{bridgetown_collection}) do |c|
+      c.endpoint = "#{directus_collection}"
+      c.layout = "#{bridgetown_collection.to_s.singularize}"
+      # Minimal mapping (optional):
+      c.field :id, "id"
+      c.field :title, "title"
+      # Add more c.field declarations above as needed for custom logic.
+      # To enable translations, uncomment and edit the following line:
+      # c.enable_translations([:title, :content])
+    end
+  RUBY
 end
 
 say_status :success, "Bridgetown Directus plugin has been installed!", :green
-say_status :info, "Add your posts to Directus and they will be automatically imported when you build your site.", :yellow
-if translations_enabled
-  say_status :info, "Translations are enabled. Make sure your Directus collection has translations configured.", :yellow
+say_status :directus, "Check config/initializers.rb for your Directus setup."
+say_status :directus, "Check bridgetown.config.yml for your collection setup."
+
+# Only remind the user to create a layout if it's a custom collection (not 'posts' or 'pages')
+if !%w[posts pages].include?(bridgetown_collection.to_s)
+  say_status :directus, "Don't forget to create a layout file at src/_layouts/#{bridgetown_collection.to_s.singularize}.erb for your custom collection pages!"
 end
-say_status :directus, "Check config/initializers.rb for your Directus setup and config.bridgetown.yml to adjust fields mappings if necessary."
-say_status :directus, "For usage help visit:"
-say_status :directus, "https://github.com/Munkun-Estudio/bridgetown_directus/blob/main/README.md"
+
+say_status :directus, "For advanced usage and field customization, see the README: https://github.com/Munkun-Estudio/bridgetown_directus"

data/bridgetown_directus.gemspec

@@ -24,7 +24,7 @@ Gem::Specification.new do |spec|
 
   spec.required_ruby_version = ">= 2.7.0"
 
-  spec.add_dependency "bridgetown", ">= 1.2.0", "< 2.0"
+  spec.add_dependency "bridgetown", ">= 2.0.0.beta4", "< 3.0"
   spec.add_dependency "faraday", "~> 2.12"
 
   spec.add_development_dependency "bundler", "~> 2.0"
@@ -32,7 +32,7 @@ Gem::Specification.new do |spec|
   spec.add_development_dependency "rubocop-bridgetown", "~> 0.3"
   spec.add_development_dependency "shoulda", "~> 3.0"
   spec.add_development_dependency "minitest", "~> 5.0"
-  spec.add_development_dependency "minitest-profile", "~> 0.5"
+  spec.add_development_dependency "minitest-profile", "~> 0.0.2"
   spec.add_development_dependency "minitest-reporters", "~> 1.0"
   spec.add_development_dependency "webmock", "~> 3.0"
 end

data/example/bridgetown.config.yml

@@ -0,0 +1,24 @@
+# Example Bridgetown configuration file for the enhanced Directus plugin
+
+# Site settings
+title: My Bridgetown Site with Directus
+email: your-email@example.com
+description: >-
+  A Bridgetown site powered by Directus headless CMS
+baseurl: ""
+url: ""
+
+# Collections
+collections:
+  posts:
+    output: true
+    permalink: /blog/:slug/
+    source: _posts
+    future: true
+  staff_members:
+    output: true
+    permalink: /staff_members/:slug/
+    source: _staff_members
+    sort_field: 'created_at'
+    sort_reverse: false
+

data/example/config/initializers.rb

@@ -0,0 +1,34 @@
+# frozen_string_literal: true
+
+# Example Bridgetown Directus plugin initializer for v2+
+#
+# All Directus configuration is now handled here, NOT in bridgetown.config.yml.
+# Use ENV variables for secrets and API credentials.
+
+require "securerandom"
+require "time"
+
+init :bridgetown_directus do |directus|
+  # Set API credentials from environment variables
+  directus.api_url = ENV["DIRECTUS_API_URL"] || "https://your-directus-instance.com"
+  directus.token = ENV["DIRECTUS_API_TOKEN"] || "your-token-here"
+
+  # Example custom collection: staff_members
+  directus.register_collection(:staff_members) do |c|
+    c.endpoint = "staff_members"
+    c.layout = "staff_member"
+    c.field :id, "id"
+    c.field :title, "title"
+    # To enable translations, uncomment and edit:
+    # c.enable_translations([:title, :content])
+    # Add more fields as needed
+  end
+
+  # Example for posts (if needed)
+  directus.register_collection(:posts) do |c|
+    c.endpoint = "articles"
+    c.layout = "post"
+    c.field :title, "title"
+    c.field :content, "body"
+  end
+end