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:| |`sendmail_settings`|Allows you to override options for the `:sendmail` delivery method.| |`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:See [API docs](https://api.rubyonrails.org/classes/ActionMailer/Base.html) for more info.| +|`delivery_method`|Defines a delivery method. Possible values are: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 `