perron 0.12.0 → 0.13.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 70a9d142afefaac54496efbd93312cae38e14525b7f6310be576f74e7f9dfb4d
-  data.tar.gz: fd010ef141b72700120c926a104b8f33f72971d94e58ae01c8c793424d4c5319
+  metadata.gz: 4a0f1b173ae94ac69df1bf9fe680062fa7d07ef6af132677313e80a1d909cb68
+  data.tar.gz: 6e6c7865e13a312b6bdac601d6d8878f13136c8d70734ceb5c03fa5ea8d83159
 SHA512:
-  metadata.gz: 9ab5c1d522c8645f3470451e74c7a5a3475f1a683d6dc953e88fd8fb123e4477558ae99839f2db4742741663c2957eec9d94696d05d7936aa1df14880a5d59a4
-  data.tar.gz: fb40411ad56556967b82396d1bb540766550e73131b9358f870f441c75bd1538c9ef071b3fcb4a6c371f389ee7a1a031c101c4e24cb76b9875b4841756a68dc7
+  metadata.gz: '066983a2578dabbc1d1033f8e9d36065ff03cd9d46fde15cc77348086c114e23c9052aff9e2087bc7e429584bcdb99821bdb1195ba908053f7b5d80966b6133c'
+  data.tar.gz: 98eafaeed24b4395c55f4847cf672941f99f551833f15c29cf6a8e3974c8ff0d4da7facc6af87e400e95449b6b76687f3f3c89e14ee3ef60cd1b89583271f0f1

data/Gemfile.lock

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

data/README.md

@@ -13,489 +13,9 @@ A Rails-based static site generator.
 </a>
 
 
-## Getting started
+## Documentation
 
-### Installation
-
-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|
-  config.site_name = "Helptail"
-end
-```
-
-
-## Mode
-
-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` |
-| :--- | :--- | :--- |
-| **Use Case** | Full static site for hosts like Netlify/Vercel | Add static pages to a live Rails app |
-| **Output** | `output/` directory | `public/` directory |
-| **Asset Handling** | Via Perron | Via Asset Pipeline |
-
-
-## Collections
-
-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]`.
-
-
-### Create a new collection
-
-```bash
-bin/rails generate content Post
-```
-
-This will create the following files:
-
-* `app/models/content/post.rb`
-* `app/controllers/content/posts_controller.rb`
-* `app/views/content/posts/index.html.erb`
-* `app/views/content/posts/show.html.erb`
-
-And adds a route: `resources :posts, module: :content, only: %w[index show]`
-
-
-### 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> %>
-```
-
-
-### 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. 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 to your `Gemfile`:
-
-- `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
-
-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[lazy_load_images syntax_highlight target_blank] %>
-```
-
-
-### 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 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.
-
-```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] %>
-```
-
-
-### 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.
-
-### Usage
-
-To use a data file, instantiate `Perron::Site.data` with the basename of the file and iterate over the result.
-```erb
-<% Perron::Site.data.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 `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
-
-The wrapper object provides flexible, read-only access to each record's attributes. Both dot notation and hash-like key access are supported.
-```ruby
-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
-
-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.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
-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:
-```erb
-<head>
-  …
-  <%= meta_tags %>
-  …
-</head>
-```
-
-You can render specific subsets of tags:
-```erb
-<%= meta_tags only: %w[title description] %>
-```
-
-Or exclude certain tags:
-```erb
-<%= meta_tags except: %w[twitter_card twitter_image] %>
-```
-
-### Priority
-
-Values are determined with the following precedence, from highest to lowest:
-
-#### 1. Controller action
-
-Define a `@metadata` instance variable in your controller:
-```ruby
-class Content::PostsController < ApplicationController
-  def index
-    @metadata = {
-      title: "All Blog Posts",
-      description: "A collection of our articles."
-    }
-    @resources = Content::Post.all
-  end
-end
-```
-
-#### 2. Page frontmatter
-
-Add values to the YAML frontmatter in content files:
-```yaml
----
-title: My Awesome Post
-description: A deep dive into how meta tags work.
-image: /assets/images/my-awesome-post.png
-author: Kendall
----
-
-Your content here…
-```
-
-#### 3. Collection configuration
-
-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"
-  end
-end
-```
-
-#### 4. Default values
-
-Set site-wide defaults in the initializer:
-```ruby
-Perron.configure do |config|
-  # …
-
-  config.metadata.description = "Put your routine tasks on autopilot"
-  config.metadata.author = "Helptail team"
-end
-```
-
-
-## Related resources
-
-The `related_resources` method allows to find and display a list of similar resources
-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
-
-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 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
-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:
-```bash
-RAILS_ENV=production rails perron:build
-```
-
-This will create your static site in the configured output directory (`output` by default).
-
-
-## Sites using Perron
-
-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)
-
-
-## Contributing
-
-This project uses [Standard](https://github.com/testdouble/standard) for formatting Ruby code. Please run `be standardrb` before submitting pull requests. Run tests with `rails test`.
+📑 [See the docs site (built with Perron!)](https://perron.railsdesigner.com/docs/)
 
 
 ## License

data/lib/generators/content/USAGE

@@ -0,0 +1,16 @@
+Description:
+    Creates a new content model with specified actions
+
+Example:
+    rails generate content post
+
+    This will create:
+      - app/models/content/post.rb
+      - app/controllers/content/posts_controller.rb
+      - app/views/content/posts/index.html.erb
+      - app/views/content/posts/show.html.erb
+      - …and add `resource :posts, module: :content, only: %w[index show]` to `config/routes.rb`
+
+Arguments:
+    NAME: Name of the content model
+    actions: List of actions to generate (index or show)

data/lib/generators/content/content_generator.rb

@@ -7,7 +7,7 @@ class ContentGenerator < Rails::Generators::NamedBase
 
   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)"
+  argument :actions, type: :array, default: %w[index show], banner: "actions", desc: "Specify which actions to generate (index/show)"
 
   def create_model
     template "model.rb.tt", File.join("app/models/content", "#{file_name}.rb")

data/lib/generators/perron/install_generator.rb

@@ -4,6 +4,8 @@ module Perron
   class InstallGenerator < Rails::Generators::Base
     source_root File.expand_path("templates", __dir__)
 
+    desc "Install Perron in your Rails app"
+
     def copy_initializer
       template "initializer.rb.tt", "config/initializers/perron.rb"
     end

data/lib/perron/resource/table_of_content.rb

@@ -0,0 +1,58 @@
+# frozen_string_literal: true
+
+module Perron
+  class Resource
+    module TableOfContent
+      extend ActiveSupport::Concern
+
+      def table_of_content(levels: %w[h1 h2 h3 h4 h5 h6])
+        return [] if content.blank? || metadata.toc == false
+
+        document = Nokogiri::HTML::DocumentFragment.parse(Markdown.render(content))
+        headings = extract_headings from: document, levels: levels.join(", ")
+
+        Builder.new.build(headings)
+      end
+      alias_method :table_of_contents, :table_of_content
+      alias_method :toc, :table_of_content
+
+      private
+
+      Item = ::Data.define(:id, :text, :level, :children)
+
+      def extract_headings(from:, levels:)
+        from.css(levels).each_with_object([]) do |heading, headings|
+          heading.tap do |node|
+            heading_text = node.text.strip
+            id = node["id"] || node.at("a")&.[]("id")
+
+            next if heading_text.empty? || id.blank?
+
+            headings << Item.new(
+              id: id,
+              text: heading_text,
+              level: node.name[1..].to_i,
+              children: []
+            )
+          end
+        end
+      end
+
+      class Builder
+        def build(headings)
+          parents = {0 => {children: []}}
+
+          headings.each_with_object(parents[0][:children]) do |heading, _|
+            parents.delete_if { |level, _| level >= heading.level }
+
+            parent = parents[parents.keys.select { it < heading.level }.max || 0]
+
+            (parent.is_a?(Hash) ? parent[:children] : parent.children) << heading
+
+            parents[heading.level] = heading
+          end
+        end
+      end
+    end
+  end
+end

data/lib/perron/resource.rb

@@ -9,6 +9,7 @@ require "perron/resource/related"
 require "perron/resource/renderer"
 require "perron/resource/slug"
 require "perron/resource/separator"
+require "perron/resource/table_of_content"
 
 module Perron
   class Resource
@@ -18,6 +19,7 @@ module Perron
     include Perron::Resource::Core
     include Perron::Resource::ClassMethods
     include Perron::Resource::Publishable
+    include Perron::Resource::TableOfContent
 
     attr_reader :file_path, :id
 
@@ -48,9 +50,9 @@ module Perron
     def content
       page_content = Perron::Resource::Separator.new(raw_content).content
 
-      return page_content unless erb_processing?
+      return Perron::Resource::Renderer.erb(page_content, resource: self) if erb_processing?
 
-      Perron::Resource::Renderer.erb(page_content, {resource: self})
+      render_inline_erb using: page_content
     end
 
     def to_partial_path
@@ -79,6 +81,12 @@ module Perron
       ).first(ID_LENGTH)
     end
 
+    def render_inline_erb(using:)
+      using.gsub(/<%=\s*erbify\s+do\s*%>(.*?)<%\s*end\s*%>/m) do
+        Perron::Resource::Renderer.erb(Regexp.last_match(1).strip_heredoc, resource: self)
+      end
+    end
+
     def erb_processing?
       @file_path.ends_with?(".erb") || metadata.erb == true
     end

data/lib/perron/site/builder/feeds/json.rb

@@ -17,6 +17,7 @@ module Perron
 
             hash = Rails.application.routes.url_helpers.with_options(@configuration.default_url_options) do |url|
               {
+                generator: "Perron (#{Perron::VERSION})",
                 version: "https://jsonfeed.org/version/1.1",
                 home_page_url: @configuration.url,
                 title: feed_configuration.title.presence || @configuration.site_name,

data/lib/perron/site/builder/feeds/rss.rb

@@ -18,10 +18,10 @@ module Perron
             Nokogiri::XML::Builder.new(encoding: "UTF-8") do |xml|
               xml.rss(:version => "2.0", "xmlns:atom" => "http://www.w3.org/2005/Atom") do
                 xml.channel do
+                  xml.generator "Perron (#{Perron::VERSION})"
                   xml.title feed_configuration.title.presence || @configuration.site_name
                   xml.description feed_configuration.description.presence || @configuration.site_description
                   xml.link @configuration.url
-                  xml.generator "Perron (#{Perron::VERSION})"
 
                   Rails.application.routes.url_helpers.with_options(@configuration.default_url_options) do |url|
                     resources.each do |resource|

data/lib/perron/site/builder/paths.rb

@@ -18,6 +18,10 @@ module Perron
               next if skip? root
 
               @paths << (root ? routes.root_path : routes.public_send(show_path, resource))
+
+              (resource.class.try(:nested_routes) || []).each do |nested|
+                @paths << routes.polymorphic_path([resource, nested])
+              end
             end
           end
         end

data/lib/perron/version.rb

@@ -1,3 +1,3 @@
 module Perron
-  VERSION = "0.12.0"
+  VERSION = "0.13.0"
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: perron
 version: !ruby/object:Gem::Version
-  version: 0.12.0
+  version: 0.13.0
 platform: ruby
 authors:
 - Rails Designer Developers
@@ -86,6 +86,7 @@ files:
 - bin/rails
 - bin/release
 - bin/setup
+- lib/generators/content/USAGE
 - lib/generators/content/content_generator.rb
 - lib/generators/content/templates/controller.rb.tt
 - lib/generators/content/templates/index.html.erb.tt
@@ -122,6 +123,7 @@ files:
 - lib/perron/resource/renderer.rb
 - lib/perron/resource/separator.rb
 - lib/perron/resource/slug.rb
+- lib/perron/resource/table_of_content.rb
 - lib/perron/root.rb
 - lib/perron/site.rb
 - lib/perron/site/builder.rb