Repository: bridgetownrb/bridgetown
Pull request #987: add initializers.rb examples to match legacy yaml examples
Author: login: brainbuz
Created: 2025-03-20T05:08:38Z | Merged: 2025-04-15T16:04:38Z

I've gone through the doc looking for examples in legacy yaml and added equivalent initializers code with multilang. configuration.md had both examples, but they were not equivalent, I updated the ruby example to include all options in the yaml example. 

I also added a note on configuration processing order.


Diff:
diff --git a/bridgetown-website/src/_docs/configuration.md b/bridgetown-website/src/_docs/configuration.md
index 6fc7ec633..ad9d0ab14 100644
--- a/bridgetown-website/src/_docs/configuration.md
+++ b/bridgetown-website/src/_docs/configuration.md
@@ -53,9 +53,22 @@ Bridgetown.configure do |config|
   init :dotenv
 
   config.autoload_paths << "jobs"
-
+  url "https://www.bridgetownrb.com"
   permalink "pretty"
   timezone "America/Los_Angeles"
+  template_engine "serbea"
+
+  collections do
+    docs do
+      output true
+      permalink "/:collection/:path.*"
+      name "Documentation"
+    end
+  end
+
+  if Bridgetown.env.development?
+    unpublished true
+  end
 
   only :server do
     init :mail, password: ENV["SENDGRID_API_KEY"]
@@ -65,6 +78,12 @@ end
 
 The initializer-style config is the most powerful, because you can configure different options for different contexts (static, server, console, rake), as well as interact with environment variables and other system features via full Ruby code. You can also initialize gem-based plugins and configure them in a single pass. And you can write your own initializers which may be called from the main `configure` block.
 
+{%@ Note do %}
+  #### Processing Order
+
+Values from bridgetown.config.yml are processed first, then config/initializers.rb, command line arguments are processed last.
+{% end %}
+
 ## Take a Deep Dive
 
 * [Initializers](/docs/configuration/initializers)
diff --git a/bridgetown-website/src/_docs/configuration/environments.md b/bridgetown-website/src/_docs/configuration/environments.md
index d89650e8f..5aef00e50 100644
--- a/bridgetown-website/src/_docs/configuration/environments.md
+++ b/bridgetown-website/src/_docs/configuration/environments.md
@@ -60,25 +60,24 @@ The default value for `BRIDGETOWN_ENV` is `development`. Thus if you omit
 
 Some elements you might want to hide in development environments include comment forms or analytics. Conversely, you might want to expose an "Edit This Page" button in a development or staging environment but not include it in production environments.
 
-## Environment-specific Configurations
+## Defining Environments
 
-In your `bridgetown.config.yml` config file, as well as the
-`src/_data/site_metadata.yml` metadata file, you can add a block of YAML options
-per environment. For example, given the following metadata:
+The Legacy YAML format defines environments as key/value pairs, config/initializers.rb uses the environment as a condition for applying settings.
 
-```yaml
-# src/_data/site_metadata.yml
+{%@ Documentation::Multilang do %}
+```ruby
+# config/initializers.rb
 
-title: My Website
+if Bridgetown.env.development?
+  unpublished true
+  future true
+elsif Bridgetown.env.staging?
+  unpublished true
+end
 
-development:
-  title: My (DEV) Website
 ```
-
-Your site title would be "My Website" if built with a `production` environment,
-and "My (DEV) Website" if built with a `development` environment. You can specify any
-number of environment blocks that you wish. For example:
-
+===
+{% raw %}
 ```yaml
 # bridgetown.config.yml
 
@@ -89,11 +88,30 @@ development:
 staging:
   unpublished: true
 ```
+{% endraw %}
+{% end %}
 
 The `development` environment will build documents that are marked as unpublished as
-well as having a future date, whereas the `staging` environment will only
+well as having a future date, the `staging` environment will only
 build unpublished. And the `production` environment would exclude both sets.
 
+## Environment Specific Metadata
+
+In your `src/_data/site_metadata.yml`, you can add a block of YAML options
+per environment. For example, given the following metadata:
+
+```yaml
+# src/_data/site_metadata.ymlTITLE
+
+title: My Website
+
+development:
+  title: My (DEV) Website
+```
+
+Your site title would be "My Website" if built with a `production` environment,
+and "My (DEV) Website" if built with a `development` environment. If you define your environments in the Legacy YAML config, you can also set per environment metadata values there. It is recommended to set metadata values in site_metadata.yml and Bridgetown values in initializers.
+
 {%@ Note do %}
   #### Accessing the Environment in Your Ruby Code and Plugins
 
diff --git a/bridgetown-website/src/_docs/content/pagination.md b/bridgetown-website/src/_docs/content/pagination.md
index 4e6c04b98..18996fd43 100644
--- a/bridgetown-website/src/_docs/content/pagination.md
+++ b/bridgetown-website/src/_docs/content/pagination.md
@@ -17,8 +17,8 @@ Bridgetown.configure do
 end
 ```
 ===
-```yml
-# bridgetown.config/yml
+```yaml
+# bridgetown.config.yml
 pagination:
   enabled: true
 ```
@@ -130,3 +130,7 @@ To display pagination links, use the `paginator` object as follows:
 The `paginator` Ruby / Liquid object provides the following properties:
 
 {%@ Documentation::VariablesTable data: site.data, scope: :paginator, description_size: :bigger %}
+
+## Considerations When Using Pagination
+
+On paginated pages, the originating collection is replaced by the paginator. Code in a layout like resource.collection.label will generate undefined method errors on your paginated page. Accessing the collection directly rather than through the paginator will also fail.
diff --git a/bridgetown-website/src/_docs/internationalization.md b/bridgetown-website/src/_docs/internationalization.md
index 73a12845e..723557ff8 100644
--- a/bridgetown-website/src/_docs/internationalization.md
+++ b/bridgetown-website/src/_docs/internationalization.md
@@ -22,17 +22,29 @@ Bridgetown uses the [Ruby I18n](https://github.com/ruby-i18n/i18n) gem to aid in
 
 ## Setup & Translations
 
-First, you'll want to define your locales in `bridgetown.config.yml`. There are three configuration options, which by default are:
+First, you'll want to define your locales in `config/initializers.rb` or `bridgetown.config.yml`. There are three configuration options:
 
-```yml
+* `available_locales`: This is an array of locales you wish to support on your site. They can be simple language codes (`es` for Spanish, `th` for Thai, etc.), or they can also include regional differences known as subtags (`pt-BR` for Brazilian Portuguese, `pt-PT` for Portuguese as spoken in Portugal, etc.). [You can look up various languages and subtags here](https://r12a.github.io/app-subtags/). An example value for English, French, and German would be: `[en, fr, de]`.
+* `default_locale`: This the locale you wish to consider the "default" for your site (aka the locale a visitor would first encounter before specifically choosing a locale). The default is English: `en`.
+* `prefix_default_locale`: As mentioned above, you can either have default locale URLs live within the root of your site, or you can set this to `true` to have the root direct to the default locale's prefix.
+
+{%@ Documentation::Multilang do %}
+```ruby
+Bridgetown.configure do |config|
+  available_locales [:en, :fr, :de]
+  default_locale :en
+  prefix_default_locale false
+end
+```
+===
+{% raw %}
+```yaml
 available_locales: [en]
 default_locale: en
 prefix_default_locale: false
 ```
-
-* `available_locales`: This is an array of locales you wish to support on your site. They can be simple language codes (`es` for Spanish, `th` for Thai, etc.), or they can also include regional differences known as subtags (`pt-BR` for Brazilian Portuguese, `pt-PT` for Portuguese as spoken in Portugal, etc.). [You can look up various languages and subtags here](https://r12a.github.io/app-subtags/). An example value for English, French, and German would be: `[en, fr, de]`.
-* `default_locale`: This the locale you wish to consider the "default" for your site (aka the locale a visitor would first encounter before specifically choosing a locale). The default is English: `en`.
-* `prefix_default_locale`: As mentioned above, you can either have default locale URLs live within the root of your site, or you can set this to `true` to have the root direct to the default locale's prefix.
+{% endraw %}
+{% end %}
 
 Once you've completed your intial configuration, create a `src/_locales` folder and add files in YAML, JSON, or Ruby hash format for your locale translations. The first key of the data structure should be the locale, with various hierarchies of subkeys as you deem fit. Here's an example of a `en.yml` file:
 
diff --git a/bridgetown-website/src/_docs/plugins/external-apis.md b/bridgetown-website/src/_docs/plugins/external-apis.md
index 438c5266e..e411b1c0d 100644
--- a/bridgetown-website/src/_docs/plugins/external-apis.md
+++ b/bridgetown-website/src/_docs/plugins/external-apis.md
@@ -144,7 +144,7 @@ add_resource :authors, "rlstevenson.md" do
 end
 ```
 
-You don't even need to use a collection that's previously been configured in `bridgetown.config.yml`. You can make up new collections and use existing layouts to place your content within the appropriate templates, assuming the expected front matter is compatible.
+You don't even need to use a collection that's previously been configured in `initializers.rb` or `bridgetown.config.yml`. You can make up new collections and use existing layouts to place your content within the appropriate templates, assuming the expected front matter is compatible.
 
 ```ruby
 add_resource :blogish, "fake-blog-post.html" do
diff --git a/bridgetown-website/src/_docs/prototype-pages.md b/bridgetown-website/src/_docs/prototype-pages.md
index 957fb7ec6..b6052f8e2 100644
--- a/bridgetown-website/src/_docs/prototype-pages.md
+++ b/bridgetown-website/src/_docs/prototype-pages.md
@@ -10,7 +10,7 @@ lets you create automatically generated, paginated archives of your content filt
 the search terms you provide. For instance you could set it up so every category has its
 own page, every tag has its own page, or virtually any other search term.
 
-Note that in order to use [pagination](/docs/content/pagination/), you'll need to enable it your site's `bridgetown.config.yml`.
+Note that in order to use [pagination](/docs/content/pagination/), you'll need to enable it in your site's `initializers.rb` or `bridgetown.config.yml`.
 
 {{ toc }}
 
diff --git a/bridgetown-website/src/_docs/template-engines.md b/bridgetown-website/src/_docs/template-engines.md
index 08d9e1651..3720973b6 100644
--- a/bridgetown-website/src/_docs/template-engines.md
+++ b/bridgetown-website/src/_docs/template-engines.md
@@ -50,7 +50,7 @@ It's worth noting that by combining Markdown, ERB/Serbea, components, and fronte
 
 ## Why Did Bridgetown Switch from Liquid?
 
-Prior to Bridgetown 2.0, Liquid was the default template type. Liquid feels more akin to template engines like Mustache, Jinja, Nunjucks, Twig, and so forth—and it was the only default option in Bridgetown's progenitor, Jekyll.
+Prior to Bridgetown 2.0, Liquid was the default template type. Liquid feels more akin to template engines like Mustache, Jinja, Nunjucks, Twig, and so forth—and it was the only option in Bridgetown's progenitor, Jekyll.
 
 But most Bridgetown developers will need more power (especially when writing [components](/docs/components)) or may already be familiar with Ruby and engines such as ERB. And some developers are looking to switch from [Middleman](https://middlemanapp.com) which uses ERB by default. Thus it makes sense to standardize around ERB.
 


Reviews:
user: login: jaredcwhite
body: Overall this is looking stellar! I just had a couple of notes to make, should be quick to change and then I'll go ahead and merge. TIA
state: CHANGES_REQUESTED
author_association: MEMBER
submitted_at: 2025-04-14T18:38:28Z

Review comments:
diff_hunk: @@ -65,6 +78,13 @@ end
 
 The initializer-style config is the most powerful, because you can configure different options for different contexts (static, server, console, rake), as well as interact with environment variables and other system features via full Ruby code. You can also initialize gem-based plugins and configure them in a single pass. And you can write your own initializers which may be called from the main `configure` block.
 
+{%@ Note do %}
+  #### Processing Order
+
+Values from bridgetown.config.yml are processed first, then config/initializers.rb, command line arguments are processed last. If you defined environments in bridgetown.config.yml, but also had a condition in initializers.rb, adding `<pre><%= site.config.to_yaml %></pre>` in a page would show the yaml defined environment, but the active parameters would match those set in initializers.
path: bridgetown-website/src/_docs/configuration.md
user: login: jaredcwhite
body: This isn't strictly true, `site.config` will reflect the most recently-defined config value such as initializers config, not reflect what might have been in the original `bridgetown.config.yml` file. Otherwise, I love this section!
created_at: 2025-04-14T18:34:47Z
author_association: MEMBER
diff_hunk: @@ -60,25 +60,24 @@ The default value for `BRIDGETOWN_ENV` is `development`. Thus if you omit
 
 Some elements you might want to hide in development environments include comment forms or analytics. Conversely, you might want to expose an "Edit This Page" button in a development or staging environment but not include it in production environments.
 
-## Environment-specific Configurations
+## Defining Environments
 
-In your `bridgetown.config.yml` config file, as well as the
-`src/_data/site_metadata.yml` metadata file, you can add a block of YAML options
-per environment. For example, given the following metadata:
+The Legacy YAML format defines environments as key/value pairs, config/initilizers.rb uses the environment as a condition for applying settings.
path: bridgetown-website/src/_docs/configuration/environments.md
user: login: jaredcwhite
body: spelling issue with "initilizers"
created_at: 2025-04-14T18:35:37Z
author_association: MEMBER
diff_hunk: @@ -40,7 +40,7 @@ Then you can use the `paginator.resources` logic to iterate through the collecti
 
 {%@ Documentation::Multilang do %}
 ```erb
-<% paginator.each do |post| %>
+<% paginator.resources.each do |post| %>
path: bridgetown-website/src/_docs/content/pagination.md
user: login: jaredcwhite
body: Let's revert this change, I'm convinced we don't need to keep that `resources` method call and if we need to fix a bug to get it working we will (provided I can reproduce).
created_at: 2025-04-14T18:36:55Z
author_association: MEMBER

PR comments:
user: login: jaredcwhite
created_at: 2025-03-20T18:22:50Z
body: @brainbuz Fantastic! I'll review soon when I'm able.
author_association: MEMBER
user: login: brainbuz
created_at: 2025-03-24T16:10:35Z
body: The request in #883 appears to be addressed in the current pagination documentation, this PR shows both ruby and legacy yaml config for enabling pagination. However, I'm finding that following the documentation as written, pagination only works with Liquid templates (not working in ERB) @jaredcwhite can you take a look? [ruby 2.4.2 bridgetown 2B4 & main/HEAD]
author_association: CONTRIBUTOR
user: login: brainbuz
created_at: 2025-03-25T17:33:41Z
body: Jared I picked this up again and I think I figured out why it's not working. I'll update this PR with any doc fixes later.
author_association: CONTRIBUTOR
user: login: brainbuz
created_at: 2025-03-26T21:30:25Z
body: I've experienced the same issue as 'Pages which paginate are excluded from collections.pages' #807. The original requester closed the issue as he decided not to use pagination. In your comments you didn't see an easy fix. What is the best workaround? Could something be done with a partial or component? In my case navigation is using the list of resources in the pages collection to generate a menu. I'd like to request that you reopen 807 until its fixed or a workaround is in the documentation. 
author_association: CONTRIBUTOR
user: login: jaredcwhite
created_at: 2025-04-02T03:57:17Z
body: Hmm, I'm curious what the error was that prompted your commit [b859405](https://github.com/bridgetownrb/bridgetown/pull/987/commits/b8594051b7b75baa832620b653a6651f872b278f) — the `paginator.each` example should work in ERB, and if not there's a bug somewhere I think.
author_association: MEMBER
user: login: jaredcwhite
created_at: 2025-04-02T04:01:33Z
body: Oh hey, it just occurred to me that there's now a `original_resource` method on the paginated page, so maybe the docs could mention that rather than just say access to resource info is lost.
author_association: MEMBER
user: login: brainbuz
created_at: 2025-04-02T04:26:22Z
body: When I tried to paginate with <% paginator.each do |post| %> it did not work,  <% paginator.resources.each do |post| %> did work. original_resource should definitely be in the pagination documentation, as should all of the quirks. 

After creating the single page archives by year alternative, I found I didn't need to use pagination. Most end users don't pay much attention to the urls, so whether a javascript is flipping the page in place or the pages have nice rest urls isn't going to get notice other than by developers. 
author_association: CONTRIBUTOR
user: login: brainbuz
created_at: 2025-04-02T05:27:54Z
body: If you send me some notes / point at source code or test files with comments etc, I'll be happy to do the writing.
author_association: CONTRIBUTOR
user: login: jaredcwhite
created_at: 2025-04-15T16:04:33Z
body: 🎉 
author_association: MEMBER