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/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_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,6 +548,7 @@ Some common modules you might want to add:
       self.cache_store = :mem_cache_store
     end
     ```
+
     Rails does *not* pass this configuration automatically.
 
 The best place to add a module is in your `ApplicationController`, but you can

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
 -----------------------------
@@ -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

@@ -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/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/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.

guides/source/working_with_javascript_in_rails.md

@@ -133,10 +133,7 @@ that you should choose a traditional bundler include:
   [Webpack loaders](https://webpack.js.org/loaders/).
 * If you are absolutely sure that you need
   [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
 -----