perron 0.9.1 → 0.11.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: cce790442290a0fedc4e4db328e3358b60a7edafafc6a0c980cec22d6f02fba5
-  data.tar.gz: c0a48eecc48c7a3230de6c36bf3a9180c9125b389282b0f311c02638b2db41cf
+  metadata.gz: 1757232a5830a600f00f1517b0aa26c0f95cc55005c32cdb7865282b522cefec
+  data.tar.gz: ba9a09ab06d80c8cc266c210d51770c5577d079dbfab6226f058c1f39a974505
 SHA512:
-  metadata.gz: e3f7bce10120b2feaf667051c8b67efd58adffb83a91d7d853b79b408bfa04cf5e004f40e99357059871c51f42aaf8ee26d32e4b36b776fcb9936309d1a7e94a
-  data.tar.gz: 9324e15f3d236809cf9422da8e8500d302e64a980352c5a9163734d908f8ecd1774cd1350d762487e9795df887d026858e3bd3bcab440c8f9fb1c547913295d9
+  metadata.gz: 82e81dbe7b346d47d539ab50b098c1b2542241d8864e3ed0cddf3e565b39785ae6710718a3db158cacaa27e67ea436960b88b012851ec5e85d7c91d3d0baa718
+  data.tar.gz: bdc619b82756afede00259a7f89970bac482a2e7204f2b8a66ad80b798467604b934462fe69d93e9d70e359abc298b0f72fcbf6842dde0258b7aaabe14a5042c

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.9.1)
+    perron (0.11.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
 
@@ -31,7 +31,7 @@ rails generate perron:install
 This creates an initializer:
 ```ruby
 Perron.configure do |config|
-  config.site_name = "AppRefresher"
+  config.site_name = "Helptail"
 end
 ```
 
@@ -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 content
 
 ```bash
 bin/rails generate content Post
@@ -69,29 +69,52 @@ This will create the following files:
 * Adds route: `resources :posts, module: :content, only: %w[index show]`
 
 
-### Setting a Root Page
+### 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).
+To set a root page, include `Perron::Root` in your `Content::PagesController` and add a `app/content/pages/root.{md,erb,*}` file. This is automatically added for you when you create a `Page` collection.
 
-This is automatically added when you create a `Page` collection.
 
-
-## Markdown Support
+## 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
+
+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
+## HTML transformations
 
 Perron can post-process the HTML generated from your Markdown content.
 
@@ -100,19 +123,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.
@@ -131,7 +155,61 @@ end
 ```
 
 
-## Data Files
+### Embed Ruby
+
+Perron provides flexible options for embedding dynamic Ruby code in your content using ERB.
+
+
+#### 1. File extension
+
+Any content file with a `.erb` extension (e.g., `about.erb`) will automatically have its content processed as ERB.
+
+
+#### 2. Frontmatter
+
+You can enable ERB processing on a per-file basis, even for standard `.md` files, by adding `erb: true` to the file's frontmatter.
+```markdown
+---
+title: Dynamic Page
+erb: true
+---
+
+This entire page will be processed by ERB.
+The current time is: <%= Time.current.to_fs(:long_ordinal) %>.
+```
+
+
+#### 3. `erbify` helper
+
+For the most granular control, the `erbify` helper allows to process specific sections of a file as ERB.
+This is ideal for generating dynamic content like lists or tables from your resource's metadata, without needing to enable ERB for the entire file. The `erbify` helper can be used with a string or, more commonly, a block.
+
+**Example:** Generating a list from frontmatter data in a standard `.md` file.
+```markdown
+---
+title: Features
+features:
+  - Rails based
+  - SEO friendly
+  - Markdown first
+  - ERB support
+---
+
+Check out our amazing features:
+
+<%= erbify do %>
+  <ul>
+    <% @resource.metadata.features.each do |feature| %>
+      <li>
+        <%= feature %>
+      </li>
+    <% end %>
+  </ul>
+<% end %>
+```
+
+
+## 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.
@@ -146,12 +224,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
@@ -159,6 +237,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/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/features/_feature.html.erb -->
+<div class="feature">
+  <h4><%= feature.name %></h4>
+  <p><%= feature.description %></p>
+</div>
+```
+
 
 ## Feeds
 
@@ -234,7 +328,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
@@ -249,10 +343,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
@@ -266,36 +359,36 @@ 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
   # …
 
-  config.metadata.description = "AI-powered tool to keep your knowledge base articles images/screenshots and content up-to-date"
-  config.metadata.author = "Rails Designer"
+  config.metadata.description = "Put your routine tasks on autopilot"
+  config.metadata.author = "Helptail team"
 end
 ```
 
-#### 4. Default Values
+#### 4. Default values
 
 Set site-wide defaults in the initializer:
 ```ruby
 Perron.configure do |config|
   # …
 
-  config.metadata.description = "AI-powered tool to keep your knowledge base articles images/screenshots and content up-to-date"
-  config.metadata.author = "Rails Designer"
+  config.metadata.description = "Put your routine tasks on autopilot"
+  config.metadata.author = "Helptail team"
 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
@@ -307,9 +400,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
@@ -344,7 +437,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/app/helpers/perron/erb_helper.rb

@@ -0,0 +1,9 @@
+# frozen_string_literal: true
+
+module Perron
+  module ErbHelper
+    def erbify(content = nil, options = {}, &block)
+      Perron::Resource::Renderer.erb(content || capture(&block).strip_heredoc, {resource: @resource})
+    end
+  end
+end

data/lib/generators/content/content_generator.rb

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 require "rails/generators/base"
 
 class ContentGenerator < Rails::Generators::NamedBase

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

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 module Perron
   class InstallGenerator < Rails::Generators::Base
     source_root File.expand_path("templates", __dir__)
@@ -12,5 +14,16 @@ module Perron
 
       template "README.md.tt", File.join(data_directory, "README.md")
     end
+
+    def add_markdown_gems
+      append_to_file "Gemfile", <<~RUBY
+
+        # 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
   end
 end

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

@@ -1,20 +1,23 @@
 Perron.configure do |config|
   # config.output = "output"
 
-  # config.site_name = "AppRefresher"
+  # 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: "apprefresher.com", protocol: "https", trailing_slash: true}
+  # 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 = "AI-powered tool to keep your knowledge base articles images/screenshots and content up-to-date"`
-  # - `config.metadata.author = "Rails Designer"`
+  # - `config.metadata.description = "Put your routine tasks on autopilot"`
+  # - `config.metadata.author = "Helptail Team"`
 
   # Set meta title suffix
   # config.metadata.title_suffix = nil

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

@@ -5,7 +5,7 @@ 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)
@@ -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

@@ -13,24 +13,31 @@ module Perron
     def initialize
       @config = ActiveSupport::OrderedOptions.new
 
+      @config.site_name = nil
+      @config.site_description = nil
+
+      @config.site_email = nil
+
       @config.output = "output"
 
       @config.mode = :standalone
       @config.include_root = false
 
-      @config.site_name = nil
-      @config.site_description = nil
+      @config.allowed_extensions = %w[erb md]
 
-      @config.allowed_extensions = [".erb", ".md"]
       @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/data/proxy.rb

@@ -0,0 +1,47 @@
+# frozen_string_literal: true
+
+module Perron
+  class Data
+    class Proxy
+      include Enumerable
+
+      def initialize(parts = [])
+        @parts = parts
+        @data = data_for_proxy
+      end
+
+      def each(&block) = @data.each(&block)
+
+      def inspect = @data.inspect
+
+      def respond_to_missing?(name, include_private = false)
+        identifier = File.join(*@parts, name.to_s)
+
+        Perron::Data.directory?(identifier) || Perron::Data.path_for(identifier) || super
+      end
+
+      def method_missing(name, *arguments, &block)
+        raise ArgumentError, "Data access does not accept arguments" if arguments.any? || block
+
+        new_parts = @parts + [name.to_s]
+        identifier = File.join(*new_parts)
+
+        return Proxy.new(new_parts) if Perron::Data.directory?(identifier)
+        return Perron::Data.new(identifier) if Perron::Data.path_for(identifier)
+
+        super
+      end
+
+      private
+
+      def data_for_proxy
+        return [] if @parts.empty?
+
+        identifier = File.join(*@parts)
+        data_path = Perron::Data.path_for(identifier) || Perron::Data.path_for(File.join(identifier, "index"))
+
+        data_path ? Perron::Data.new(data_path) : []
+      end
+    end
+  end
+end

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

@@ -1,19 +1,37 @@
 # frozen_string_literal: true
 
-require "erb"
-require "singleton"
-
 require "csv"
 
 module Perron
   class Data < SimpleDelegator
     def initialize(identifier)
-      @file_path = path_for(identifier)
+      @identifier = identifier
+      @file_path = self.class.path_for!(identifier)
       @records = records
 
       super(records)
     end
 
+    class << self
+      def path_for(identifier)
+        path = Pathname.new(identifier)
+
+        return path.to_s if path.file? && path.absolute?
+
+        base_path = Rails.root.join("app", "content", "data")
+
+        SUPPORTED_EXTENSIONS.lazy.map { base_path.join("#{identifier}#{it}") }.find(&:exist?)&.to_s
+      end
+
+      def path_for!(identifier)
+        path_for(identifier).tap do |path|
+          raise Errors::FileNotFoundError, "No data file found for `#{identifier}`" unless path
+        end
+      end
+
+      def directory?(identifier) = Dir.exist?(Rails.root.join("app", "content", "data", identifier))
+    end
+
     private
 
     PARSER_METHODS = {
@@ -22,24 +40,15 @@ module Perron
     }.freeze
     SUPPORTED_EXTENSIONS = PARSER_METHODS.keys
 
-    def path_for(identifier)
-      path = Pathname.new(identifier)
-
-      return path.to_s if path.file? && path.absolute?
-
-      path = SUPPORTED_EXTENSIONS.lazy.map { Rails.root.join("app", "content", "data").join("#{identifier}#{it}") }.find(&:exist?)
-      path&.to_s or raise Errors::FileNotFoundError, "No data file found for '#{identifier}'"
-    end
-
     def records
       content = rendered_from(@file_path)
       data = parsed_from(content, @file_path)
 
       unless data.is_a?(Array)
-        raise Errors::DataParseError, "Data in '#{@file_path}' must be an array of objects."
+        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)
@@ -89,12 +98,23 @@ module Perron
     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/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