perron 0.7.0 → 0.9.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 4ab1fe5550ba3bfd474381303929b49e9dac552d2d086bcbeb79c0760ad59979
-  data.tar.gz: 4b64af0d6128def66419351d50f74dffc29e8c74b1cf6f00ec004dc122f426cb
+  metadata.gz: 2f225e6b75be66a9fd394e0c87b3c63c878042664e3acfeaa7ff68cc449af1b1
+  data.tar.gz: a963c546505ffa227310b7e0d8cba7a40446d0a70b86b8491f7baa761bf6e0cb
 SHA512:
-  metadata.gz: a3490ff02b1c8612e99f6403d0db98008b88461dd73b430b3470623a33bd4bd5bdc2945ff61a7bae821e1ff1bbcd3ba9f707be86c28724807300cdf75f476493
-  data.tar.gz: 505b439b20f2dbc5d2310aa56d8b8bcd99b793ddf83395f5652be1814e598c26d3f2154cde99531ad79d621ef7377cb12ddc076677e233a54c96faa875ff4cbf
+  metadata.gz: 3f9926aba1d4c88204131fc61564173334a059bcc832c7457f0c31a276b1e05d1466c196afc8a25f54091402436618bee7ae97c6397fdb0660a1da50dbb80231
+  data.tar.gz: 54f74446e210fb7ac299b0dc5496bcce18676128fdf9af994403513f8f4ddff37aee8933e58cc5d4e3cbf7316667b0b19860863ddaec6da78ca79c9ac81d3fd6

data/Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    perron (0.7.0)
+    perron (0.9.0)
       csv
       json
       psych

data/README.md

@@ -17,11 +17,17 @@ A Rails-based static site generator.
 
 ### Installation
 
-Start by generating the configuration file:
+Start by adding Perron:
+```bash
+bundle add perron
+```
+
+Then generate the initializer:
 ```bash
 rails generate perron:install
 ```
 
+
 This creates an initializer:
 ```ruby
 Perron.configure do |config|
@@ -85,6 +91,46 @@ bundle add {commonmarker,kramdown,redcarpet}
 ```
 
 
+## HTML Transformations
+
+Perron can post-process the HTML generated from your Markdown content.
+
+
+### Usage
+
+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] %>
+```
+
+
+### 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.
+
+
+### Creating Your Own
+
+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.
+
+```ruby
+# app/processors/add_nofollow_processor.rb
+class AddNofollowProcessor < Perron::HtmlProcessor::Base
+  def process
+    @html.css("a[target=_blank]").each { it["rel"] = "nofollow" }
+  end
+end
+```
+
+```erb
+<%= markdownify @resource.content, process: ["target_blank", AddNofollowProcessor] %>
+```
+
+
 ## Data Files
 
 Perron can consume structured data from YML, JSON, or CSV files, making them available within your templates.
@@ -92,9 +138,9 @@ This is useful for populating features, team members, or any other repeated data
 
 ### Usage
 
-To use a data file, instantiate `Perron::Data` with the basename of the file and iterate over the result.
+To use a data file, instantiate `Perron::Site.data` with the basename of the file and iterate over the result.
 ```erb
-<% Perron::Data.new("features").each do |feature| %>
+<% Perron::Site.data.features.each do |feature| %>
   <h4><%= feature.name %></h4>
   <p><%= feature.description %></p>
 <% end %>
@@ -103,7 +149,7 @@ To use a data file, instantiate `Perron::Data` with the basename of the file and
 ### File Location and Formats
 
 By default, Perron looks up `app/content/data/` for files with a `.yml`, `.json`, or `.csv` extension.
-For a `new("features")` call, it would find `features.yml`, `features.json`, or `features.csv`. You can also provide a full, absolute path to any data file.
+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
 
@@ -114,11 +160,55 @@ feature[:name]
 ```
 
 
+## Feeds
+
+The `feeds` helper automatically generates HTML `<link>` tags for your site's RSS and JSON feeds.
+
+
+### Usage
+
+In your layout (e.g., `app/views/layouts/application.html.erb`), add the helper to the `<head>` section:
+```erb
+<head>
+  …
+  <%= feeds %>
+  …
+</head>
+```
+
+To render feeds for specific collections, such as `posts`:
+```erb
+<%= feeds only: %w[posts] %>
+```
+
+Similarly, you can exclude collections:
+```erb
+<%= feeds except: %w[pages] %>
+```
+
+
+### Configuration
+
+Feeds are configured within the `Resource` class corresponding to a collection:
+```ruby
+# app/models/content/post.rb
+class Content::Post < Perron::Resource
+  configure do |config|
+    config.feeds.rss.enabled = true
+    # config.feeds.rss.path = "path-to-feed.xml"
+    # config.feeds.rss.max_items = 25
+    config.feeds.json.enabled = true
+    # config.feeds.json.max_items = 15
+    # config.feeds.json.path = "path-to-feed.json"
+  end
+end
+```
+
+
 ## Metatags
 
 The `meta_tags` helper automatically generates SEO and social sharing meta tags for your pages.
 
-
 ### Usage
 
 In your layout (e.g., `app/views/layouts/application.html.erb`), add the helper to the `<head>` section:
@@ -174,7 +264,19 @@ author: Kendall
 Your content here…
 ```
 
-#### 3. Default Values
+#### 3. Collection configuration
+
+Set site-wide defaults in the initializer:
+```ruby
+class Content::Post < Perron::Resource
+  # …
+
+  config.metadata.description = "AI-powered tool to keep your knowledge base articles images/screenshots and content up-to-date"
+  config.metadata.author = "Rails Designer"
+end
+```
+
+#### 4. Default Values
 
 Set site-wide defaults in the initializer:
 ```ruby
@@ -187,6 +289,61 @@ end
 ```
 
 
+## 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.
+
+
+### Basic Usage
+
+To get a list of the 5 most similar resources, call the method on any resource instance.
+```ruby
+# app/views/content/posts/show.html.erb
+@resource.related_resources
+
+# Just the 3 most similar resources
+@resource.related_resources(limit: 3)
+```
+
+
+## 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.
+
+Enable it with the following line in the Perron configuration:
+```ruby
+Perron.configure do |config|
+  # …
+  config.sitemap.enabled = true
+  # config.sitemap.priority = 0.8
+  # config.sitemap.change_frequency = :monthly
+  # …
+end
+```
+
+Values can be overridden per collection…
+```ruby
+# app/models/content/post.rb
+class Content::Post < Perron::Resource
+  configure do |config|
+    config.sitemap.enabled = false
+    config.sitemap.priority = 0.5
+    config.sitemap.change_frequency = :weekly
+  end
+end
+```
+
+…or on a resource basis:
+```ruby
+# app/content/posts/my-first-post.md
+---
+sitemap_priority: 0.25
+sitemap_change_frequency: :daily
+---
+```
+
+
 ## Building Your Static Site
 
 When in `standalone` mode and you're ready to generate your static site, run:
@@ -203,9 +360,11 @@ Sites that use Perron.
 
 ### Standalone (as a SSG)
 - [AppRefresher](https://apprefresher.com)
+- [Helptail](https://helptail.com)
 
 ### Integrated (part of a Rails app)
-- [Rails Designers (private community for Rails UI engineers](https://railsdesigners.com)
+- [Rails Designers (private community for Rails UI engineers)](https://railsdesigners.com)
+
 
 ## Contributing
 

data/app/helpers/feeds_helper.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+module FeedsHelper
+  def feeds(options = {}) = Perron::Feeds.new.render(options)
+end

data/app/helpers/meta_tags_helper.rb

@@ -1,17 +1,15 @@
 # frozen_string_literal: true
 
 module MetaTagsHelper
-  def meta_tags(options = {})
-    Perron::Metatags.new(source).render(options)
-  end
+  def meta_tags(options = {}) = Perron::Metatags.new(resource).render(options)
 
   private
 
-  Source = Data.define(:path, :metadata, :published_at)
+  Resource = Data.define(:path, :metadata, :published_at)
 
-  def source
+  def resource
     return Source.new(request.path, @metadata, nil) if @metadata.present?
 
-    @resource || Source.new(request.path, {}, nil)
+    @resource || Resource.new(request.path, {}, nil)
   end
 end

data/app/helpers/perron/markdown_helper.rb

@@ -4,6 +4,10 @@ require "perron/markdown"
 
 module Perron
   module MarkdownHelper
-    def markdownify(content = nil, &block) = Perron::Markdown.render(content || capture(&block).strip_heredoc)
+    def markdownify(content = nil, options = {}, &block)
+      processors = options.fetch(:process, [])
+
+      Perron::Markdown.render(content || capture(&block).strip_heredoc, processors: processors)
+    end
   end
 end

data/lib/generators/perron/install_generator.rb

@@ -7,7 +7,7 @@ module Perron
     end
 
     def create_data_directory
-      data_directory = Rails.root.join("app", "views", "content", "data")
+      data_directory = Rails.root.join("app", "content", "data")
       empty_directory data_directory
 
       template "README.md.tt", File.join(data_directory, "README.md")

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

@@ -6,19 +6,29 @@ This is useful for populating features, team members, or any other repeated data
 
 ## Usage
 
-To use a data file, instantiate `Perron::Data` with the basename of the file and iterate over the result.
+To use a data file, you can access it through the `Perron::Site.data` object followed by the basename of the file:
 ```erb
-<% Perron::Data.new("features").each do |feature| %>
-  <h4><%= feature.name %></h4>
+<%% Perron::Site.data.features.each do |feature| %>
+  <h4><%%= feature.name %></h4>
 
-  <p><%= feature.description %></p>
-<% end %>
+  <p><%%= feature.description %></p>
+<%% end %>
 ```
 
+This is a convenient shorthand for `Perron::Data.new("features")`, which can also be used directly:
+```ruby
+
<%% Perron::Data.new("features").each do |feature| %>
+  <h4><%%= feature.name %></h4>
+
+  <p><%%= feature.description %></p>
+<%% end %>
+```
+
+
 ## File Location and Formats
 
 By default, Perron looks up `app/content/data/` for files with a `.yml`, `.json`, or `.csv` extension.
-For a `new("features")` call, it would find `features.yml`, `features.json`, or `features.csv`. You can also provide a full, absolute path to any data file.
+For a `new("features")` call, it would find `features.yml`, `features.json`, or `features.csv`. You can also provide a full, absolute path to any data file, like `Perron::Data.new("path-to-some-data-file")`.
 
 
 ## Accessing Data

data/lib/perron/configuration.rb

@@ -9,10 +9,6 @@ module Perron
     yield(configuration)
   end
 
-  def self.reset_configuration!
-    @configuration = Configuration.new
-  end
-
   class Configuration
     def initialize
       @config = ActiveSupport::OrderedOptions.new
@@ -23,6 +19,7 @@ module Perron
       @config.include_root = false
 
       @config.site_name = nil
+      @config.site_description = nil
 
       @config.allowed_extensions = [".erb", ".md"]
       @config.exclude_from_public = %w[assets storage]
@@ -34,11 +31,16 @@ module Perron
         trailing_slash: ENV.fetch("PERRON_TRAILING_SLASH", "true") == "true"
       }
 
+      @config.sitemap = ActiveSupport::OrderedOptions.new
+      @config.sitemap.enabled = false
+      @config.sitemap.priority = 0.5
+      @config.sitemap.change_frequency = :monthly
+
       @config.metadata = ActiveSupport::OrderedOptions.new
       @config.metadata.title_separator = " — "
     end
 
-    def input = "app/content"
+    def input = Rails.root.join("app", "content")
 
     def output
       mode.integrated? ? "public" : @config.output
@@ -48,6 +50,13 @@ module Perron
 
     def exclude_root? = !@config.include_root
 
+    def url
+      options = Perron.configuration.default_url_options
+      path = options[:trailing_slash] ? "/" : ""
+
+      URI.join("#{options[:protocol]}://#{options[:host]}", path).to_s
+    end
+
     def method_missing(method_name, ...)
       if @config.respond_to?(method_name)
         @config.send(method_name, ...)

data/lib/perron/errors.rb

@@ -9,5 +9,9 @@ module Perron
     class UnsupportedDataFormatError < StandardError; end
 
     class DataParseError < StandardError; end
+
+    class ProcessorNotFoundError < StandardError; end
+
+    class InvalidProcessorError < StandardError; end
   end
 end

data/lib/perron/feeds.rb

@@ -0,0 +1,38 @@
+# frozen_string_literal: true
+
+module Perron
+  class Feeds
+    include ActionView::Helpers::TagHelper
+
+    def render(options = {})
+      html_tags = []
+
+      Rails.application.routes.url_helpers.with_options(Perron.configuration.default_url_options) do |url|
+        Perron::Site.collections.each do |collection|
+          collection_name = collection.name.to_s
+
+          next if options[:only]&.map(&:to_s)&.exclude?(collection_name)
+          next if options[:except]&.map(&:to_s)&.include?(collection_name)
+
+          collection.configuration.feeds.each do |type, feed|
+            next unless feed.enabled && feed.path && MIME_TYPES.key?(type)
+
+            absolute_url = URI.join(url.root_url, feed.path).to_s
+            title = "#{collection.name.humanize} #{type.to_s.upcase} Feed"
+
+            html_tags << tag(:link, rel: "alternate", type: MIME_TYPES[type], title: title, href: absolute_url)
+          end
+        end
+      end
+
+      safe_join(html_tags, "\n")
+    end
+
+    private
+
+    MIME_TYPES = {
+      rss: "application/rss+xml",
+      json: "application/json"
+    }
+  end
+end

data/lib/perron/html_processor/base.rb

@@ -0,0 +1,15 @@
+# frozen_string_literal: true
+
+module Perron
+  class HtmlProcessor
+    class Base
+      def initialize(html)
+        @html = html
+      end
+
+      def process
+        raise NotImplementedError
+      end
+    end
+  end
+end

data/lib/perron/html_processor/lazy_load_images.rb

@@ -0,0 +1,13 @@
+# frozen_string_literal: true
+
+module Perron
+  class HtmlProcessor
+    class LazyLoadImages < HtmlProcessor::Base
+      def process
+        @html.css("img").each do |image|
+          image["loading"] = "lazy"
+        end
+      end
+    end
+  end
+end

data/lib/perron/html_processor/target_blank.rb

@@ -1,21 +1,17 @@
 # frozen_string_literal: true
 
+require "perron/html_processor/base"
+
 module Perron
   class HtmlProcessor
-    class TargetBlank
-      def initialize(html)
-        @html = html
-      end
-
+    class TargetBlank < HtmlProcessor::Base
       def process
         @html.css("a").each do |link|
           href = link["href"]
 
-          next unless href
-          next if href.start_with?("/", "#", "mailto:")
+          next if href.blank? || href.start_with?("/", "#", "mailto:")
 
           link["target"] = "_blank"
-          link["rel"] = "noopener"
         end
       end
     end

data/lib/perron/html_processor.rb

@@ -1,28 +1,50 @@
 # frozen_string_literal: true
 
 require "perron/html_processor/target_blank"
+require "perron/html_processor/lazy_load_images"
 
 module Perron
   class HtmlProcessor
-    def initialize(html)
+    def initialize(html, processors: [])
       @html = html
+      @processors = processors.map { find_by(it) }
     end
 
     def process
       document = Nokogiri::HTML::DocumentFragment.parse(@html)
 
-      PROCESSORS.each do |processor|
-        processor.new(document).process
-      end
+      @processors.each { it.new(document).process }
 
       document.to_html
     end
 
     private
 
-    # TODO: should be a configuration option
-    PROCESSORS = [
-      Perron::HtmlProcessor::TargetBlank
-    ]
+    BUILT_IN = {
+      "target_blank" => Perron::HtmlProcessor::TargetBlank,
+      "lazy_load_images" => Perron::HtmlProcessor::LazyLoadImages
+    }
+
+    def find_by(identifier)
+      case identifier
+      when String, Symbol
+        key = identifier.to_s
+
+        BUILT_IN[key] || find_class_by(key)
+      when Class
+        identifier
+      else
+        raise Perron::Errors::InvalidProcessorError, "Processor must be a String, Symbol, or Class, but got #{identifier.class.name}."
+      end
+    end
+
+    def find_class_by(name)
+      processor = name.camelize.safe_constantize
+
+      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."
+    end
   end
 end

data/lib/perron/markdown.rb

@@ -5,9 +5,9 @@ require "perron/html_processor"
 module Perron
   class Markdown
     class << self
-      def render(text)
+      def render(text, processors: [])
         parser.parse(text)
-          .then { Perron::HtmlProcessor.new(it).process }
+          .then { Perron::HtmlProcessor.new(it, processors: processors).process }
           .html_safe
       end
 

data/lib/perron/metatags.rb

@@ -20,6 +20,7 @@ module Perron
     private
 
     FRONTMATTER_KEY_MAP = {
+      "locale" => %w[og:locale],
       "image" => %w[og:image twitter:image],
       "author" => %w[og:author]
     }.freeze
@@ -27,33 +28,40 @@ module Perron
     def tags
       @tags ||= begin
         frontmatter = @resource&.metadata&.stringify_keys || {}
-        defaults = @config.metadata
+        collection_config = @resource.collection.configuration.metadata
+        site_config = @config.metadata
 
-        title = frontmatter["title"] || defaults["title"] || @config.site_name || Rails.application.name.underscore.camelize
-        description = frontmatter["description"] || defaults["description"]
-        author = frontmatter["author"] || defaults["author"]
-        image = frontmatter["image"] || defaults["image"]
-        og_image = frontmatter["og:image"] || image
-        twitter_image = frontmatter["twitter:image"] || og_image
+        title = frontmatter["title"] || collection_config["title"] || site_config["title"] || @config.site_name || Rails.application.name.underscore.camelize
+        type = frontmatter["type"] || collection_config["type"] || site_config["type"]
+        description = frontmatter["description"] || collection_config["description"] || site_config["description"]
+        logo = frontmatter["logo"] || collection_config["logo"] || site_config["logo"]
+        author = frontmatter["author"] || collection_config["author"] || site_config["author"]
+        locale = frontmatter["locale"] || collection_config["locale"] || site_config["locale"]
+
+        image = frontmatter["image"] || collection_config["image"] || site_config["image"]
+        og_image = frontmatter["og:image"] || collection_config["og:image"] || site_config["og:image"] || image
+        twitter_image = frontmatter["twitter:image"] || collection_config["twitter:image"] || site_config["twitter:image"] || og_image
 
         {
           title: title_tag(title),
           description: meta_tag(name: "description", content: description),
+          article_published: meta_tag(property: "article:published_time", content: @resource&.published_at),
 
-          og_type: meta_tag(property: "og:type", content: frontmatter["og:type"] || "article"),
           og_title: meta_tag(property: "og:title", content: frontmatter["og:title"] || title),
+          og_type: meta_tag(property: "og:type", content: frontmatter["og:type"] || type),
+          og_url: meta_tag(property: "og:url", content: canonical_url),
+          og_image: meta_tag(property: "og:image", content: og_image),
+
           og_description: meta_tag(property: "og:description", content: frontmatter["og:description"] || description),
           og_site_name: meta_tag(property: "og:site_name", content: @config.site_name),
-          og_image: meta_tag(property: "og:image", content: og_image),
+          og_logo: meta_tag(property: "og:logo", content: frontmatter["og:logo"] || logo),
           og_author: meta_tag(property: "og:author", content: frontmatter["og:author"] || author),
+          og_locale: meta_tag(property: "og:locale", content: frontmatter["og:locale"] || locale),
 
           twitter_card: meta_tag(name: "twitter:card", content: frontmatter["twitter:card"] || "summary_large_image"),
           twitter_title: meta_tag(name: "twitter:title", content: frontmatter["twitter:title"] || title),
           twitter_description: meta_tag(name: "twitter:description", content: frontmatter["twitter:description"] || description),
-          twitter_image: meta_tag(name: "twitter:image", content: twitter_image),
-          article_published: meta_tag(property: "article:published_time", content: @resource&.published_at),
-
-          og_url: meta_tag(property: "og:url", content: canonical_url)
+          twitter_image: meta_tag(name: "twitter:image", content: twitter_image)
         }
       end
     end