perron 0.10.0 → 0.12.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 2aa4c7af63f95aef3bc25c9ef97a4da02d75486ec3ee975f69a980f66cb34557
-  data.tar.gz: f1c62fff6d0ba6c121da85f463dc32fd5656c884d059d0f2955c6a95a4c0bf3a
+  metadata.gz: 70a9d142afefaac54496efbd93312cae38e14525b7f6310be576f74e7f9dfb4d
+  data.tar.gz: fd010ef141b72700120c926a104b8f33f72971d94e58ae01c8c793424d4c5319
 SHA512:
-  metadata.gz: 175ecbdc5dc5468e28e0abe13926b578fb6669d078b594da1dea91ab8cce68c3a7f63f12d3be4f0de757d270c5d3a95ce96db925ea9c3cbe238e1dd72069aaa1
-  data.tar.gz: b65f95000da601c8ea2f6dcea2e1cf9edb907d366ff783b3ba37e4b2c2d0ff0222cf98821f7537690895087c39ad0c902397c6325e309e27019914101072b6df
+  metadata.gz: 9ab5c1d522c8645f3470451e74c7a5a3475f1a683d6dc953e88fd8fb123e4477558ae99839f2db4742741663c2957eec9d94696d05d7936aa1df14880a5d59a4
+  data.tar.gz: fb40411ad56556967b82396d1bb540766550e73131b9358f870f441c75bd1538c9ef071b3fcb4a6c371f389ee7a1a031c101c4e24cb76b9875b4841756a68dc7

data/Gemfile

@@ -14,4 +14,5 @@ group :development, :test do
   gem "rake", "~> 13.3.0"
   gem "minitest", "~> 5.25", ">= 5.25.5"
   gem "debug", "~> 1.11.0"
+  gem "rouge", "~> 4.6.0"
 end

data/Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    perron (0.10.0)
+    perron (0.12.0)
       csv
       json
       psych
@@ -204,6 +204,7 @@ GEM
     regexp_parser (2.10.0)
     reline (0.6.1)
       io-console (~> 0.5)
+    rouge (4.6.0)
     rubocop (1.75.8)
       json (~> 2.3)
       language_server-protocol (~> 3.17.0.2)
@@ -267,6 +268,7 @@ DEPENDENCIES
   perron!
   rails (~> 7.2.0)
   rake (~> 13.3.0)
+  rouge (~> 4.6.0)
   standard (~> 1.50.0)
 
 BUNDLED WITH

data/README.md

@@ -13,7 +13,7 @@ A Rails-based static site generator.
 </a>
 
 
-## Getting Started
+## Getting started
 
 ### Installation
 
@@ -38,7 +38,7 @@ end
 
 ## Mode
 
-Perron can operate in two modes, configured via `config.mode`. This allows you to build either a full static site or integrate pages into a dynamic Rails application.
+Perron can operate in two modes, configured via `config.mode`. This allows a build to be either a full static site or be integrated pages in a dynamic Rails application.
 
 | **Mode** | `:standalone` (default) | `:integrated` |
 | :--- | :--- | :--- |
@@ -47,14 +47,14 @@ Perron can operate in two modes, configured via `config.mode`. This allows you t
 | **Asset Handling** | Via Perron | Via Asset Pipeline |
 
 
-## Creating Content
+## Collections
 
-Perron is, just like Rails, designed with convention over configuration in mind. Content is stored in `app/content/*/*.{erb,md}`. Content is backed by a class, located in `app/models/content/` that inherits from `Perron::Resource`.
+Perron is, just like Rails, designed with convention over configuration in mind. Content is stored in `app/content/*/*.{erb,md,*}` and backed by a class, located in `app/models/content/` that inherits from `Perron::Resource`.
 
 The controllers are located in `app/controllers/content/`. To make them available, create a route: `resources :posts, module: :content, only: %w[index show]`.
 
 
-### Collections
+### Create a new collection
 
 ```bash
 bin/rails generate content Post
@@ -66,32 +66,82 @@ This will create the following files:
 * `app/controllers/content/posts_controller.rb`
 * `app/views/content/posts/index.html.erb`
 * `app/views/content/posts/show.html.erb`
-* Adds route: `resources :posts, module: :content, only: %w[index show]`
 
+And adds a route: `resources :posts, module: :content, only: %w[index show]`
 
-### Setting a Root Page
 
-To set a root page, include `Perron::Root` in your `Content::PagesController` and add a `app/content/pages/root.[md,erb]` file (make sure to set `slug: "/"` in its frontmatter).
+### Routes
+
+Perron uses standard Rails routing, allowing the use of familiar route helpers. For a typical “clean slug”, the filename without extensions serves as the `id` parameter (slug).
+```ruby
+<%# For app/content/pages/about.md %>
+<%= link_to "About Us", page_path("about") # => <a href="/about/">About Us</a> %>
+```
+
+To create files with specific extensions directly (e.g., `pricing.html`), the route must first be configured to treat the entire filename as the ID. In `config/routes.rb`, modify the generated `resources` line by adding a `constraints` option:
+
+```ruby
+# Change from…
+resources :pages, path: "/", module: :content, only: %w[show]
+
+# …to…
+resources :pages, path: "/", module: :content, only: %w[show], constraints: { id: /[^\/]+/ }
+```
+
+With this change, a content file named `app/content/pages/pricing.html.erb` can be linked using the full filename. The builder will then create `pricing.html` in the output directory.
+```ruby
+<%= link_to "View Pricing", page_path("pricing", format: :html) # => <a href="/pricing.html">View Pricing</a> %>
+```
 
-This is automatically added when you create a `Page` collection.
 
+### Setting a root page
 
-## Markdown Support
+To set a root page, include `Perron::Root` in your `Content::PagesController` and add a `app/content/pages/root.{md,erb,*}` file. Then add `root to: "content/pages#root"` add the bottom of your `config/routes.erb`.
+
+This is automatically added for you when you create a `Page` collection.
+
+
+## Markdown support
 
 Perron supports markdown with the `markdownify` helper.
 
-There are no markdown gems bundled by default, so you'll need to add one of these:
+There are no markdown gems bundled by default, so you'll need to add one of these to your `Gemfile`:
 
-- CommonMarker
-- Kramdown
-- Redcarpet
+- `commonmarker`
+- `kramdown`
+- `redcarpet`
 
 ```bash
 bundle add {commonmarker,kramdown,redcarpet}
 ```
 
+### Configuration
 
-## HTML Transformations
+To pass options to the parser, set `markdown_options` in `config/initializers/perron.rb`. The options hash is passed directly to the chosen library.
+
+**Commonmarker**
+```ruby
+# Options are passed as keyword arguments.
+Perron.configuration.markdown_options = { options: [:HARDBREAKS], extensions: [:table] }
+```
+
+**Kramdown**
+```ruby
+# Options are passed as a standard hash.
+Perron.configuration.markdown_options = { input: "GFM", smart_quotes: "apos,quot" }
+```
+
+**Redcarpet**
+```ruby
+# Options are nested under :renderer_options and :markdown_options.
+Perron.configuration.markdown_options = {
+  renderer_options: { hard_wrap: true },
+  markdown_options: { tables: true, autolink: true }
+}
+```
+
+
+## HTML transformations
 
 Perron can post-process the HTML generated from your Markdown content.
 
@@ -100,19 +150,20 @@ Perron can post-process the HTML generated from your Markdown content.
 
 Apply transformations by passing an array of processor names or classes to the `markdownify` helper via the `process` option.
 ```erb
-<%= markdownify @resource.content, process: %w[target_blank lazy_load_images] %>
+<%= markdownify @resource.content, process: %w[lazy_load_images syntax_highlight target_blank] %>
 ```
 
 
-### Available Processors
+### Available processors
 
 The following processors are built-in and can be activated by passing their string name:
 
 - `target_blank`: Adds `target="_blank"` to all external links;
 - `lazy_load_images`: Adds `loading="lazy"` to all `<img>` tags.
+- `syntax_highlight`: Applies syntax highlighting to fenced code blocks (e.g., \`\`\`ruby). This requires adding the `rouge` gem to your Gemfile (`bundle add rouge`). You will also need to include a Rouge CSS theme for colors to appear.
 
 
-### Creating Your Own
+### Creating your own processors
 
 You can create your own processor by defining a class that inherits from `Perron::HtmlProcessor::Base` and implements a `process` method.
 Then, pass the class constant directly in the `process` array.
@@ -184,19 +235,8 @@ Check out our amazing features:
 <% end %>
 ```
 
-**Result:**
-```html
-<p>Check out our amazing features:</p>
-<ul>
-  <li>Rails based</li>
-  <li>SEO friendly</li>
-  <li>Markdown first</li>
-  <li>ERB support</li>
-</ul>
-```
-
 
-## Data Files
+## Data files
 
 Perron can consume structured data from YML, JSON, or CSV files, making them available within your templates.
 This is useful for populating features, team members, or any other repeated data structure.
@@ -211,12 +251,12 @@ To use a data file, instantiate `Perron::Site.data` with the basename of the fil
 <% end %>
 ```
 
-### File Location and Formats
+### File location and formats
 
 By default, Perron looks up `app/content/data/` for files with a `.yml`, `.json`, or `.csv` extension.
 For a `features` call, it would find `features.yml`, `features.json`, or `features.csv`. You can also provide a path to any data file, via `Perron::Data.new("path/to/data.json")`.
 
-### Accessing Data
+### Accessing data
 
 The wrapper object provides flexible, read-only access to each record's attributes. Both dot notation and hash-like key access are supported.
 ```ruby
@@ -224,6 +264,22 @@ feature.name
 feature[:name]
 ```
 
+### Rendering
+
+You can render data collections directly using Rails-like partial rendering. When you call `render` on a data collection, Perron will automatically render a partial for each item.
+```erb
+<%= render Perron::Site.data.features %>
+```
+
+This expects a partial at `app/views/content/features/_feature.html.erb` that will be rendered once for each feature in your data file. The individual record is made available as a local variable matching the singular form of the collection name.
+```erb
+<!-- app/views/content/features/_feature.html.erb -->
+<div class="feature">
+  <h4><%= feature.name %></h4>
+  <p><%= feature.description %></p>
+</div>
+```
+
 
 ## Feeds
 
@@ -260,9 +316,14 @@ Feeds are configured within the `Resource` class corresponding to a collection:
 class Content::Post < Perron::Resource
   configure do |config|
     config.feeds.rss.enabled = true
+    # config.feeds.rss.title = "My RSS feed" # defaults to configured site_name
+    # config.feeds.rss.description = "My RSS feed description" # defaults to configured site_description
     # config.feeds.rss.path = "path-to-feed.xml"
     # config.feeds.rss.max_items = 25
+    #
     config.feeds.json.enabled = true
+    # config.feeds.json.title = "My JSON feed" # defaults to configured site_name
+    # config.feeds.json.description = "My JSON feed description" # defaults to configured site_description
     # config.feeds.json.max_items = 15
     # config.feeds.json.path = "path-to-feed.json"
   end
@@ -299,7 +360,7 @@ Or exclude certain tags:
 
 Values are determined with the following precedence, from highest to lowest:
 
-#### 1. Controller Action
+#### 1. Controller action
 
 Define a `@metadata` instance variable in your controller:
 ```ruby
@@ -314,10 +375,9 @@ class Content::PostsController < ApplicationController
 end
 ```
 
-#### 2. Page Frontmatter
+#### 2. Page frontmatter
 
 Add values to the YAML frontmatter in content files:
-
 ```yaml
 ---
 title: My Awesome Post
@@ -331,17 +391,19 @@ Your content here…
 
 #### 3. Collection configuration
 
-Set site-wide defaults in the initializer:
+Set collection defaults in the resource model:
 ```ruby
 class Content::Post < Perron::Resource
-  # …
+  Perron.configure do |config|
+    # …
 
-  config.metadata.description = "Put your routine tasks on autopilot"
-  config.metadata.author = "Helptail team"
+    config.metadata.description = "Put your routine tasks on autopilot"
+    config.metadata.author = "Helptail team"
+  end
 end
 ```
 
-#### 4. Default Values
+#### 4. Default values
 
 Set site-wide defaults in the initializer:
 ```ruby
@@ -354,13 +416,13 @@ end
 ```
 
 
-## Related Resources
+## Related resources
 
 The `related_resources` method allows to find and display a list of similar resources
-from the same collection. Similarity is calculated using the **TF-IDF** algorithm on the content of each resource.
+from the sme collection. Similarity is calculated using the **[TF-IDF](https://en.wikipedia.org/wiki/Tf%E2%80%93idf)** algorithm on the content of each resource.
 
 
-### Basic Usage
+### Basic usage
 
 To get a list of the 5 most similar resources, call the method on any resource instance.
 ```ruby
@@ -372,9 +434,9 @@ To get a list of the 5 most similar resources, call the method on any resource i
 ```
 
 
-## XML Sitemap
+## XML sitemap
 
-A sitemap is an XML file that lists all the pages of a website to help search engines discover and index content more efficiently, typically containing URLs, last modification dates, change frequency, and priority values.
+A sitemap is a XML file that lists all the pages of a website to help search engines discover and index content more efficiently, typically containing URLs, last modification dates, change frequency, and priority values.
 
 Enable it with the following line in the Perron configuration:
 ```ruby
@@ -409,7 +471,7 @@ sitemap_change_frequency: :daily
 ```
 
 
-## Building Your Static Site
+## Building your static site
 
 When in `standalone` mode and you're ready to generate your static site, run:
 ```bash

data/app/helpers/meta_tags_helper.rb

@@ -1,7 +1,7 @@
 # frozen_string_literal: true
 
 module MetaTagsHelper
-  def meta_tags(options = {}) = Perron::Metatags.new(resource).render(options)
+  def meta_tags(options = {}) = Perron::Metatags.new(resource.metadata).render(options)
 
   private
 

data/lib/generators/content/content_generator.rb

@@ -5,6 +5,8 @@ require "rails/generators/base"
 class ContentGenerator < Rails::Generators::NamedBase
   source_root File.expand_path("templates", __dir__)
 
+  class_option :force_plural, type: :boolean, default: false, desc: "Forces the use of a plural model name and class"
+
   argument :actions, type: :array, default: %w[index show], desc: "Specify which actions to generate (index/show)"
 
   def create_model
@@ -35,8 +37,23 @@ class ContentGenerator < Rails::Generators::NamedBase
     route "resources :#{plural_file_name}, module: :content, only: %w[#{actions.join(" ")}]"
   end
 
+  def add_root_route
+    return unless pages_controller?
+    return if root_route_exists?
+
+    inject_into_file "config/routes.rb", "  root to: \"content/pages#show\"\n", before: /^\s*end\s*$/
+  end
+
   private
 
+  def file_name
+    options[:force_plural] ? super.pluralize : super.singularize
+  end
+
+  def class_name
+    options[:force_plural] ? super.pluralize : super.singularize
+  end
+
   def view_directory = Rails.root.join("app", "views", "content", plural_file_name)
 
   def content_directory = Rails.root.join("app", "content", plural_file_name)
@@ -44,4 +61,12 @@ class ContentGenerator < Rails::Generators::NamedBase
   def plural_class_name = plural_name.camelize
 
   def pages_controller? = plural_file_name == "pages"
+
+  def root_route_exists?
+    routes = Rails.root.join("config", "routes.rb")
+
+    return false unless File.exist?(routes)
+
+    File.read(routes).match?(/\broot\s+to:/)
+  end
 end

data/lib/generators/content/templates/root.erb.tt

@@ -1,5 +1,4 @@
 ---
-slug: "/"
 ---
 
 Find me in `app/content/pages/root.erb`

data/lib/generators/perron/install_generator.rb

@@ -18,11 +18,16 @@ module Perron
     def add_markdown_gems
       append_to_file "Gemfile", <<~RUBY
 
-        # Perron can use one of the following gems. Uncomment your preferred choice and run `bundle install`
+        # Perron supports Markdown rendering using one of the following gems.
+        # Uncomment your preferred choice and run `bundle install`
         # gem "commonmarker"
         # gem "kramdown"
         # gem "redcarpet"
       RUBY
     end
+
+    def gitignore_output_folder
+      append_to_file ".gitignore", "/#{Perron.configuration.output}/\n"
+    end
   end
 end

data/lib/generators/perron/templates/README.md.tt

@@ -17,7 +17,7 @@ To use a data file, you can access it through the `Perron::Site.data` object fol
 
 This is a convenient shorthand for `Perron::Data.new("features")`, which can also be used directly:
 ```ruby
-
<%% Perron::Data.new("features").each do |feature| %>
+
<%% Perron::Data.new("features").each do |feature| %>
   <h4><%%= feature.name %></h4>
 
   <p><%%= feature.description %></p>
@@ -38,3 +38,20 @@ The wrapper object provides flexible, read-only access to each record's attribut
 feature.name
 feature[:name]
 ```
+
+
+## Rendering
+
+You can render data collections directly using Rails-like partial rendering. When you call `render` on a data collection, Perron will automatically render a partial for each item.
+```erb
+<%= render Perron::Site.data.features %>
+```
+
+This expects a partial at `app/views/content/features/_feature.html.erb` that will be rendered once for each feature in your data file. The individual record is made available as a local variable matching the singular form of the collection name.
+```erb
+<!-- app/views/content/features/_feature.html.erb -->
+<div class="feature">
+  <h4><%= feature.name %></h4>
+  <p><%= feature.description %></p>
+</div>
+```

data/lib/generators/perron/templates/initializer.rb.tt

@@ -3,14 +3,17 @@ Perron.configure do |config|
 
   # config.site_name = "Helptail"
 
-  # The build mode for Perron. Can be :standalone or :integrated.
+  # The build mode for Perron. Can be :standalone or :integrated
   # config.mode = :standalone
 
-  # In `integrated` mode, the root is skipped by default. Set to `true` to enable.
+  # In `integrated` mode, the root is skipped by default. Set to `true` to enable
   # config.include_root = false
 
   # config.default_url_options = {host: "helptail.com", protocol: "https", trailing_slash: true}
 
+  # The options hash is passed directly to the chosen library
+  # config.markdown_options = {}
+
   # Set default meta values
   # Examples:
   # - `config.metadata.description = "Put your routine tasks on autopilot"`

data/lib/perron/{site/collection.rb → collection.rb}

@@ -5,14 +5,14 @@ module Perron
     attr_reader :name
 
     def initialize(name)
-      @name = name
+      @name = name.inquiry
       @collection_path = File.join(Perron.configuration.input, name)
 
       raise Errors::CollectionNotFoundError, "No such collection: #{name}" unless File.exist?(@collection_path) && File.directory?(@collection_path)
     end
 
     def configuration(resource_class = "Content::#{name.classify}".safe_constantize)
-      resource_class.configuration
+      resource_class&.configuration
     end
 
     def all(resource_class = "Content::#{name.classify}".safe_constantize)
@@ -29,5 +29,11 @@ module Perron
 
       raise Errors::ResourceNotFoundError, "Resource not found with slug: #{slug}"
     end
+
+    def find_by_file_name(file_name, resource_class = Resource)
+      resource_class.new(
+        Perron.configuration.allowed_extensions.lazy.map { File.join(@collection_path, [file_name, it].join(".")) }.find { File.exist?(it) }
+      )
+    end
   end
 end

data/lib/perron/configuration.rb

@@ -28,12 +28,16 @@ module Perron
       @config.exclude_from_public = %w[assets storage]
       @config.excluded_assets = %w[action_cable actioncable actiontext activestorage rails-ujs trix turbo]
 
+      @config.view_unpublished = Rails.env.development?
+
       @config.default_url_options = {
         host: ENV.fetch("PERRON_HOST", "localhost:3000"),
         protocol: ENV.fetch("PERRON_PROTOCOL", "http"),
         trailing_slash: ENV.fetch("PERRON_TRAILING_SLASH", "true") == "true"
       }
 
+      @config.markdown_options = {}
+
       @config.sitemap = ActiveSupport::OrderedOptions.new
       @config.sitemap.enabled = false
       @config.sitemap.priority = 0.5

data/lib/perron/{site/data.rb → data.rb}

@@ -5,6 +5,7 @@ require "csv"
 module Perron
   class Data < SimpleDelegator
     def initialize(identifier)
+      @identifier = identifier
       @file_path = self.class.path_for!(identifier)
       @records = records
 
@@ -47,7 +48,7 @@ module Perron
         raise Errors::DataParseError, "Data in `#{@file_path}` must be an array of objects."
       end
 
-      data.map { Item.new(it) }
+      data.map { Item.new(it, identifier: @identifier) }
     end
 
     def rendered_from(path)
@@ -93,16 +94,29 @@ module Perron
       end
 
       def get_binding = binding
+
+      def default_url_options = Perron.configuration.default_url_options || {}
     end
     private_constant :HelperContext
 
     class Item
-      def initialize(attributes)
+      def initialize(attributes, identifier:)
         @attributes = attributes.transform_keys(&:to_sym)
+        @identifier = identifier
       end
 
       def [](key) = @attributes[key.to_sym]
 
+      def to_partial_path
+        @to_partial_path ||= begin
+          identifier = @identifier.to_s
+          collection = File.extname(identifier).present? ? File.basename(identifier, ".*") : identifier
+          element = ActiveSupport::Inflector.underscore(ActiveSupport::Inflector.singularize(File.basename(collection)))
+
+          File.join("content", collection, element)
+        end
+      end
+
       def method_missing(method_name, *arguments, &block)
         return super if !@attributes.key?(method_name) || arguments.any? || block
 

data/lib/perron/feeds.rb

@@ -13,6 +13,7 @@ module Perron
 
           next if options[:only]&.map(&:to_s)&.exclude?(collection_name)
           next if options[:except]&.map(&:to_s)&.include?(collection_name)
+          next if collection.configuration.blank?
 
           collection.configuration.feeds.each do |type, feed|
             next unless feed.enabled && feed.path && MIME_TYPES.key?(type)

data/lib/perron/html_processor/syntax_highlight.rb

@@ -0,0 +1,30 @@
+# frozen_string_literal: true
+
+require "rouge"
+require "perron/html_processor/base"
+
+module Perron
+  class HtmlProcessor
+    class SyntaxHighlight < HtmlProcessor::Base
+      def process
+        @html.css('pre > code[class*="language-"]').each do |code_block|
+          language = code_block[:class][/(?<=language-)\S+/]
+
+          next if language.blank?
+
+          code_block.parent.replace(
+            highlight(code_block.text, with: language)
+          )
+        end
+      end
+
+      private
+
+      def highlight(code_block, with:)
+        lexer = Rouge::Lexer.find(with) || Rouge::Lexers::PlainText.new
+
+        Rouge::Formatters::HTMLPygments.new(::Rouge::Formatters::HTML.new).format(lexer.lex(code_block))
+      end
+    end
+  end
+end

data/lib/perron/html_processor.rb

@@ -11,11 +11,9 @@ module Perron
     end
 
     def process
-      document = Nokogiri::HTML::DocumentFragment.parse(@html)
-
-      @processors.each { it.new(document).process }
-
-      document.to_html
+      Nokogiri::HTML::DocumentFragment.parse(@html).tap do |document|
+        @processors.each { it.new(document).process }
+      end.to_html
     end
 
     private
@@ -23,7 +21,13 @@ module Perron
     BUILT_IN = {
       "target_blank" => Perron::HtmlProcessor::TargetBlank,
       "lazy_load_images" => Perron::HtmlProcessor::LazyLoadImages
-    }
+    }.tap do |processors|
+      require "rouge"
+      require "perron/html_processor/syntax_highlight"
+
+      processors["syntax_highlight"] = Perron::HtmlProcessor::SyntaxHighlight
+    rescue LoadError
+    end
 
     def find_by(identifier)
       case identifier
@@ -43,8 +47,8 @@ module Perron
 
       return processor if processor
 
-      raise Perron::Errors::ProcessorNotFoundError,
-        "Could not find processor `#{name}`. It is not a Perron-included processor and the constant `#{name.camelize}` could not be found."
+      raise Perron::Errors::ProcessorNotFoundError, "The `syntax_highlight` processor requires `rouge`. Run `bundle add rouge` to add it to your Gemfile." if name.inquiry.syntax_highlight?
+      raise Perron::Errors::ProcessorNotFoundError, "Could not find processor `#{name}`. It is not a Perron-included processor and the constant `#{name.camelize}` could not be found."
     end
   end
 end