perron 0.0.1 → 0.6.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: adaceff47ea616f74cae034e46a3118592519103709fa65c9c8909492a8b1abb
-  data.tar.gz: d80d4b86cb22002462cc7c99217cbf784e95a14df860ea529911c5c6d127ddf0
+  metadata.gz: f91a86bc7ff57f28eb58ef9aac6b1d3e94c008a3570df359aca5f5e6b416c7e7
+  data.tar.gz: 53cd0a23ce3fbcd1fe90aa07a26577f34e66be5a8fd018c596498e34c67c5718
 SHA512:
-  metadata.gz: 3cbb1fc5c50b598ec29a85f1fbf5ce5b34a0052e0354b1bd05fa7e0446ad5784f3d0d2de113daed351d97f9471ad03623df23f55118ee25ddbc70493c253acf9
-  data.tar.gz: a90e0f986a7dfbeafa2c85264814750f5d9e050d7f8a4595532ed483c9bde8d0c59c2f72568149ca2c3319ec43e73783bf5dbe63761ed6e062b6174e7b7055f2
+  metadata.gz: dd5f18ac803ece9604f9187047c637e4be0f1ad31fb77bce0d73f97dc633ba60644a4d2638deadc2d2d05e6f5152e8050ecc4823caa1dd2c64d0da487618ee85
+  data.tar.gz: e99ffd6732c726f78f4a5e3f2ce07c571019b43d8028539ea1a5d6ad0d75f52f74d254808e3585f0d0e546b2d453e880f2291b2e088dc8e6fe8e63b496f5990d

data/Gemfile

@@ -0,0 +1,17 @@
+# frozen_string_literal: true
+
+source "https://rubygems.org"
+
+gemspec
+
+gem "rails", "~> 7.2.0"
+
+group :development do
+  gem "standard", "~> 1.50.0"
+end
+
+group :development, :test do
+  gem "rake", "~> 13.3.0"
+  gem "minitest", "~> 5.25", ">= 5.25.5"
+  gem "debug", "~> 1.11.0"
+end

data/Gemfile.lock

@@ -0,0 +1,273 @@
+PATH
+  remote: .
+  specs:
+    perron (0.6.0)
+      csv
+      json
+      psych
+      rails (>= 7.2.0)
+
+GEM
+  remote: https://rubygems.org/
+  specs:
+    actioncable (7.2.2.1)
+      actionpack (= 7.2.2.1)
+      activesupport (= 7.2.2.1)
+      nio4r (~> 2.0)
+      websocket-driver (>= 0.6.1)
+      zeitwerk (~> 2.6)
+    actionmailbox (7.2.2.1)
+      actionpack (= 7.2.2.1)
+      activejob (= 7.2.2.1)
+      activerecord (= 7.2.2.1)
+      activestorage (= 7.2.2.1)
+      activesupport (= 7.2.2.1)
+      mail (>= 2.8.0)
+    actionmailer (7.2.2.1)
+      actionpack (= 7.2.2.1)
+      actionview (= 7.2.2.1)
+      activejob (= 7.2.2.1)
+      activesupport (= 7.2.2.1)
+      mail (>= 2.8.0)
+      rails-dom-testing (~> 2.2)
+    actionpack (7.2.2.1)
+      actionview (= 7.2.2.1)
+      activesupport (= 7.2.2.1)
+      nokogiri (>= 1.8.5)
+      racc
+      rack (>= 2.2.4, < 3.2)
+      rack-session (>= 1.0.1)
+      rack-test (>= 0.6.3)
+      rails-dom-testing (~> 2.2)
+      rails-html-sanitizer (~> 1.6)
+      useragent (~> 0.16)
+    actiontext (7.2.2.1)
+      actionpack (= 7.2.2.1)
+      activerecord (= 7.2.2.1)
+      activestorage (= 7.2.2.1)
+      activesupport (= 7.2.2.1)
+      globalid (>= 0.6.0)
+      nokogiri (>= 1.8.5)
+    actionview (7.2.2.1)
+      activesupport (= 7.2.2.1)
+      builder (~> 3.1)
+      erubi (~> 1.11)
+      rails-dom-testing (~> 2.2)
+      rails-html-sanitizer (~> 1.6)
+    activejob (7.2.2.1)
+      activesupport (= 7.2.2.1)
+      globalid (>= 0.3.6)
+    activemodel (7.2.2.1)
+      activesupport (= 7.2.2.1)
+    activerecord (7.2.2.1)
+      activemodel (= 7.2.2.1)
+      activesupport (= 7.2.2.1)
+      timeout (>= 0.4.0)
+    activestorage (7.2.2.1)
+      actionpack (= 7.2.2.1)
+      activejob (= 7.2.2.1)
+      activerecord (= 7.2.2.1)
+      activesupport (= 7.2.2.1)
+      marcel (~> 1.0)
+    activesupport (7.2.2.1)
+      base64
+      benchmark (>= 0.3)
+      bigdecimal
+      concurrent-ruby (~> 1.0, >= 1.3.1)
+      connection_pool (>= 2.2.5)
+      drb
+      i18n (>= 1.6, < 2)
+      logger (>= 1.4.2)
+      minitest (>= 5.1)
+      securerandom (>= 0.3)
+      tzinfo (~> 2.0, >= 2.0.5)
+    ast (2.4.3)
+    base64 (0.3.0)
+    benchmark (0.4.1)
+    bigdecimal (3.2.2)
+    builder (3.3.0)
+    concurrent-ruby (1.3.5)
+    connection_pool (2.5.3)
+    crass (1.0.6)
+    csv (3.3.5)
+    date (3.4.1)
+    debug (1.11.0)
+      irb (~> 1.10)
+      reline (>= 0.3.8)
+    drb (2.2.3)
+    erb (5.0.1)
+    erubi (1.13.1)
+    globalid (1.2.1)
+      activesupport (>= 6.1)
+    i18n (1.14.7)
+      concurrent-ruby (~> 1.0)
+    io-console (0.8.0)
+    irb (1.15.2)
+      pp (>= 0.6.0)
+      rdoc (>= 4.0.0)
+      reline (>= 0.4.2)
+    json (2.12.2)
+    language_server-protocol (3.17.0.5)
+    lint_roller (1.1.0)
+    logger (1.7.0)
+    loofah (2.24.1)
+      crass (~> 1.0.2)
+      nokogiri (>= 1.12.0)
+    mail (2.8.1)
+      mini_mime (>= 0.1.1)
+      net-imap
+      net-pop
+      net-smtp
+    marcel (1.0.4)
+    mini_mime (1.1.5)
+    minitest (5.25.5)
+    net-imap (0.5.9)
+      date
+      net-protocol
+    net-pop (0.1.2)
+      net-protocol
+    net-protocol (0.2.2)
+      timeout
+    net-smtp (0.5.1)
+      net-protocol
+    nio4r (2.7.4)
+    nokogiri (1.18.8-aarch64-linux-gnu)
+      racc (~> 1.4)
+    nokogiri (1.18.8-aarch64-linux-musl)
+      racc (~> 1.4)
+    nokogiri (1.18.8-arm-linux-gnu)
+      racc (~> 1.4)
+    nokogiri (1.18.8-arm-linux-musl)
+      racc (~> 1.4)
+    nokogiri (1.18.8-arm64-darwin)
+      racc (~> 1.4)
+    nokogiri (1.18.8-x86_64-darwin)
+      racc (~> 1.4)
+    nokogiri (1.18.8-x86_64-linux-gnu)
+      racc (~> 1.4)
+    nokogiri (1.18.8-x86_64-linux-musl)
+      racc (~> 1.4)
+    parallel (1.27.0)
+    parser (3.3.8.0)
+      ast (~> 2.4.1)
+      racc
+    pp (0.6.2)
+      prettyprint
+    prettyprint (0.2.0)
+    prism (1.4.0)
+    psych (5.2.6)
+      date
+      stringio
+    racc (1.8.1)
+    rack (3.1.16)
+    rack-session (2.1.1)
+      base64 (>= 0.1.0)
+      rack (>= 3.0.0)
+    rack-test (2.2.0)
+      rack (>= 1.3)
+    rackup (2.2.1)
+      rack (>= 3)
+    rails (7.2.2.1)
+      actioncable (= 7.2.2.1)
+      actionmailbox (= 7.2.2.1)
+      actionmailer (= 7.2.2.1)
+      actionpack (= 7.2.2.1)
+      actiontext (= 7.2.2.1)
+      actionview (= 7.2.2.1)
+      activejob (= 7.2.2.1)
+      activemodel (= 7.2.2.1)
+      activerecord (= 7.2.2.1)
+      activestorage (= 7.2.2.1)
+      activesupport (= 7.2.2.1)
+      bundler (>= 1.15.0)
+      railties (= 7.2.2.1)
+    rails-dom-testing (2.3.0)
+      activesupport (>= 5.0.0)
+      minitest
+      nokogiri (>= 1.6)
+    rails-html-sanitizer (1.6.2)
+      loofah (~> 2.21)
+      nokogiri (>= 1.15.7, != 1.16.7, != 1.16.6, != 1.16.5, != 1.16.4, != 1.16.3, != 1.16.2, != 1.16.1, != 1.16.0.rc1, != 1.16.0)
+    railties (7.2.2.1)
+      actionpack (= 7.2.2.1)
+      activesupport (= 7.2.2.1)
+      irb (~> 1.13)
+      rackup (>= 1.0.0)
+      rake (>= 12.2)
+      thor (~> 1.0, >= 1.2.2)
+      zeitwerk (~> 2.6)
+    rainbow (3.1.1)
+    rake (13.3.0)
+    rdoc (6.14.2)
+      erb
+      psych (>= 4.0.0)
+    regexp_parser (2.10.0)
+    reline (0.6.1)
+      io-console (~> 0.5)
+    rubocop (1.75.8)
+      json (~> 2.3)
+      language_server-protocol (~> 3.17.0.2)
+      lint_roller (~> 1.1.0)
+      parallel (~> 1.10)
+      parser (>= 3.3.0.2)
+      rainbow (>= 2.2.2, < 4.0)
+      regexp_parser (>= 2.9.3, < 3.0)
+      rubocop-ast (>= 1.44.0, < 2.0)
+      ruby-progressbar (~> 1.7)
+      unicode-display_width (>= 2.4.0, < 4.0)
+    rubocop-ast (1.45.1)
+      parser (>= 3.3.7.2)
+      prism (~> 1.4)
+    rubocop-performance (1.25.0)
+      lint_roller (~> 1.1)
+      rubocop (>= 1.75.0, < 2.0)
+      rubocop-ast (>= 1.38.0, < 2.0)
+    ruby-progressbar (1.13.0)
+    securerandom (0.4.1)
+    standard (1.50.0)
+      language_server-protocol (~> 3.17.0.2)
+      lint_roller (~> 1.0)
+      rubocop (~> 1.75.5)
+      standard-custom (~> 1.0.0)
+      standard-performance (~> 1.8)
+    standard-custom (1.0.2)
+      lint_roller (~> 1.0)
+      rubocop (~> 1.50)
+    standard-performance (1.8.0)
+      lint_roller (~> 1.1)
+      rubocop-performance (~> 1.25.0)
+    stringio (3.1.7)
+    thor (1.3.2)
+    timeout (0.4.3)
+    tzinfo (2.0.6)
+      concurrent-ruby (~> 1.0)
+    unicode-display_width (3.1.4)
+      unicode-emoji (~> 4.0, >= 4.0.4)
+    unicode-emoji (4.0.4)
+    useragent (0.16.11)
+    websocket-driver (0.8.0)
+      base64
+      websocket-extensions (>= 0.1.0)
+    websocket-extensions (0.1.5)
+    zeitwerk (2.7.3)
+
+PLATFORMS
+  aarch64-linux-gnu
+  aarch64-linux-musl
+  arm-linux-gnu
+  arm-linux-musl
+  arm64-darwin
+  x86_64-darwin
+  x86_64-linux-gnu
+  x86_64-linux-musl
+
+DEPENDENCIES
+  debug (~> 1.11.0)
+  minitest (~> 5.25, >= 5.25.5)
+  perron!
+  rails (~> 7.2.0)
+  rake (~> 13.3.0)
+  standard (~> 1.50.0)
+
+BUNDLED WITH
+   2.6.8

data/README.md

@@ -0,0 +1,221 @@
+# Perron
+
+A Rails-based static site generator.
+
+**Sponsored By [Rails Designer](https://railsdesigner.com/)**
+
+<a href="https://railsdesigner.com/" target="_blank">
+  <picture>
+    <source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/Rails-Designer/perron/HEAD/.github/logo-dark.svg">
+    <source media="(prefers-color-scheme: light)" srcset="https://raw.githubusercontent.com/Rails-Designer/perron/HEAD/.github/logo-light.svg">
+    <img alt="Rails Designer" src="https://raw.githubusercontent.com/Rails-Designer/perron/HEAD/.github/logo-light.svg" width="240" style="max-width: 100%;">
+  </picture>
+</a>
+
+
+## Getting Started
+
+### Installation
+
+Start by generating the configuration file:
+```bash
+rails generate perron:install
+```
+
+This creates an initializer:
+```ruby
+Perron.configure do |config|
+  config.site_name = "AppRefresher"
+
+  # Override the defaults (meta) title suffix
+  # Default: `— Perron.configuration.site_name`
+  # config.title_suffix = nil
+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.
+
+| **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 |
+
+
+## Creating Content
+
+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`.
+
+The controllers are located in `app/controllers/content/`. To make them available, create a route: `resources :posts, module: :content, only: %w[index show]`.
+
+
+### Collections
+
+```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`
+* Adds 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).
+
+This is automatically added 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:
+
+- CommonMarker
+- Kramdown
+- Redcarpet
+
+```bash
+bundle add {commonmarker,kramdown,redcarpet}
+```
+
+
+## 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::Data` with the basename of the file and iterate over the result.
+```erb
+<% 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.
+
+### 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]
+```
+
+
+## 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. 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"
+end
+```
+
+
+## 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)
+
+### 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`.
+
+
+## License
+
+Perron is released under the [MIT License](https://opensource.org/licenses/MIT).

data/Rakefile

@@ -0,0 +1,9 @@
+# frozen_string_literal: true
+
+require "bundler/gem_tasks"
+require "minitest/test_task"
+require "standard/rake"
+
+Minitest::TestTask.create
+
+task default: %i[test standard]

data/app/helpers/meta_tags_helper.rb

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

data/app/helpers/perron/markdown_helper.rb

@@ -0,0 +1,9 @@
+# frozen_string_literal: true
+
+require "perron/markdown"
+
+module Perron
+  module MarkdownHelper
+    def markdownify(content = nil, &block) = Perron::Markdown.render(content || capture(&block).strip_heredoc)
+  end
+end

data/bin/console

@@ -0,0 +1,10 @@
+#!/usr/bin/env ruby
+
+require "bundler/setup"
+require "perron"
+
+# You can add fixtures and/or initialization code here to make experimenting
+# with your gem easier. You can also use a different console, if you like.
+
+require "irb"
+IRB.start(__FILE__)

data/bin/rails

@@ -0,0 +1,17 @@
+#!/usr/bin/env ruby
+# This command will automatically be run when you run "rails" with Rails gems
+# installed from the root of your application.
+
+ENGINE_ROOT = File.expand_path("..", __dir__)
+ENGINE_PATH = File.expand_path("../lib/perron/engine", __dir__)
+
+# Set up gems listed in the Gemfile.
+ENV["BUNDLE_GEMFILE"] ||= File.expand_path("../Gemfile", __dir__)
+require "bundler/setup" if File.exist?(ENV["BUNDLE_GEMFILE"])
+
+require "rails"
+
+require "action_controller/railtie"
+require "action_view/railtie"
+
+require "rails/engine/commands"

data/bin/release

@@ -0,0 +1,19 @@
+#!/usr/bin/env bash
+
+VERSION=$1
+
+if [ -z "$VERSION" ]; then
+  echo "Error: The version number is required."
+  echo "Usage: $0 <version-number>"
+  exit 1
+fi
+
+printf "module Perron\n  VERSION = \"$VERSION\"\nend\n" > ./lib/perron/version.rb
+bundle
+git add Gemfile.lock lib/perron/version.rb
+git commit -m "Bump version for $VERSION"
+git push
+git tag v$VERSION
+git push --tags
+gem build perron.gemspec
+gem push "perron-$VERSION.gem"

data/bin/setup

@@ -0,0 +1,8 @@
+#!/usr/bin/env bash
+set -euo pipefail
+IFS=$'\n\t'
+set -vx
+
+bundle install
+
+# Do any other automated setup that you need to do here

data/lib/generators/content/content_generator.rb

@@ -0,0 +1,45 @@
+require "rails/generators/base"
+
+class ContentGenerator < Rails::Generators::NamedBase
+  source_root File.expand_path("templates", __dir__)
+
+  argument :actions, type: :array, default: %w[index show], desc: "Specify which actions to generate (index/show)"
+
+  def create_model
+    template "model.rb.tt", File.join("app/models/content", "#{file_name}.rb")
+  end
+
+  def create_controller
+    template "controller.rb.tt", File.join("app/controllers/content", "#{plural_file_name}_controller.rb")
+  end
+
+  def create_views
+    empty_directory view_directory
+
+    actions.each do |action|
+      template "#{action}.html.erb.tt", File.join(view_directory, "#{action}.html.erb")
+    end
+  end
+
+  def create_content_directory = FileUtils.mkdir_p(content_directory)
+
+  def create_pages_root
+    return unless pages_controller?
+
+    template "root.erb.tt", File.join(content_directory, "root.erb")
+  end
+
+  def add_content_route
+    route "resources :#{plural_file_name}, module: :content, only: %w[#{actions.join(" ")}]"
+  end
+
+  private
+
+  def view_directory = Rails.root.join("app", "views", "content", plural_file_name)
+
+  def content_directory = Rails.root.join("app", "content", plural_file_name)
+
+  def plural_class_name = plural_name.camelize
+
+  def pages_controller? = plural_file_name == "pages"
+end

data/lib/generators/content/templates/controller.rb.tt

@@ -0,0 +1,17 @@
+class Content::<%= plural_class_name %>Controller < ApplicationController
+<%- if pages_controller? -%>
+  include Perron::Root
+<%- end -%>
+
+<%- if actions.include?("index") -%>
+  def index
+    @resources = Content::<%= class_name %>.all
+  end
+
+<%- end -%>
+<%- if actions.include?("show") -%>
+  def show
+    @resource = Content::<%= class_name %>.find(params[:id])
+  end
+<%- end -%>
+end

data/lib/generators/content/templates/index.html.erb.tt

@@ -0,0 +1,11 @@
+<h1>
+  <%= plural_class_name %>
+</h1>
+
+<ul>
+  <%% @resources.each do |resource| %>
+    <li>
+      <%%= link_to resource.filename, resource %>
+    </li>
+  <%% end %>
+</ul>

data/lib/generators/content/templates/model.rb.tt

@@ -0,0 +1,2 @@
+class Content::<%= class_name %> < Perron::Resource
+end