diff --git a/guides/source/action_cable_overview.md b/guides/source/action_cable_overview.md
index 9f7cf121ed..d4228c4321 100644
--- a/guides/source/action_cable_overview.md
+++ b/guides/source/action_cable_overview.md
@@ -770,9 +770,10 @@ in the development environment.
### Consumer Configuration
To configure the URL, add a call to [`action_cable_meta_tag`][] in your HTML layout
-HEAD. This uses a URL or path typically set via `config.action_cable.url` in the
+HEAD. This uses a URL or path typically set via [`config.action_cable.url`][] in the
environment configuration files.
+[`config.action_cable.url`]: configuring.html#config-action-cable-url
[`action_cable_meta_tag`]: https://api.rubyonrails.org/classes/ActionCable/Helpers/ActionCableHelper.html#method-i-action_cable_meta_tag
### Worker Pool Configuration
@@ -823,7 +824,7 @@ For a full list of all configuration options, see the
Action Cable can run alongside your Rails application. For example, to
listen for WebSocket requests on `/websocket`, specify that path to
-`config.action_cable.mount_path`:
+[`config.action_cable.mount_path`][]:
```ruby
# config/application.rb
@@ -840,6 +841,8 @@ For every instance of your server you create, and for every worker your server
spawns, you will also have a new instance of Action Cable, but the Redis or
PostgreSQL adapter keeps messages synced across connections.
+[`config.action_cable.mount_path`]: configuring.html#config-action-cable-mount-path
+
### Standalone
The cable servers can be separated from your normal application server. It's
diff --git a/guides/source/action_controller_overview.md b/guides/source/action_controller_overview.md
index 56b670db5f..86a286fed4 100644
--- a/guides/source/action_controller_overview.md
+++ b/guides/source/action_controller_overview.md
@@ -1167,7 +1167,7 @@ Rails keeps a log file for each environment in the `log` folder. These are extre
### Parameters Filtering
You can filter out sensitive request parameters from your log files by
-appending them to `config.filter_parameters` in the application configuration.
+appending them to [`config.filter_parameters`][] in the application configuration.
These parameters will be marked [FILTERED] in the log.
```ruby
@@ -1180,6 +1180,8 @@ expression. Rails adds a list of default filters, including `:passw`,
(`initializers/filter_parameter_logging.rb`) to handle typical application
parameters like `password`, `password_confirmation` and `my_token`.
+[`config.filter_parameters`]: configuring.html#config-filter-parameters
+
### Redirects Filtering
Sometimes it's desirable to filter out from log files some sensitive locations your application is redirecting to.
@@ -1272,6 +1274,7 @@ Force HTTPS protocol
If you'd like to ensure that communication to your controller is only possible
via HTTPS, you should do so by enabling the [`ActionDispatch::SSL`][] middleware via
-`config.force_ssl` in your environment configuration.
+[`config.force_ssl`][] in your environment configuration.
+[`config.force_ssl`]: configuring.html#config-force-ssl
[`ActionDispatch::SSL`]: https://api.rubyonrails.org/classes/ActionDispatch/SSL.html
diff --git a/guides/source/action_mailbox_basics.md b/guides/source/action_mailbox_basics.md
index 8b8e81813f..b489c3e3dd 100644
--- a/guides/source/action_mailbox_basics.md
+++ b/guides/source/action_mailbox_basics.md
@@ -333,11 +333,13 @@ on your side of the application. The InboundEmail simply stays in the system
for the extra time to provide debugging and forensics options.
The actual incineration is done via the `IncinerationJob` that's scheduled
-to run after `config.action_mailbox.incinerate_after` time. This value is
+to run after [`config.action_mailbox.incinerate_after`][] time. This value is
by default set to `30.days`, but you can change it in your production.rb
configuration. (Note that this far-future incineration scheduling relies on
your job queue being able to hold jobs for that long.)
+[`config.action_mailbox.incinerate_after`]: configuring.html#config-action-mailbox-incinerate-after
+
## Working with Action Mailbox in development
It's helpful to be able to test incoming emails in development without actually
diff --git a/guides/source/action_mailer_basics.md b/guides/source/action_mailer_basics.md
index 50c0da2e05..d69561cff1 100644
--- a/guides/source/action_mailer_basics.md
+++ b/guides/source/action_mailer_basics.md
@@ -815,7 +815,7 @@ files (environment.rb, production.rb, etc...)
|`smtp_settings`|Allows detailed configuration for `:smtp` delivery method:
- `:address` - Allows you to use a remote mail server. Just change it from its default `"localhost"` setting.
- `:port` - On the off chance that your mail server doesn't run on port 25, you can change it.
- `:domain` - If you need to specify a HELO domain, you can do it here.
- `:user_name` - If your mail server requires authentication, set the username in this setting.
- `:password` - If your mail server requires authentication, set the password in this setting.
- `:authentication` - If your mail server requires authentication, you need to specify the authentication type here. This is a symbol and one of `:plain` (will send the password in the clear), `:login` (will send password Base64 encoded) or `:cram_md5` (combines a Challenge/Response mechanism to exchange information and a cryptographic Message Digest 5 algorithm to hash important information)
- `:enable_starttls` - Use STARTTLS when connecting to your SMTP server and fail if unsupported. Defaults to `false`.
- `:enable_starttls_auto` - Detects if STARTTLS is enabled in your SMTP server and starts to use it. Defaults to `true`.
- `:openssl_verify_mode` - When using TLS, you can set how OpenSSL checks the certificate. This is really useful if you need to validate a self-signed and/or a wildcard certificate. You can use the name of an OpenSSL verify constant ('none' or 'peer') or directly the constant (`OpenSSL::SSL::VERIFY_NONE` or `OpenSSL::SSL::VERIFY_PEER`).
- `:ssl/:tls` - Enables the SMTP connection to use SMTP/TLS (SMTPS: SMTP over direct TLS connection)
- `:open_timeout` - Number of seconds to wait while attempting to open a connection.
- `:read_timeout` - Number of seconds to wait until timing-out a read(2) call.
|
|`sendmail_settings`|Allows you to override options for the `:sendmail` delivery method.- `:location` - The location of the sendmail executable. Defaults to `/usr/sbin/sendmail`.
- `:arguments` - The command line arguments to be passed to sendmail. Defaults to `-i`.
|
|`raise_delivery_errors`|Whether or not errors should be raised if the email fails to be delivered. This only works if the external email server is configured for immediate delivery.|
-|`delivery_method`|Defines a delivery method. Possible values are:- `:smtp` (default), can be configured by using `config.action_mailer.smtp_settings`.
- `:sendmail`, can be configured by using `config.action_mailer.sendmail_settings`.
- `:file`: save emails to files; can be configured by using `config.action_mailer.file_settings`.
- `:test`: save emails to `ActionMailer::Base.deliveries` array.
See [API docs](https://api.rubyonrails.org/classes/ActionMailer/Base.html) for more info.|
+|`delivery_method`|Defines a delivery method. Possible values are:- `:smtp` (default), can be configured by using [`config.action_mailer.smtp_settings`][].
- `:sendmail`, can be configured by using [`config.action_mailer.sendmail_settings`][].
- `:file`: save emails to files; can be configured by using `config.action_mailer.file_settings`.
- `:test`: save emails to `ActionMailer::Base.deliveries` array.
See [API docs](https://api.rubyonrails.org/classes/ActionMailer/Base.html) for more info.|
|`perform_deliveries`|Determines whether deliveries are actually carried out when the `deliver` method is invoked on the Mail message. By default they are, but this can be turned off to help functional testing. If this value is `false`, `deliveries` array will not be populated even if `delivery_method` is `:test`.|
|`deliveries`|Keeps an array of all the emails sent out through the Action Mailer with delivery_method :test. Most useful for unit and functional testing.|
|`delivery_job`|The job class used with `deliver_later`. Defaults to `ActionMailer::MailDeliveryJob`.|
@@ -826,6 +826,9 @@ For a complete writeup of possible configurations see the
[Configuring Action Mailer](configuring.html#configuring-action-mailer) in
our Configuring Rails Applications guide.
+[`config.action_mailer.sendmail_settings`]: configuring.html#config-action-mailer-sendmail-settings
+[`config.action_mailer.smtp_settings`]: configuring.html#config-action-mailer-smtp-settings
+
### Example Action Mailer Configuration
An example would be adding the following to your appropriate
diff --git a/guides/source/action_view_helpers.md b/guides/source/action_view_helpers.md
index b8082fb95c..0b93fdcd30 100644
--- a/guides/source/action_view_helpers.md
+++ b/guides/source/action_view_helpers.md
@@ -23,7 +23,7 @@ The following is only a brief overview summary of the helpers available in Actio
This module provides methods for generating HTML that links views to assets such as images, JavaScript files, stylesheets, and feeds.
-By default, Rails links to these assets on the current host in the public folder, but you can direct Rails to link to assets from a dedicated assets server by setting `config.asset_host` in the application configuration, typically in `config/environments/production.rb`. For example, let's say your asset host is `assets.example.com`:
+By default, Rails links to these assets on the current host in the public folder, but you can direct Rails to link to assets from a dedicated assets server by setting [`config.asset_host`][] in the application configuration, typically in `config/environments/production.rb`. For example, let's say your asset host is `assets.example.com`:
```ruby
config.asset_host = "assets.example.com"
@@ -31,6 +31,8 @@ image_tag("rails.png")
# =>
```
+[`config.asset_host`]: configuring.html#config-asset-host
+
#### auto_discovery_link_tag
Returns a link tag that browsers and feed readers can use to auto-detect an RSS, Atom, or JSON feed.
diff --git a/guides/source/active_job_basics.md b/guides/source/active_job_basics.md
index 646824bff3..b926274fe7 100644
--- a/guides/source/active_job_basics.md
+++ b/guides/source/active_job_basics.md
@@ -130,7 +130,7 @@ see the API Documentation for [`ActiveJob::QueueAdapters`][].
### Setting the Backend
-You can easily set your queuing backend:
+You can easily set your queuing backend with [`config.active_job.queue_adapter`]:
```ruby
# config/application.rb
@@ -156,6 +156,8 @@ end
# was configured in `config.active_job.queue_adapter`.
```
+[`config.active_job.queue_adapter`]: configuring.html#config-active-job-queue-adapter
+
### Starting the Backend
Since jobs run in parallel to your Rails application, most queuing libraries
@@ -188,7 +190,7 @@ end
```
You can prefix the queue name for all your jobs using
-`config.active_job.queue_name_prefix` in `application.rb`:
+[`config.active_job.queue_name_prefix`][] in `application.rb`:
```ruby
# config/application.rb
@@ -225,7 +227,7 @@ end
```
The default queue name prefix delimiter is '\_'. This can be changed by setting
-`config.active_job.queue_name_delimiter` in `application.rb`:
+[`config.active_job.queue_name_delimiter`][] in `application.rb`:
```ruby
# config/application.rb
@@ -284,6 +286,8 @@ ProcessVideoJob.perform_later(Video.last)
NOTE: Make sure your queuing backend "listens" on your queue name. For some
backends you need to specify the queues to listen to.
+[`config.active_job.queue_name_delimiter`]: configuring.html#config-active-job-queue-name-delimiter
+[`config.active_job.queue_name_prefix`]: configuring.html#config-active-job-queue-name-prefix
[`queue_as`]: https://api.rubyonrails.org/classes/ActiveJob/QueueName/ClassMethods.html#method-i-queue_as
Callbacks
diff --git a/guides/source/active_record_migrations.md b/guides/source/active_record_migrations.md
index 6d6ac54060..e550b0f84f 100644
--- a/guides/source/active_record_migrations.md
+++ b/guides/source/active_record_migrations.md
@@ -1029,7 +1029,7 @@ summed up in the schema file.
### Types of Schema Dumps
The format of the schema dump generated by Rails is controlled by the
-`config.active_record.schema_format` setting in `config/application.rb`. By
+[`config.active_record.schema_format`][] setting in `config/application.rb`. By
default, the format is `:ruby`, but can also be set to `:sql`.
If `:ruby` is selected, then the schema is stored in `db/schema.rb`. If you look
@@ -1074,6 +1074,8 @@ To load the schema from `db/structure.sql`, run `bin/rails db:schema:load`.
Loading this file is done by executing the SQL statements it contains. By
definition, this will create a perfect copy of the database's structure.
+[`config.active_record.schema_format`]: configuring.html#config-active-record-schema-format
+
### Schema Dumps and Source Control
Because schema files are commonly used to create new databases, it is strongly
diff --git a/guides/source/active_record_multiple_databases.md b/guides/source/active_record_multiple_databases.md
index 7d7883b2a3..1d94c345fa 100644
--- a/guides/source/active_record_multiple_databases.md
+++ b/guides/source/active_record_multiple_databases.md
@@ -482,7 +482,7 @@ config.active_record.shard_resolver = ->(request) {
In Rails 6.1+, Active Record provides a new internal API for connection management.
In most cases applications will not need to make any changes except to opt-in to the
new behavior (if upgrading from 6.0 and below) by setting
-`config.active_record.legacy_connection_handling = false`. If you have a single database
+[`config.active_record.legacy_connection_handling`][] to `false`. If you have a single database
application, no other changes will be required. If you have a multiple database application
the following changes are required if your application is using these methods:
@@ -500,11 +500,13 @@ you'll want writing or reading pools with `connection_handler.connection_pool_li
* If you turn off `legacy_connection_handling` in your application, any method that's unsupported
will raise an error (i.e. `connection_handlers=`).
+[`config.active_record.legacy_connection_handling`]: configuring.html#config-active-record-legacy-connection-handling
+
## Granular Database Connection Switching
In Rails 6.1 it's possible to switch connections for one database instead of
all databases globally. To use this feature you must first set
-`config.active_record.legacy_connection_handling` to `false` in your application
+[`config.active_record.legacy_connection_handling`][] to `false` in your application
configuration. The majority of applications should not need to make any other
changes since the public APIs have the same behavior. See the above section for
how to enable and migrate away from `legacy_connection_handling`.
@@ -546,7 +548,7 @@ connections globally.
### Handling associations with joins across databases
As of Rails 7.0+, Active Record has an option for handling associations that would perform
-a join across multiple databases. If you have a has many through or a has one through association
+a join across multiple databases. If you have a has many through or a has one through association
that you want to disable joining and perform 2 or more queries, pass the `disable_joins: true` option.
For example:
@@ -570,8 +572,8 @@ class Yard
end
```
-Previously calling `@dog.treats` without `disable_joins` or `@dog.yard` without `disable_joins`
-would raise an error because databases are unable to handle joins across clusters. With the
+Previously calling `@dog.treats` without `disable_joins` or `@dog.yard` without `disable_joins`
+would raise an error because databases are unable to handle joins across clusters. With the
`disable_joins` option, Rails will generate multiple select queries
to avoid attempting joining across clusters. For the above association, `@dog.treats` would generate the
following SQL:
diff --git a/guides/source/active_record_querying.md b/guides/source/active_record_querying.md
index 715e00b57a..e0a0f13b29 100644
--- a/guides/source/active_record_querying.md
+++ b/guides/source/active_record_querying.md
@@ -419,11 +419,12 @@ as long as they have no ordering, since the method needs to force an order
internally to iterate.
If an order is present in the receiver the behaviour depends on the flag
-`config.active_record.error_on_ignored_order`. If true, `ArgumentError` is
+[`config.active_record.error_on_ignored_order`][]. If true, `ArgumentError` is
raised, otherwise the order is ignored and a warning issued, which is the
default. This can be overridden with the option `:error_on_ignore`, explained
below.
+[`config.active_record.error_on_ignored_order`]: configuring.html#config-active-record-error-on-ignored-order
[`find_each`]: https://api.rubyonrails.org/classes/ActiveRecord/Batches.html#method-i-find_each
##### Options for `find_each`
diff --git a/guides/source/active_storage_overview.md b/guides/source/active_storage_overview.md
index 8fe9abee30..ec61daf2d0 100644
--- a/guides/source/active_storage_overview.md
+++ b/guides/source/active_storage_overview.md
@@ -821,7 +821,7 @@ The Active Storage variant tracker improves performance of this, by storing a
record in the database if the requested representation has been processed before.
Thus, the above code will only make an API call to the remote service (e.g. S3)
once, and once a variant is stored, will use that. The variant tracker runs
-automatically, but can be disabled through `config.active_storage.track_variants`.
+automatically, but can be disabled through [`config.active_storage.track_variants`][].
If you're rendering lots of images on a page, the above example could result
in N+1 queries loading all the variant records. To avoid these N+1 queries,
@@ -833,6 +833,7 @@ message.images.with_all_variant_records.each do |file|
end
```
+[`config.active_storage.track_variants`]: configuring.html#config-active-storage-track-variants
[`ActiveStorage::Representations::RedirectController`]: https://api.rubyonrails.org/classes/ActiveStorage/Representations/RedirectController.html
[`ActiveStorage::Attachment`]: https://api.rubyonrails.org/classes/ActiveStorage/Attachment.html
@@ -852,16 +853,15 @@ location.
If a variant is requested, Active Storage will automatically apply
transformations depending on the image's format:
-1. Content types that are variable (as dictated by `config.active_storage.variable_content_types`)
- and not considered web images (as dictated by `config.active_storage.web_image_content_types`),
+1. Content types that are variable (as dictated by [`config.active_storage.variable_content_types`][])
+ and not considered web images (as dictated by [`config.active_storage.web_image_content_types`][]),
will be converted to PNG.
2. If `quality` is not specified, the variant processor's default quality for the format will be used.
Active Storage can use either [Vips][] or MiniMagick as the variant processor.
The default depends on your `config.load_defaults` target version, and the
-processor can be changed by setting [`config.active_storage.variant_processor`](
-configuring.html#config-active-storage-variant-processor).
+processor can be changed by setting [`config.active_storage.variant_processor`][].
The two processors are not fully compatible, so when migrating an existing application
between MiniMagick and Vips, some changes have to be made if using options that are format
@@ -875,6 +875,9 @@ specific:
<%= image_tag user.avatar.variant(resize_to_limit: [100, 100], format: :jpeg, saver: { subsample_mode: "on", strip: true, interlace: true, quality: 80 }) %>
```
+[`config.active_storage.variable_content_types`]: configuring.html#config-active-storage-variable-content-types
+[`config.active_storage.variant_processor`]: configuring.html#config-active-storage-variant-processor
+[`config.active_storage.web_image_content_types`]: configuring.html#config-active-storage-web-image-content-types
[`variant`]: https://api.rubyonrails.org/classes/ActiveStorage/Blob/Representable.html#method-i-variant
[Vips]: https://www.rubydoc.info/gems/ruby-vips/Vips/Image
diff --git a/guides/source/active_support_core_extensions.md b/guides/source/active_support_core_extensions.md
index d4bf68840c..cf16a0c3d0 100644
--- a/guides/source/active_support_core_extensions.md
+++ b/guides/source/active_support_core_extensions.md
@@ -85,7 +85,9 @@ That does not even put the entire Active Support in memory upfront indeed, some
### Active Support Within a Ruby on Rails Application
-A Ruby on Rails application loads all Active Support unless `config.active_support.bare` is true. In that case, the application will only load what the framework itself cherry-picks for its own needs, and can still cherry-pick itself at any granularity level, as explained in the previous section.
+A Ruby on Rails application loads all Active Support unless [`config.active_support.bare`][] is true. In that case, the application will only load what the framework itself cherry-picks for its own needs, and can still cherry-pick itself at any granularity level, as explained in the previous section.
+
+[`config.active_support.bare`]: configuring.html#config-active-support-bare
Extensions to All Objects
-------------------------
@@ -3214,7 +3216,7 @@ NOTE: Defined in `active_support/core_ext/date/calculations.rb`.
The methods [`beginning_of_week`][DateAndTime::Calculations#beginning_of_week] and [`end_of_week`][DateAndTime::Calculations#end_of_week] return the dates for the
beginning and end of the week, respectively. Weeks are assumed to start on
Monday, but that can be changed passing an argument, setting thread local
-`Date.beginning_of_week` or `config.beginning_of_week`.
+`Date.beginning_of_week` or [`config.beginning_of_week`][].
```ruby
d = Date.new(2010, 5, 8) # => Sat, 08 May 2010
@@ -3228,6 +3230,7 @@ d.end_of_week(:sunday) # => Sat, 08 May 2010
NOTE: Defined in `active_support/core_ext/date_and_time/calculations.rb`.
+[`config.beginning_of_week`]: configuring.html#config-beginning-of-week
[DateAndTime::Calculations#at_beginning_of_week]: https://api.rubyonrails.org/classes/DateAndTime/Calculations.html#method-i-at_beginning_of_week
[DateAndTime::Calculations#at_end_of_week]: https://api.rubyonrails.org/classes/DateAndTime/Calculations.html#method-i-at_end_of_week
[DateAndTime::Calculations#beginning_of_week]: https://api.rubyonrails.org/classes/DateAndTime/Calculations.html#method-i-beginning_of_week
@@ -3257,7 +3260,7 @@ NOTE: Defined in `active_support/core_ext/date_and_time/calculations.rb`.
##### `prev_week`, `next_week`
-The method [`next_week`][DateAndTime::Calculations#next_week] receives a symbol with a day name in English (default is the thread local [`Date.beginning_of_week`][Date.beginning_of_week], or `config.beginning_of_week`, or `:monday`) and it returns the date corresponding to that day.
+The method [`next_week`][DateAndTime::Calculations#next_week] receives a symbol with a day name in English (default is the thread local [`Date.beginning_of_week`][Date.beginning_of_week], or [`config.beginning_of_week`][], or `:monday`) and it returns the date corresponding to that day.
```ruby
d = Date.new(2010, 5, 9) # => Sun, 09 May 2010
diff --git a/guides/source/api_app.md b/guides/source/api_app.md
index a643144091..7356d4e66f 100644
--- a/guides/source/api_app.md
+++ b/guides/source/api_app.md
@@ -163,7 +163,7 @@ class definition:
config.api_only = true
```
-In `config/environments/development.rb`, set `config.debug_exception_response_format`
+In `config/environments/development.rb`, set [`config.debug_exception_response_format`][]
to configure the format used in responses when errors occur in development mode.
To render an HTML page with debugging information, use the value `:default`.
@@ -194,6 +194,8 @@ class ApplicationController < ActionController::API
end
```
+[`config.debug_exception_response_format`]: configuring.html#config-debug-exception-response-format
+
Choosing Middleware
--------------------
@@ -285,7 +287,7 @@ If your front-end server supports accelerated file sending, `Rack::Sendfile`
will offload the actual file sending work to the front-end server.
You can configure the name of the header that your front-end server uses for
-this purpose using `config.action_dispatch.x_sendfile_header` in the appropriate
+this purpose using [`config.action_dispatch.x_sendfile_header`][] in the appropriate
environment's configuration file.
You can learn more about how to use `Rack::Sendfile` with popular
@@ -306,6 +308,8 @@ config.action_dispatch.x_sendfile_header = "X-Accel-Redirect"
Make sure to configure your server to support these options following the
instructions in the `Rack::Sendfile` documentation.
+[`config.action_dispatch.x_sendfile_header`]: configuring.html#config-action-dispatch-x-sendfile-header
+
### Using ActionDispatch::Request
`ActionDispatch::Request#params` will take parameters from the client in the JSON
diff --git a/guides/source/asset_pipeline.md b/guides/source/asset_pipeline.md
index 48f0159d4f..bf117164dd 100644
--- a/guides/source/asset_pipeline.md
+++ b/guides/source/asset_pipeline.md
@@ -41,8 +41,8 @@ gem 'sassc-rails'
```
To set asset compression methods, set the appropriate configuration options
-in `production.rb` - `config.assets.css_compressor` for your CSS and
-`config.assets.js_compressor` for your JavaScript:
+in `production.rb` - [`config.assets.css_compressor`][] for your CSS and
+[`config.assets.js_compressor`][] for your JavaScript:
```ruby
config.assets.css_compressor = :yui
@@ -52,6 +52,9 @@ config.assets.js_compressor = :terser
NOTE: The `sassc-rails` gem is automatically used for CSS compression if included
in the `Gemfile` and no `config.assets.css_compressor` option is set.
+[`config.assets.css_compressor`]: configuring.html#config-assets-css-compressor
+[`config.assets.js_compressor`]: configuring.html#config-assets-js-compressor
+
### Main Features
The first feature of the pipeline is to concatenate assets, which can reduce the
@@ -134,13 +137,15 @@ that filenames are consistent based on their content.
Fingerprinting is enabled by default for both the development and production
environments. You can enable or disable it in your configuration through the
-`config.assets.digest` option.
+[`config.assets.digest`][] option.
More reading:
* [Optimize caching](https://developers.google.com/speed/docs/insights/LeverageBrowserCaching)
* [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
+
How to Use the Asset Pipeline
-----------------------------
@@ -152,13 +157,15 @@ directory. Files in this directory are served by the Sprockets middleware.
Assets can still be placed in the `public` hierarchy. Any assets under `public`
will be served as static files by the application or web server when
-`config.public_file_server.enabled` is set to true. You should use `app/assets` for
+[`config.public_file_server.enabled`][] is set to true. You should use `app/assets` for
files that must undergo some pre-processing before they are served.
In production, Rails precompiles these files to `public/assets` by default. The
precompiled copies are then served as static assets by the web server. The files
in `app/assets` are never served directly in production.
+[`config.public_file_server.enabled`]: configuring.html#config-public-file-server-enabled
+
### Controller Specific Assets
When you generate a scaffold or a controller, Rails also generates a
@@ -248,7 +255,7 @@ is referenced as:
```
You can view the search path by inspecting
-`Rails.application.config.assets.paths` in the Rails console.
+[`Rails.application.config.assets.paths`][`config.assets.paths`] in the Rails console.
Besides the standard `assets/*` paths, additional (fully qualified) paths can be
added to the pipeline in `config/initializers/assets.rb`. For example:
@@ -265,6 +272,8 @@ It is important to note that files you want to reference outside a manifest must
be added to the precompile array or they will not be available in the production
environment.
+[`config.assets.paths`]: configuring.html#config-assets-paths
+
#### Using Index Files
Sprockets uses files named `index` (with the relevant extensions) for a special
@@ -319,7 +328,7 @@ Alternatively, a request for a file with an SHA256 hash such as
is treated the same way. How these hashes are generated is covered in the [In
Production](#in-production) section later on in this guide.
-Sprockets will also look through the paths specified in `config.assets.paths`,
+Sprockets will also look through the paths specified in [`config.assets.paths`][],
which includes the standard application paths and any paths added by Rails
engines.
@@ -598,7 +607,7 @@ NOTE: with the Asset Pipeline the `:cache` and `:concat` options aren't used
anymore, delete these options from the `javascript_include_tag` and
`stylesheet_link_tag`.
-The fingerprinting behavior is controlled by the `config.assets.digest`
+The fingerprinting behavior is controlled by the [`config.assets.digest`][]
initialization option (which defaults to `true`).
NOTE: Under normal circumstances the default `config.assets.digest` option
@@ -611,7 +620,7 @@ content changes.
Rails comes bundled with a command to compile the asset manifests and other
files in the pipeline.
-Compiled assets are written to the location specified in `config.assets.prefix`.
+Compiled assets are written to the location specified in [`config.assets.prefix`][].
By default, this is the `/assets` directory.
You can call this command on the server during deployment to create compiled
@@ -683,6 +692,8 @@ NOTE: If there are missing precompiled files in production you will get a
`Sprockets::Helpers::RailsHelper::AssetPaths::AssetNotPrecompiledError`
exception indicating the name of the missing file(s).
+[`config.assets.prefix`]: configuring.html#config-assets-prefix
+
#### Far-future Expires Header
Precompiled assets exist on the file system and are served directly by your web
@@ -829,7 +840,7 @@ valid CDN provider at the time of this writing). Now that you have configured
your CDN server, you need to tell browsers to use your CDN to grab assets
instead of your Rails server directly. You can do this by configuring Rails to
set your CDN as the asset host instead of using a relative path. To set your
-asset host in Rails, you need to set `config.asset_host` in
+asset host in Rails, you need to set [`config.asset_host`][] in
`config/environments/production.rb`:
```ruby
@@ -875,12 +886,15 @@ it for future use.
If you want to serve only some assets from your CDN, you can use custom `:host`
option your asset helper, which overwrites value set in
-`config.action_controller.asset_host`.
+[`config.action_controller.asset_host`][].
```erb
<%= asset_path 'image.png', host: 'mycdnsubdomain.fictional-cdn.com' %>
```
+[`config.action_controller.asset_host`]: configuring.html#config-action-controller-asset-host
+[`config.asset_host`]: configuring.html#config-asset-host
+
#### Customize CDN Caching Behavior
A CDN works by caching content. If the CDN has stale or bad content, then it is
diff --git a/guides/source/association_basics.md b/guides/source/association_basics.md
index 14d5ca52ed..164f417018 100644
--- a/guides/source/association_basics.md
+++ b/guides/source/association_basics.md
@@ -821,7 +821,7 @@ standard names. However, Active Record will not automatically identify
bi-directional associations that contain the `:through` or `:foreign_key`
options. Custom scopes on the opposite association also prevent automatic
identification, as do custom scopes on the association itself unless
-`config.active_record.automatic_scope_inversing` is set to true (the default for
+[`config.active_record.automatic_scope_inversing`][] is set to true (the default for
new applications).
For example, consider the following model declarations:
@@ -900,6 +900,8 @@ By including the `:inverse_of` option in the `has_many` association declaration,
Active Record will now recognize the bi-directional association and behave as in
the initial examples above.
+[`config.active_record.automatic_scope_inversing`]: configuring.html#config-active-record-automatic-scope-inversing
+
Detailed Association Reference
------------------------------
diff --git a/guides/source/autoloading_and_reloading_constants.md b/guides/source/autoloading_and_reloading_constants.md
index b5abf0630c..15731d5d15 100644
--- a/guides/source/autoloading_and_reloading_constants.md
+++ b/guides/source/autoloading_and_reloading_constants.md
@@ -178,9 +178,9 @@ Rails automatically reloads classes and modules if application files in the auto
More precisely, if the web server is running and application files have been modified, Rails unloads all autoloaded constants managed by the `main` autoloader just before the next request is processed. That way, application classes or modules used during that request will be autoloaded again, thus picking up their current implementation in the file system.
-Reloading can be enabled or disabled. The setting that controls this behavior is `config.cache_classes`, which is false by default in `development` mode (reloading enabled), and true by default in `production` mode (reloading disabled).
+Reloading can be enabled or disabled. The setting that controls this behavior is [`config.cache_classes`][], which is false by default in `development` mode (reloading enabled), and true by default in `production` mode (reloading disabled).
-Rails uses an evented file monitor to detect files changes by default. It can be configured instead to detect file changes by walking the autoload paths. This is controlled by the `config.file_watcher` setting.
+Rails uses an evented file monitor to detect files changes by default. It can be configured instead to detect file changes by walking the autoload paths. This is controlled by the [`config.file_watcher`][] setting.
In a Rails console there is no file watcher active regardless of the value of `config.cache_classes`. This is because, normally, it would be confusing to have code reloaded in the middle of a console session. Similar to an individual request, you generally want a console session to be served by a consistent, non-changing set of application classes and modules.
@@ -198,6 +198,9 @@ irb(main):003:0> User.object_id
As you can see, the class object stored in the `User` constant is different after reloading.
+[`config.cache_classes`]: configuring.html#config-cache-classes
+[`config.file_watcher`]: configuring.html#config-file-watcher
+
### Reloading and Stale Objects
It is very important to understand that Ruby does not have a way to truly reload classes and modules in memory, and have that reflected everywhere they are already used. Technically, "unloading" the `User` class means removing the `User` constant via `Object.send(:remove_const, "User")`.
@@ -300,12 +303,13 @@ Eager Loading
In production-like environments it is generally better to load all the application code when the application boots. Eager loading puts everything in memory ready to serve requests right away, and it is also [CoW](https://en.wikipedia.org/wiki/Copy-on-write)-friendly.
-Eager loading is controlled by the flag `config.eager_load`, which is enabled by default in `production` mode.
+Eager loading is controlled by the flag [`config.eager_load`][], which is enabled by default in `production` mode.
The order in which files are eager-loaded is undefined.
If the `Zeitwerk` constant is defined, Rails invokes `Zeitwerk::Loader.eager_load_all` regardless of the application autoloading mode. That ensures dependencies managed by Zeitwerk are eager-loaded.
+[`config.eager_load`]: configuring.html#config-eager-load
Single Table Inheritance
------------------------
diff --git a/guides/source/caching_with_rails.md b/guides/source/caching_with_rails.md
index 31dde87b69..a1cf2cd43f 100644
--- a/guides/source/caching_with_rails.md
+++ b/guides/source/caching_with_rails.md
@@ -36,13 +36,15 @@ page and action caching you will need to add `actionpack-page_caching` and
By default, caching is only enabled in your production environment. You can play
around with caching locally by running `rails dev:cache`, or by setting
-`config.action_controller.perform_caching` to `true` in `config/environments/development.rb`.
+[`config.action_controller.perform_caching`][] to `true` in `config/environments/development.rb`.
NOTE: Changing the value of `config.action_controller.perform_caching` will
only have an effect on the caching provided by Action Controller.
For instance, it will not impact low-level caching, that we address
[below](#low-level-caching).
+[`config.action_controller.perform_caching`]: configuring.html#config-action-controller-perform-caching
+
### Page Caching
Page caching is a Rails mechanism which allows the request for a generated page
diff --git a/guides/source/engines.md b/guides/source/engines.md
index 6bec907498..47746bbbbc 100644
--- a/guides/source/engines.md
+++ b/guides/source/engines.md
@@ -1508,7 +1508,7 @@ Configuration hooks do not hook into any particular framework, but instead they
| ---------------------- | ---------------------------------------------------------------------------------- |
| `before_configuration` | First configurable block to run. Called before any initializers are run. |
| `before_initialize` | Second configurable block to run. Called before frameworks initialize. |
-| `before_eager_load` | Third configurable block to run. Does not run if `config.eager_load` set to false. |
+| `before_eager_load` | Third configurable block to run. Does not run if [`config.eager_load`][] set to false. |
| `after_initialize` | Last configurable block to run. Called after frameworks initialize. |
Configuration hooks can be called in the Engine class.
@@ -1522,3 +1522,5 @@ module Blorgh
end
end
```
+
+[`config.eager_load`]: configuring.html#config-eager-load
diff --git a/guides/source/rails_on_rack.md b/guides/source/rails_on_rack.md
index 5faa91dfff..ecf4899f74 100644
--- a/guides/source/rails_on_rack.md
+++ b/guides/source/rails_on_rack.md
@@ -137,7 +137,9 @@ The default middlewares shown here (and some others) are each summarized in the
### Configuring Middleware Stack
-Rails provides a simple configuration interface `config.middleware` for adding, removing, and modifying the middlewares in the middleware stack via `application.rb` or the environment specific configuration file `environments/.rb`.
+Rails provides a simple configuration interface [`config.middleware`][] for adding, removing, and modifying the middlewares in the middleware stack via `application.rb` or the environment specific configuration file `environments/.rb`.
+
+[`config.middleware`]: configuring.html#config-middleware
#### Adding a Middleware
@@ -225,11 +227,15 @@ Much of Action Controller's functionality is implemented as Middlewares. The fol
**`Rack::Sendfile`**
-* Sets server specific X-Sendfile header. Configure this via `config.action_dispatch.x_sendfile_header` option.
+* Sets server specific X-Sendfile header. Configure this via [`config.action_dispatch.x_sendfile_header`][] option.
+
+[`config.action_dispatch.x_sendfile_header`]: configuring.html#config-action-dispatch-x-sendfile-header
**`ActionDispatch::Static`**
-* Used to serve static files from the public directory. Disabled if `config.public_file_server.enabled` is `false`.
+* Used to serve static files from the public directory. Disabled if [`config.public_file_server.enabled`][] is `false`.
+
+[`config.public_file_server.enabled`]: configuring.html#config-public-file-server-enabled
**`Rack::Lock`**
diff --git a/guides/source/security.md b/guides/source/security.md
index 17b5b91a98..68e9bc1901 100644
--- a/guides/source/security.md
+++ b/guides/source/security.md
@@ -287,7 +287,7 @@ There are many other possibilities, like using a `