Introduce markdownlint for guides

This is a follow up to rails#47186, this time for all markdown content.

[markdownlint](https://github.com/markdownlint/markdownlint) is an excellent tool, and I've found it very useful for finding issues in the guides.

Many of the rules are common style issues I'm correcting on PRs, so it will be nice to have that automated.

We should also be able to use the same config with our editors, so that errors show up in real-time 🙏 and will update the contributing docs once this gets merged with how to debug and use mdl appropriately.

.github/workflows/mdl.yml

@@ -0,0 +1,24 @@
+name: Markdown Lint [Guides]
+
+on: [pull_request]
+
+permissions:
+  contents: read
+
+jobs:
+  mdl:
+    runs-on: ubuntu-latest
+    env:
+      BUNDLE_ONLY: mdl
+
+    steps:
+    - uses: actions/checkout@v3
+
+    - name: Set up Ruby 3.2
+      uses: ruby/setup-ruby@v1
+      with:
+        ruby-version: 3.2
+        bundler-cache: true
+
+    - name: Run mdl
+      run: bundle exec rake -f guides/Rakefile guides:lint

.mdlrc

@@ -0,0 +1 @@
+style "#{File.dirname(__FILE__)}/.mdlrc.rb"

.mdlrc.rb

@@ -0,0 +1,23 @@
+# frozen_string_literal: true
+
+all
+
+exclude_rule "MD003"
+exclude_rule "MD004"
+exclude_rule "MD005"
+exclude_rule "MD006"
+exclude_rule "MD007"
+exclude_rule "MD012"
+exclude_rule "MD014"
+exclude_rule "MD024"
+exclude_rule "MD026"
+exclude_rule "MD033"
+exclude_rule "MD034"
+exclude_rule "MD036"
+exclude_rule "MD040"
+exclude_rule "MD041"
+
+rule "MD013", line_length: 2000, ignore_code_blocks: true
+# rule "MD024", allow_different_nesting: true # This did not work as intended, see action_cable_overview.md
+rule "MD029", style: :ordered
+# rule "MD046", style: :consistent # default (:fenced)

Gemfile

@@ -49,6 +49,11 @@ group :rubocop do
   gem "rubocop-md", require: false
 end
 
+group :mdl do
+  gem "mdl", require: false
+  gem "rake", ">= 13", require: false
+end
+
 group :doc do
   gem "sdoc", ">= 2.6.0"
   gem "rdoc", "~> 6.5"

Gemfile.lock

@@ -160,6 +160,8 @@ GEM
       regexp_parser (>= 1.5, < 3.0)
       xpath (~> 3.2)
     cgi (0.3.6)
+    chef-utils (18.1.29)
+      concurrent-ruby
     concurrent-ruby (1.1.10)
     connection_pool (2.3.0)
     crack (0.4.5)
@@ -275,6 +277,10 @@ GEM
       railties (>= 6.0.0)
     json (2.6.3)
     jwt (2.6.0)
+    kramdown (2.4.0)
+      rexml
+    kramdown-parser-gfm (1.1.0)
+      kramdown (~> 2.0)
     libxml-ruby (4.0.0)
     listen (3.8.0)
       rb-fsevent (~> 0.10, >= 0.10.3)
@@ -289,6 +295,12 @@ GEM
       net-smtp
     marcel (1.0.2)
     matrix (0.4.2)
+    mdl (0.12.0)
+      kramdown (~> 2.3)
+      kramdown-parser-gfm (~> 1.1)
+      mixlib-cli (~> 2.1, >= 2.1.1)
+      mixlib-config (>= 2.2.1, < 4)
+      mixlib-shellout
     memoist (0.16.2)
     mini_magick (4.12.0)
     mini_mime (1.1.2)
@@ -303,6 +315,11 @@ GEM
       minitest (>= 5.0)
     minitest-server (1.0.7)
       minitest (~> 5.16)
+    mixlib-cli (2.1.8)
+    mixlib-config (3.0.27)
+      tomlrb
+    mixlib-shellout (3.2.7)
+      chef-utils
     mono_logger (1.1.1)
     msgpack (1.6.0)
     multi_json (1.15.0)
@@ -327,7 +344,7 @@ GEM
       racc (~> 1.4)
     os (1.1.4)
     parallel (1.22.1)
-    parser (3.2.0.0)
+    parser (3.2.1.1)
       ast (~> 2.4.1)
     path_expander (1.1.1)
     pg (1.4.5)
@@ -407,7 +424,7 @@ GEM
       rubocop-ast (>= 1.26.0, < 2.0)
       ruby-progressbar (~> 1.7)
       unicode-display_width (>= 2.4.0, < 3.0)
-    rubocop-ast (1.27.0)
+    rubocop-ast (1.28.0)
       parser (>= 3.2.1.0)
     rubocop-md (1.2.0)
       rubocop (>= 1.0)
@@ -489,6 +506,7 @@ GEM
     thor (1.2.1)
     tilt (2.0.11)
     timeout (0.3.2)
+    tomlrb (2.0.3)
     trailblazer-option (0.1.2)
     turbo-rails (1.3.2)
       actionpack (>= 6.0.0)
@@ -558,6 +576,7 @@ DEPENDENCIES
   json (>= 2.0.0)
   libxml-ruby
   listen (~> 3.3)
+  mdl
   minitest (>= 5.15.0)
   minitest-bisect
   minitest-ci

guides/Rakefile

@@ -24,6 +24,14 @@ namespace :guides do
     end
   end
 
+  desc "Lint guides, using `mdl`"
+  task :lint do
+    require "mdl"
+    all = Dir.glob("#{__dir__}/source/*.md")
+    files = all - Dir.glob("#{__dir__}/**/*_release_notes.md") # Ignore release notes
+    MarkdownLint.run files
+  end
+
   # Validate guides -------------------------------------------------------------------------
   desc 'Validate guides, use ONLY=foo to process just "foo.html"'
   task :validate do

guides/source/action_cable_overview.md

@@ -651,28 +651,28 @@ consumer.subscriptions.create("AppearanceChannel", {
 #### Client-Server Interaction
 
 1. **Client** connects to the **Server** via `createConsumer()`. (`consumer.js`). The
-**Server** identifies this connection by `current_user`.
+  **Server** identifies this connection by `current_user`.
 
 2. **Client** subscribes to the appearance channel via
-`consumer.subscriptions.create({ channel: "AppearanceChannel" })`. (`appearance_channel.js`)
+  `consumer.subscriptions.create({ channel: "AppearanceChannel" })`. (`appearance_channel.js`)
 
 3. **Server** recognizes a new subscription has been initiated for the
-appearance channel and runs its `subscribed` callback, calling the `appear`
+  appearance channel and runs its `subscribed` callback, calling the `appear`
-method on `current_user`. (`appearance_channel.rb`)
+  method on `current_user`. (`appearance_channel.rb`)
 
 4. **Client** recognizes that a subscription has been established and calls
-`connected` (`appearance_channel.js`), which in turn calls `install` and `appear`.
+  `connected` (`appearance_channel.js`), which in turn calls `install` and `appear`.
-`appear` calls `AppearanceChannel#appear(data)` on the server, and supplies a
+  `appear` calls `AppearanceChannel#appear(data)` on the server, and supplies a
-data hash of `{ appearing_on: this.appearingOn }`. This is
+  data hash of `{ appearing_on: this.appearingOn }`. This is
-possible because the server-side channel instance automatically exposes all
+  possible because the server-side channel instance automatically exposes all
-public methods declared on the class (minus the callbacks), so that these can be
+  public methods declared on the class (minus the callbacks), so that these can be
-reached as remote procedure calls via a subscription's `perform` method.
+  reached as remote procedure calls via a subscription's `perform` method.
 
 5. **Server** receives the request for the `appear` action on the appearance
-channel for the connection identified by `current_user`
+  channel for the connection identified by `current_user`
-(`appearance_channel.rb`). **Server** retrieves the data with the
+  (`appearance_channel.rb`). **Server** retrieves the data with the
-`:appearing_on` key from the data hash and sets it as the value for the `:on`
+  `:appearing_on` key from the data hash and sets it as the value for the `:on`
-key being passed to `current_user.appear`.
+  key being passed to `current_user.appear`.
 
 ### Example 2: Receiving New Web Notifications
 

guides/source/action_mailer_basics.md

@@ -116,10 +116,10 @@ a full list of all available options, please have a look further down at the
 Complete List of Action Mailer user-settable attributes section.
 
 * The [`default`][] method sets default values for all emails sent from
-this mailer. In this case, we use it to set the `:from` header value for all
+  this mailer. In this case, we use it to set the `:from` header value for all
-messages in this class. This can be overridden on a per-email basis.
+  messages in this class. This can be overridden on a per-email basis.
 * The [`mail`][] method creates the actual email message. We use it to specify
-the values of headers like `:to` and `:subject` per email.
+  the values of headers like `:to` and `:subject` per email.
 
 [`default`]: https://api.rubyonrails.org/classes/ActionMailer/Base.html#method-c-default
 [`mail`]: https://api.rubyonrails.org/classes/ActionMailer/Base.html#method-i-mail

guides/source/active_record_basics.md

@@ -88,8 +88,7 @@ singularizing) both regular and irregular words. When using class names composed
 of two or more words, the model class name should follow the Ruby conventions,
 using the CamelCase form, while the table name must use the snake_case form. Examples:
 
-* Model Class - Singular with the first letter of each word capitalized (e.g.,
+* Model Class - Singular with the first letter of each word capitalized (e.g., `BookClub`).
-`BookClub`).
 * Database Table - Plural with underscores separating words (e.g., `book_clubs`).
 
 | Model / Class    | Table / Schema |

guides/source/active_record_encryption.md

@@ -265,6 +265,7 @@ When generating the filter parameter, it will use the model name as a prefix. E.
 ```ruby
 config.active_record.encryption.add_to_filter_parameters = false
 ```
+
 In case you want exclude specific columns from this automatic filtering, add them to `config.active_record.encryption.excluded_from_filter_parameters`.
 
 ### Encoding
@@ -534,6 +535,7 @@ ActiveRecord::Encryption.without_encryption do
    ...
 end
 ```
+
 This means that reading encrypted text will return the ciphertext, and saved content will be stored unencrypted.
 
 ##### Protect Encrypted Data
@@ -545,4 +547,5 @@ ActiveRecord::Encryption.protecting_encrypted_data do
    ...
 end
 ```
+
 This can be handy if you want to protect encrypted data while still running arbitrary code against it (e.g. in a Rails console).

guides/source/active_record_migrations.md

@@ -517,14 +517,14 @@ Column modifiers can be applied when creating or changing a column:
 * `comment`      Adds a comment for the column.
 * `collation`    Specifies the collation for a `string` or `text` column.
 * `default`      Allows to set a default value on the column. Note that if you
-are using a dynamic value (such as a date), the default will only be calculated
+  are using a dynamic value (such as a date), the default will only be calculated
-the first time (i.e. on the date the migration is applied). Use `nil` for `NULL`.
+  the first time (i.e. on the date the migration is applied). Use `nil` for `NULL`.
 * `limit`        Sets the maximum number of characters for a `string` column
-and the maximum number of bytes for `text/binary/integer` columns.
+  and the maximum number of bytes for `text/binary/integer` columns.
 * `null`         Allows or disallows `NULL` values in the column.
 * `precision`    Specifies the precision for `decimal/numeric/datetime/time` columns.
 * `scale`        Specifies the scale for the `decimal` and `numeric` columns,
-representing the number of digits after the decimal point.
+  representing the number of digits after the decimal point.
 
 NOTE: For `add_column` or `change_column` there is no option for adding indexes.
 They need to be added separately using `add_index`.

guides/source/active_record_multiple_databases.md

@@ -23,10 +23,8 @@ At this time the following features are supported:
 
 * Multiple writer databases and a replica for each
 * Automatic connection switching for the model you're working with
-* Automatic swapping between the writer and replica depending on the HTTP verb
+* Automatic swapping between the writer and replica depending on the HTTP verb and recent writes
-and recent writes
+* Rails tasks for creating, dropping, migrating, and interacting with the multiple databases
-* Rails tasks for creating, dropping, migrating, and interacting with the multiple
-databases
 
 The following features are not (yet) supported:
 

guides/source/active_storage_overview.md

@@ -183,6 +183,7 @@ amazon:
     server_side_encryption: "" # 'aws:kms' or 'AES256'
     cache_control: "private, max-age=<%= 1.day.to_i %>"
 ```
+
 TIP: Set sensible client HTTP timeouts and retry limits for your application. In certain failure scenarios, the default AWS client configuration may cause connections to be held for up to several minutes and lead to request queuing.
 
 Add the [`aws-sdk-s3`](https://github.com/aws/aws-sdk-ruby) gem to your `Gemfile`:

guides/source/api_app.md

@@ -548,7 +548,8 @@ Some common modules you might want to add:
       self.cache_store = :mem_cache_store
     end
     ```
-  Rails does *not* pass this configuration automatically.
+
+    Rails does *not* pass this configuration automatically.
 
 The best place to add a module is in your `ApplicationController`, but you can
 also add modules to individual controllers.

guides/source/asset_pipeline.md

@@ -113,26 +113,17 @@ with a built-in helper. In the source the generated code looked like this:
 
 The query string strategy has several disadvantages:
 
-1. **Not all caches will reliably cache content where the filename only differs by
+1. **Not all caches will reliably cache content where the filename only differs by query parameters**
-query parameters**
 
-    [Steve Souders recommends](https://www.stevesouders.com/blog/2008/08/23/revving-filenames-dont-use-querystring/),
+    [Steve Souders recommends][], "...avoiding a querystring for cacheable resources". He found that in this case 5-20% of requests will not be cached. Query strings in particular do not work at all with some CDNs for cache invalidation.
-"...avoiding a querystring for cacheable resources". He found that in this
-case 5-20% of requests will not be cached. Query strings in particular do not
-work at all with some CDNs for cache invalidation.
 
 2. **The file name can change between nodes in multi-server environments.**
 
-    The default query string in Rails 2.x is based on the modification time of
+    The default query string in Rails 2.x is based on the modification time of the files. When assets are deployed to a cluster, there is no guarantee that the timestamps will be the same, resulting in different values being used depending on which server handles the request.
-the files. When assets are deployed to a cluster, there is no guarantee that the
-timestamps will be the same, resulting in different values being used depending
-on which server handles the request.
 
 3. **Too much cache invalidation**
 
-    When static assets are deployed with each new release of code, the mtime
+    When static assets are deployed with each new release of code, the mtime (time of last modification) of _all_ these files changes, forcing all remote clients to fetch them again, even when the content of those assets has not changed.
-(time of last modification) of _all_ these files changes, forcing all remote
-clients to fetch them again, even when the content of those assets has not changed.
 
 Fingerprinting fixes these problems by avoiding query strings, and by ensuring
 that filenames are consistent based on their content.
@@ -147,7 +138,7 @@ More reading:
 * [Revving Filenames: don't use querystring](http://www.stevesouders.com/blog/2008/08/23/revving-filenames-dont-use-querystring/)
 
 [`config.assets.digest`]: configuring.html#config-assets-digest
-
+[Steve Souders recommends]: https://www.stevesouders.com/blog/2008/08/23/revving-filenames-dont-use-querystring/
 
 How to Use the Asset Pipeline
 -----------------------------
@@ -207,15 +198,15 @@ Pipeline assets can be placed inside an application in one of three locations:
 `app/assets`, `lib/assets` or `vendor/assets`.
 
 * `app/assets` is for assets that are owned by the application, such as custom
-images, JavaScript files, or stylesheets.
+  images, JavaScript files, or stylesheets.
 
 * `lib/assets` is for your own libraries' code that doesn't really fit into the
-scope of the application or those libraries which are shared across applications.
+  scope of the application or those libraries which are shared across applications.
 
 * `vendor/assets` is for assets that are owned by outside entities, such as
-code for JavaScript plugins and CSS frameworks. Keep in mind that third party
+  code for JavaScript plugins and CSS frameworks. Keep in mind that third party
-code with references to other files also processed by the asset Pipeline (images,
+  code with references to other files also processed by the asset Pipeline (images,
-stylesheets, etc.), will need to be rewritten to use helpers like `asset_path`.
+  stylesheets, etc.), will need to be rewritten to use helpers like `asset_path`.
 
 #### Search Paths
 
@@ -760,9 +751,9 @@ $ RAILS_ENV=production rails assets:precompile
 
 Note the following caveats:
 
-*   If precompiled assets are available, they will be served — even if they no
+* If precompiled assets are available, they will be served — even if they no
-    longer match the original (uncompiled) assets, _even on the development
+  longer match the original (uncompiled) assets, _even on the development
-    server._
+  server._
 
     To ensure that the development server always compiles assets on-the-fly (and
     thus always reflects the most recent state of the code), the development
@@ -777,6 +768,7 @@ Note the following caveats:
     ```ruby
     config.assets.prefix = "/dev-assets"
     ```
+
 * The asset precompile task in your deployment tool (_e.g.,_ Capistrano) should
   be disabled.
 * Any necessary compressors or minifiers must be available on your development
@@ -1141,6 +1133,7 @@ and any other environments you define with production behavior (not
 `application.rb`).
 
 TIP: For further details have a look at the docs of your production web server:
+
 - [Apache](https://tn123.org/mod_xsendfile/)
 - [NGINX](https://www.nginx.com/resources/wiki/start/topics/examples/xsendfile/)
 

guides/source/association_basics.md

@@ -1131,14 +1131,14 @@ towards the counter. To fix a stale counter cache, use [`reset_counters`][].
 If you set the `:dependent` option to:
 
 * `:destroy`, when the object is destroyed, `destroy` will be called on its
-associated objects.
+  associated objects.
 * `:delete`, when the object is destroyed, all its associated objects will be
-deleted directly from the database without calling their `destroy` method.
+  deleted directly from the database without calling their `destroy` method.
 * `:destroy_async`: when the object is destroyed, an `ActiveRecord::DestroyAssociationAsyncJob`
-job is enqueued which will call destroy on its associated objects. Active Job must be set up
+  job is enqueued which will call destroy on its associated objects. Active Job must be set up
-for this to work. Do not use this option if the association is backed by foreign key
+  for this to work. Do not use this option if the association is backed by foreign key
-constraints in your database. The foreign key constraint actions will occur inside the same
+  constraints in your database. The foreign key constraint actions will occur inside the same
-transaction that deletes its owner.
+  transaction that deletes its owner.
 
 WARNING: You should not specify this option on a `belongs_to` association that is connected with a `has_many` association on the other class. Doing so can lead to orphaned records in your database.
 
@@ -2626,6 +2626,7 @@ def check_credit_limit(book)
   throw(:abort) if limit_reached?
 end
 ```
+
 NOTE: These callbacks are called only when the associated objects are added or removed through the association collection:
 
 ```ruby

guides/source/command_line.md

@@ -486,6 +486,7 @@ $ bin/rails generate model Oops
       create      test/models/oops_test.rb
       create      test/fixtures/oops.yml
 ```
+
 ```bash
 $ bin/rails destroy model Oops
       invoke  active_record

guides/source/configuring.md

@@ -1458,7 +1458,7 @@ whether a foreign key's name should be dumped to db/schema.rb or not. By
 default, foreign key names starting with `fk_rails_` are not exported to the
 database schema dump. Defaults to `/^fk_rails_[0-9a-f]{10}$/`.
 
- #### `config.active_record.encryption.hash_digest_class`
+#### `config.active_record.encryption.hash_digest_class`
 
  Sets the digest algorithm used by Active Record Encryption.
 

guides/source/contributing_to_ruby_on_rails.md

@@ -437,6 +437,7 @@ For MySQL and PostgreSQL, it is sufficient to run:
 $ cd activerecord
 $ bundle exec rake db:mysql:build
 ```
+
 Or:
 
 ```bash

guides/source/debugging_rails_applications.md

@@ -827,9 +827,9 @@ do that with `local_variables`.
 ### Settings
 
 * `config.web_console.allowed_ips`: Authorized list of IPv4 or IPv6
-addresses and networks (defaults: `127.0.0.1/8, ::1`).
+  addresses and networks (defaults: `127.0.0.1/8, ::1`).
 * `config.web_console.whiny_requests`: Log a message when a console rendering
-is prevented (defaults: `true`).
+  is prevented (defaults: `true`).
 
 Since `web-console` evaluates plain Ruby code remotely on the server, don't try
 to use it in production.
@@ -869,18 +869,18 @@ There are some Rails plugins to help you to find errors and debug your
 application. Here is a list of useful plugins for debugging:
 
 * [Query Trace](https://github.com/ruckus/active-record-query-trace/tree/master) Adds query
-origin tracing to your logs.
+  origin tracing to your logs.
 * [Exception Notifier](https://github.com/smartinez87/exception_notification/tree/master)
-Provides a mailer object and a default set of templates for sending email
+  Provides a mailer object and a default set of templates for sending email
-notifications when errors occur in a Rails application.
+  notifications when errors occur in a Rails application.
 * [Better Errors](https://github.com/charliesome/better_errors) Replaces the
-standard Rails error page with a new one containing more contextual information,
+  standard Rails error page with a new one containing more contextual information,
-like source code and variable inspection.
+  like source code and variable inspection.
 * [RailsPanel](https://github.com/dejan/rails_panel) Chrome extension for Rails
-development that will end your tailing of development.log. Have all information
+  development that will end your tailing of development.log. Have all information
-about your Rails app requests in the browser — in the Developer Tools panel.
+  about your Rails app requests in the browser — in the Developer Tools panel.
-Provides insight to db/rendering/total times, parameter list, rendered views and
+  Provides insight to db/rendering/total times, parameter list, rendered views and
-more.
+  more.
 * [Pry](https://github.com/pry/pry) An IRB alternative and runtime developer console.
 
 References

guides/source/error_reporting.md

@@ -73,6 +73,7 @@ NOTE: The Rails error-reporter will always call registered subscribers, regardle
 There are three ways you can use the error reporter:
 
 #### Reporting and Swallowing Errors
+
 [`Rails.error.handle`](https://api.rubyonrails.org/classes/ActiveSupport/ErrorReporter.html#method-i-handle) will report any error raised within the block. It will then **swallow** the error, and the rest of your code outside the block will continue as normal.
 
 ```ruby
@@ -92,6 +93,7 @@ end
 ```
 
 #### Reporting and Re-raising Errors
+
 [`Rails.error.record`](https://api.rubyonrails.org/classes/ActiveSupport/ErrorReporter.html#method-i-record) will report errors to all registered subscribers and then re-raise the error, meaning that the rest of your code won't execute.
 
 ```ruby
@@ -104,6 +106,7 @@ end
 If no error is raised in the block, `Rails.error.record` will return the result of the block.
 
 #### Manually Reporting Errors
+
 You can also manually report errors by calling [`Rails.error.report`](https://api.rubyonrails.org/classes/ActiveSupport/ErrorReporter.html#method-i-report):
 
 ```ruby

guides/source/form_helpers.md

@@ -366,6 +366,7 @@ Rails works around this issue by emulating other methods over POST through a com
   <button type="submit" name="button">Update</button>
 </form>
 ```
+
 [formmethod]: https://developer.mozilla.org/en-US/docs/Web/HTML/Element/button#attr-formmethod
 [button-name]: https://developer.mozilla.org/en-US/docs/Web/HTML/Element/button#attr-name
 [button-value]: https://developer.mozilla.org/en-US/docs/Web/HTML/Element/button#attr-value

guides/source/upgrading_ruby_on_rails.md

@@ -543,6 +543,7 @@ You will then need to change existing image transformation code to the
 `image_processing` macros, and replace ImageMagick's options with libvips' options.
 
 #### Replace resize with resize_to_limit
+
 ```diff
 - variant(resize: "100x")
 + variant(resize_to_limit: [100, nil])
@@ -551,6 +552,7 @@ You will then need to change existing image transformation code to the
 If you don't do this, when you switch to vips you will see this error: `no implicit conversion to float from string`.
 
 #### Use an array when cropping
+
 ```diff
 - variant(crop: "1920x1080+0+0")
 + variant(crop: [0, 0, 1920, 1080])
@@ -568,6 +570,7 @@ Vips is more strict than ImageMagick when it comes to cropping:
 If you don't do this when migrating to vips, you will see the following error: `extract_area: bad extract area`
 
 #### Adjust the background color used for `resize_and_pad`
+
 Vips uses black as the default background color `resize_and_pad`, instead of white like ImageMagick. Fix that by using the `background` option:
 
 ```diff
@@ -576,6 +579,7 @@ Vips uses black as the default background color `resize_and_pad`, instead of whi
 ```
 
 #### Remove any EXIF based rotation
+
 Vips will auto rotate images using the EXIF value when processing variants. If you were storing rotation values from user uploaded photos to apply rotation with ImageMagick, you must stop doing that:
 
 ```diff
@@ -584,6 +588,7 @@ Vips will auto rotate images using the EXIF value when processing variants. If y
 ```
 
 #### Replace monochrome with colourspace
+
 Vips uses a different option to make monochrome images:
 
 ```diff
@@ -592,6 +597,7 @@ Vips uses a different option to make monochrome images:
 ```
 
 #### Switch to libvips options for compressing images
+
 JPEG
 
 ```diff
@@ -621,6 +627,7 @@ GIF
 ```
 
 #### Deploy to production
+
 Active Storage encodes into the url for the image the list of transformations that must be performed.
 If your app is caching these urls, your images will break after you deploy the new code to production.
 Because of this you must manually invalidate your affected cache keys.
@@ -1895,7 +1902,7 @@ The migration procedure is as follows:
 2. run `bundle install`.
 3. run `bin/rake db:schema:dump`.
 4. make sure that `db/schema.rb` contains every foreign key definition with
-the necessary options.
+  the necessary options.
 
 Upgrading from Rails 4.0 to Rails 4.1
 -------------------------------------
@@ -2441,12 +2448,12 @@ Rails 4.0 no longer supports loading plugins from `vendor/plugins`. You must rep
 * Rails 4.0 has changed `serialized_attributes` and `attr_readonly` to class methods only. You shouldn't use instance methods since it's now deprecated. You should change them to use class methods, e.g. `self.serialized_attributes` to `self.class.serialized_attributes`.
 
 * When using the default coder, assigning `nil` to a serialized attribute will save it
-to the database as `NULL` instead of passing the `nil` value through YAML (`"--- \n...\n"`).
+  to the database as `NULL` instead of passing the `nil` value through YAML (`"--- \n...\n"`).
 
 * Rails 4.0 has removed `attr_accessible` and `attr_protected` feature in favor of Strong Parameters. You can use the [Protected Attributes gem](https://github.com/rails/protected_attributes) for a smooth upgrade path.
 
 * If you are not using Protected Attributes, you can remove any options related to
-this gem such as `whitelist_attributes` or `mass_assignment_sanitizer` options.
+  this gem such as `whitelist_attributes` or `mass_assignment_sanitizer` options.
 
 * Rails 4.0 requires that scopes use a callable object such as a Proc or lambda:
 
@@ -2512,7 +2519,7 @@ Rails 4.0 extracted Active Resource to its own gem. If you still need the featur
 
 ### Action Pack
 
-*   Rails 4.0 introduces `ActiveSupport::KeyGenerator` and uses this as a base from which to generate and verify signed cookies (among other things). Existing signed cookies generated with Rails 3.x will be transparently upgraded if you leave your existing `secret_token` in place and add the new `secret_key_base`.
+* Rails 4.0 introduces `ActiveSupport::KeyGenerator` and uses this as a base from which to generate and verify signed cookies (among other things). Existing signed cookies generated with Rails 3.x will be transparently upgraded if you leave your existing `secret_token` in place and add the new `secret_key_base`.
 
     ```ruby
       # config/initializers/secret_token.rb
@@ -2524,7 +2531,7 @@ Rails 4.0 extracted Active Resource to its own gem. If you still need the featur
 
     If you are relying on the ability for external applications or JavaScript to be able to read your Rails app's signed session cookies (or signed cookies in general) you should not set `secret_key_base` until you have decoupled these concerns.
 
-*   Rails 4.0 encrypts the contents of cookie-based sessions if `secret_key_base` has been set. Rails 3.x signed, but did not encrypt, the contents of cookie-based session. Signed cookies are "secure" in that they are verified to have been generated by your app and are tamper-proof. However, the contents can be viewed by end users, and encrypting the contents eliminates this caveat/concern without a significant performance penalty.
+* Rails 4.0 encrypts the contents of cookie-based sessions if `secret_key_base` has been set. Rails 3.x signed, but did not encrypt, the contents of cookie-based session. Signed cookies are "secure" in that they are verified to have been generated by your app and are tamper-proof. However, the contents can be viewed by end users, and encrypting the contents eliminates this caveat/concern without a significant performance penalty.
 
     Please read [Pull Request #9978](https://github.com/rails/rails/pull/9978) for details on the move to encrypted session cookies.
 
@@ -2543,13 +2550,13 @@ Rails 4.0 extracted Active Resource to its own gem. If you still need the featur
 * Rails 4.0 deprecates the `dom_id` and `dom_class` methods in controllers (they are fine in views). You will need to include the `ActionView::RecordIdentifier` module in controllers requiring this feature.
 
 * Rails 4.0 deprecates the `:confirm` option for the `link_to` helper. You should
-instead rely on a data attribute (e.g. `data: { confirm: 'Are you sure?' }`).
+  instead rely on a data attribute (e.g. `data: { confirm: 'Are you sure?' }`).
-This deprecation also concerns the helpers based on this one (such as `link_to_if`
+  This deprecation also concerns the helpers based on this one (such as `link_to_if`
-or `link_to_unless`).
+  or `link_to_unless`).
 
 * Rails 4.0 changed how `assert_generates`, `assert_recognizes`, and `assert_routing` work. Now all these assertions raise `Assertion` instead of `ActionController::RoutingError`.
 
-*   Rails 4.0 raises an `ArgumentError` if clashing named routes are defined. This can be triggered by explicitly defined named routes or by the `resources` method. Here are two examples that clash with routes named `example_path`:
+* Rails 4.0 raises an `ArgumentError` if clashing named routes are defined. This can be triggered by explicitly defined named routes or by the `resources` method. Here are two examples that clash with routes named `example_path`:
 
     ```ruby
     get 'one' => 'test#example', as: :example
@@ -2566,7 +2573,7 @@ or `link_to_unless`).
     the `resources` method to restrict the routes created as detailed in the
     [Routing Guide](routing.html#restricting-the-routes-created).
 
-*   Rails 4.0 also changed the way unicode character routes are drawn. Now you can draw unicode character routes directly. If you already draw such routes, you must change them, for example:
+* Rails 4.0 also changed the way unicode character routes are drawn. Now you can draw unicode character routes directly. If you already draw such routes, you must change them, for example:
 
     ```ruby
     get Rack::Utils.escape('こんにちは'), controller: 'welcome', action: 'index'
@@ -2578,7 +2585,7 @@ or `link_to_unless`).
     get 'こんにちは', controller: 'welcome', action: 'index'
     ```
 
-*   Rails 4.0 requires that routes using `match` must specify the request method. For example:
+* Rails 4.0 requires that routes using `match` must specify the request method. For example:
 
     ```ruby
       # Rails 3.x
@@ -2591,7 +2598,7 @@ or `link_to_unless`).
       get '/' => 'root#index'
     ```
 
-*   Rails 4.0 has removed `ActionDispatch::BestStandardsSupport` middleware, `<!DOCTYPE html>` already triggers standards mode per https://msdn.microsoft.com/en-us/library/jj676915(v=vs.85).aspx and ChromeFrame header has been moved to `config.action_dispatch.default_headers`.
+* Rails 4.0 has removed `ActionDispatch::BestStandardsSupport` middleware, `<!DOCTYPE html>` already triggers standards mode per https://msdn.microsoft.com/en-us/library/jj676915(v=vs.85).aspx and ChromeFrame header has been moved to `config.action_dispatch.default_headers`.
 
     Remember you must also remove any references to the middleware from your application code, for example:
 
@@ -2602,7 +2609,7 @@ or `link_to_unless`).
 
     Also check your environment settings for `config.action_dispatch.best_standards_support` and remove it if present.
 
-*   Rails 4.0 allows configuration of HTTP headers by setting `config.action_dispatch.default_headers`. The defaults are as follows:
+* Rails 4.0 allows configuration of HTTP headers by setting `config.action_dispatch.default_headers`. The defaults are as follows:
 
     ```ruby
       config.action_dispatch.default_headers = {

guides/source/working_with_javascript_in_rails.md

@@ -11,7 +11,7 @@ After reading this guide, you will know:
 
 * How to use Rails without the need for a Node.js, Yarn, or a JavaScript bundler.
 * How to create a new Rails application using import maps, esbuild, rollup, or webpack to bundle
-your JavaScript.
+  your JavaScript.
 * What Turbo is, and how to use it.
 * How to use the Turbo HTML helpers provided by Rails.
 
@@ -130,13 +130,10 @@ that you should choose a traditional bundler include:
 
 * If your code requires a transpilation step, such as JSX or TypeScript.
 * If you need to use JavaScript libraries that include CSS or otherwise rely on
-[Webpack loaders](https://webpack.js.org/loaders/).
+  [Webpack loaders](https://webpack.js.org/loaders/).
 * If you are absolutely sure that you need
-[tree-shaking](https://webpack.js.org/guides/tree-shaking/).
+  [tree-shaking](https://webpack.js.org/guides/tree-shaking/).
-* If you will install Bootstrap, Bulma, PostCSS, or Dart CSS through the
+* If you will install Bootstrap, Bulma, PostCSS, or Dart CSS through the [cssbundling-rails gem](https://github.com/rails/cssbundling-rails). All options provided by this gem except Tailwind and Sass will automatically install `esbuild` for you if you do not specify a different option in `rails new`.
-[cssbundling-rails gem](https://github.com/rails/cssbundling-rails). All options provided by this
-gem except Tailwind and Sass will automatically install `esbuild` for you if you do not specify a different
-option in `rails new`.
 
 Turbo
 -----