Perron Static Site Generator

Perron allows you to consume structured data from .yml, .json, or .csv files and make them available within your Rails views. This is ideal for populating repeated data structures like team members, features, or site content.

By default, Perron looks for data files in app/content/data/. The class name used to access the data in your application matches the file's basename (e.g., features.yml is accessed via Content::Data::Features).

<% Content::Data::Features.all.each do |feature| %>
  <h4><%= feature.name %></h4>
  <p><%= feature.description %></p>
<% end %>

Data resources must be formatted as an array of objects. If you intend to use the .find method or define associations, every record must include an id field.

# app/content/data/authors.yml
- id: rails-designer
  name: Rails Designer
  bio: Creator of Perron

- id: cam
  name: Cam
  bio: Contributing author

You can customize Perron's behavior by using the Perron.configure method. This method yields the current configuration object, allowing you to set various options such as output paths, build modes, and live reload settings.

Example usage:

Perron.configure do |config| 
  config.output = "custom_output"
  config.mode = :standalone
  config.site_name = "My Awesome Site"
end

You can render entire data collections directly using Rails-style partial rendering.

When you call <%= render Content::Data::Features.all %>, Perron expects a partial located at app/views/content/features/_feature.html.erb. The partial will be rendered once for each item, and the individual record is passed as a local variable named after the singular form of the collection (e.g., feature).

<%# In your view %>
<%= render Content::Data::Features.all %>

<%# app/views/content/features/_feature.html.erb %>
<div class="feature">
  <h4><%= feature.name %></h4>
  <p><%= feature.description %></p>
</div>

Perron automatically searches app/content/data/ for files with .yml, .json, or .csv extensions.

If you need to access a data resource located at a custom path within /app/content/data/, you can instantiate a new data object using Content::Data.new("path/to/data-resource").

The Perron::Metatags#title_tag method uses global configuration to format the <title> element.

If Perron.configuration.metadata.title_suffix is set, it will be appended to the resource title using the Perron.configuration.metadata.title_separator. The suffix is only appended if the resource title is not identical to the suffix itself.

The inline method allows you to render the resource's content within a specific layout, returning a hash containing the HTML and the layout name. This is useful for generating page fragments or full views.

resource = Perron::Resource.new("page.md")
render_data = resource.inline(layout: "blog_post")
# => { html: "<html>...</html>", layout: "blog_post" }

Once initialized, you can access the resource's data using several methods:

• content: Returns the processed content. If the file is an .erb file or if metadata specifies erb: true, it will process ERB templates.
• raw (or raw_content): Returns the unprocessed string content of the file.
• metadata: Returns a hash of data parsed from the file's frontmatter.
• slug (or path, or to_param): Returns the URL-friendly slug generated from the resource.

resource = Perron::Resource.new("page.md")

resource.content    # Processed content (with ERB if applicable)
resource.raw        # The raw file string
resource.metadata   # Hash of frontmatter data
resource.slug       # The URL slug