Ruby on Rails Guides Guidelines — Ruby on Rails Guides

<!doctype html> <html dir="ltr" lang="en"> <head> <meta charset="utf-8"> <meta name="viewport" content="width=device-width, initial-scale=1"> <title>Ruby on Rails Guides Guidelines — Ruby on Rails Guides</title> <link rel="stylesheet" type="text/css" href="stylesheets/style-071e355820fc155a5c40ef8a1c0c4971.css" data-turbo-track="reload"> <link rel="stylesheet" type="text/css" href="stylesheets/print-a87ee66d50ce96bb83ac082f1249fe3e.css" media="print"> <link rel="stylesheet" type="text/css" href="stylesheets/highlight-a0d2133dd0073968b2d33b1f1360a2a3.css" data-turbo-track="reload"> <link rel="icon" href="images/favicon.ico" sizes="any"> <link rel="apple-touch-icon" href="images/icon.png"> <script src="javascripts/@hotwired--turbo-764f59c7edbeb902a9068c0340dd274e.js" data-turbo-track="reload"></script> <script src="javascripts/clipboard-8b7aed6f069f0cf58eeae353cd2f898b.js" data-turbo-track="reload"></script> <script src="javascripts/guides-897790ae3777ddd81bd4953f7ec99835.js" data-turbo-track="reload"></script> <meta property="og:title" content="Ruby on Rails Guides Guidelines — Ruby on Rails Guides" /> <meta name="description" content="Ruby on Rails Guides GuidelinesThis guide documents guidelines for writing Ruby on Rails Guides. This guide follows itself in a graceful loop, serving itself as an example.After reading this guide, you will know: About the conventions to be used in Rails documentation. How to generate guides locally." /> <meta property="og:description" content="Ruby on Rails Guides GuidelinesThis guide documents guidelines for writing Ruby on Rails Guides. This guide follows itself in a graceful loop, serving itself as an example.After reading this guide, you will know: About the conventions to be used in Rails documentation. How to generate guides locally." /> <meta property="og:locale" content="en_US" /> <meta property="og:site_name" content="Ruby on Rails Guides" /> <meta property="og:image" content="https://avatars.githubusercontent.com/u/4223" /> <meta property="og:type" content="website" /> <link rel="preconnect" href="https://fonts.googleapis.com"> <link rel="preconnect" href="https://fonts.gstatic.com" crossorigin> <link href="https://fonts.googleapis.com/css2?family=Noto+Sans+Arabic:wght@100..900&display=swap" rel="stylesheet"> <link href="https://fonts.googleapis.com/css2?family=Heebo:wght@100..900&family=Noto+Sans+Arabic:wght@100..900&display=swap" rel="stylesheet"> <meta name="theme-color" content="#C81418"> </head> <body dir="ltr" class="guide no-js"> <script> document.body.classList.remove('no-js') </script> <a id="main-skip-link" href="#main" class="skip-link" data-turbo="false"> Skip to main content </a> <div id="mobile-navigation-bar"> <div class="wrapper"> <strong class="more-info-label">More at <a href="https://rubyonrails.org/">rubyonrails.org:</a> </strong> <button type="button" class="js-only red-button more-info-button" id="more-info" aria-controls="more-info-links" aria-expanded="false"> More Ruby on Rails </button> <ul id="more-info-links" class="more-info-links hidden"> <li class="more-info"><a href="https://rubyonrails.org/blog">Blog</a></li> <li class="more-info"><a href="https://guides.rubyonrails.org/">Guides</a></li> <li class="more-info"><a href="https://api.rubyonrails.org/">API</a></li> <li class="more-info"><a href="https://discuss.rubyonrails.org/">Forum</a></li> <li class="more-info"><a href="https://github.com/rails/rails">Contribute on GitHub</a></li> </ul> </div> </div> <header id="page-header"> <div class="wrapper clearfix"> <nav id="feature-nav"> <div class="header-logo"> <a href="index.html" title="Guides home for v8.0.0 Guides">Guides</a> <span id="version-switcher" class="js-only"> <label for="version-switcher-select">Version: <span class="visibly-hidden">pick from the list to go to that Rails version's guides</span></label> <select id="version-switcher-select" class="guides-version"> <option value="https://edgeguides.rubyonrails.org/">Edge</option> <option value="https://guides.rubyonrails.org/v8.0/" selected>8.0</option> <option value="https://guides.rubyonrails.org/v7.2/">7.2</option> <option value="https://guides.rubyonrails.org/v7.1/">7.1</option> <option value="https://guides.rubyonrails.org/v7.0/">7.0</option> <option value="https://guides.rubyonrails.org/v6.1/">6.1</option> <option value="https://guides.rubyonrails.org/v6.0/">6.0</option> <option value="https://guides.rubyonrails.org/v5.2/">5.2</option> <option value="https://guides.rubyonrails.org/v5.1/">5.1</option> <option value="https://guides.rubyonrails.org/v5.0/">5.0</option> <option value="https://guides.rubyonrails.org/v4.2/">4.2</option> <option value="https://guides.rubyonrails.org/v4.1/">4.1</option> <option value="https://guides.rubyonrails.org/v4.0/">4.0</option> <option value="https://guides.rubyonrails.org/v3.2/">3.2</option> <option value="https://guides.rubyonrails.org/v3.1/">3.1</option> <option value="https://guides.rubyonrails.org/v3.0/">3.0</option> <option value="https://guides.rubyonrails.org/v2.3/">2.3</option> </select> </span> </div> <ul class="nav"> <li><a class="nav-item" id="home_nav" href="https://rubyonrails.org/">Home</a></li> <li class="guides-index guides-index-large"> <a href="index.html" id="guides-menu-button" data-aria-controls="guides" data-aria-expanded="false" class="guides-index-item nav-item">Guides Index</a> <div id="guides" class="clearfix" style="display: none;"> <hr /> <dl class="guides-section-container"> <div class="guides-section"> <dt>Start Here</dt> <dd><a href="getting_started.html">Getting Started with Rails</a></dd> </div> <div class="guides-section"> <dt>Models</dt> <dd><a href="active_record_basics.html">Active Record Basics</a></dd> <dd><a href="active_record_migrations.html">Active Record Migrations</a></dd> <dd><a href="active_record_validations.html">Active Record Validations</a></dd> <dd><a href="active_record_callbacks.html">Active Record Callbacks</a></dd> <dd><a href="association_basics.html">Active Record Associations</a></dd> <dd><a href="active_record_querying.html">Active Record Query Interface</a></dd> <dd><a href="active_model_basics.html">Active Model Basics</a></dd> </div> <div class="guides-section"> <dt>Views</dt> <dd><a href="action_view_overview.html">Action View Overview</a></dd> <dd><a href="layouts_and_rendering.html">Layouts and Rendering in Rails</a></dd> <dd><a href="action_view_helpers.html">Action View Helpers</a></dd> <dd><a href="form_helpers.html">Action View Form Helpers</a></dd> </div> <div class="guides-section"> <dt>Controllers</dt> <dd><a href="action_controller_overview.html">Action Controller Overview</a></dd> <dd><a href="routing.html">Rails Routing from the Outside In</a></dd> </div> <div class="guides-section"> <dt>Other Components</dt> <dd><a href="active_support_core_extensions.html">Active Support Core Extensions</a></dd> <dd><a href="action_mailer_basics.html">Action Mailer Basics</a></dd> <dd><a href="action_mailbox_basics.html">Action Mailbox Basics</a></dd> <dd><a href="action_text_overview.html">Action Text Overview</a></dd> <dd><a href="active_job_basics.html">Active Job Basics</a></dd> <dd><a href="active_storage_overview.html">Active Storage Overview</a></dd> <dd><a href="action_cable_overview.html">Action Cable Overview</a></dd> </div> <div class="guides-section"> <dt>Digging Deeper</dt> <dd><a href="i18n.html">Rails Internationalization (I18n) API</a></dd> <dd><a href="testing.html">Testing Rails Applications</a></dd> <dd><a href="security.html">Securing Rails Applications</a></dd> <dd><a href="error_reporting.html">Error Reporting in Rails Applications</a></dd> <dd><a href="debugging_rails_applications.html">Debugging Rails Applications</a></dd> <dd><a href="configuring.html">Configuring Rails Applications</a></dd> <dd><a href="command_line.html">The Rails Command Line</a></dd> <dd><a href="asset_pipeline.html">The Asset Pipeline</a></dd> <dd><a href="working_with_javascript_in_rails.html">Working with JavaScript in Rails</a></dd> <dd><a href="autoloading_and_reloading_constants.html">Autoloading and Reloading</a></dd> <dd><a href="caching_with_rails.html">Caching with Rails: An Overview</a></dd> <dd><a href="api_app.html">Using Rails for API-only Applications</a></dd> <dd><a href="tuning_performance_for_deployment.html">Tuning Performance for Deployment</a></dd> </div> <div class="guides-section"> <dt>Advanced Active Record</dt> <dd><a href="active_record_multiple_databases.html">Multiple Databases</a></dd> <dd><a href="active_record_composite_primary_keys.html">Composite Primary Keys</a></dd> </div> <div class="guides-section"> <dt>Extending Rails</dt> <dd><a href="rails_on_rack.html">Rails on Rack</a></dd> <dd><a href="generators.html">Creating and Customizing Rails Generators & Templates</a></dd> </div> <div class="guides-section"> <dt>Contributing</dt> <dd><a href="contributing_to_ruby_on_rails.html">Contributing to Ruby on Rails</a></dd> <dd><a href="api_documentation_guidelines.html">API Documentation Guidelines</a></dd> <dd><a href="ruby_on_rails_guides_guidelines.html">Guides Guidelines</a></dd> <dd><a href="development_dependencies_install.html">Installing Rails Core Development Dependencies</a></dd> </div> <div class="guides-section"> <dt>Policies</dt> <dd><a href="maintenance_policy.html">Maintenance Policy</a></dd> </div> <div class="guides-section"> <dt>Release Notes</dt> <dd><a href="upgrading_ruby_on_rails.html">Upgrading Ruby on Rails</a></dd> <dd><a href="7_2_release_notes.html">Version 7.2 - August 2024</a></dd> <dd><a href="7_1_release_notes.html">Version 7.1 - October 2023</a></dd> <dd><a href="7_0_release_notes.html">Version 7.0 - December 2021</a></dd> <dd><a href="6_1_release_notes.html">Version 6.1 - December 2020</a></dd> <dd><a href="6_0_release_notes.html">Version 6.0 - August 2019</a></dd> <dd><a href="5_2_release_notes.html">Version 5.2 - April 2018</a></dd> <dd><a href="5_1_release_notes.html">Version 5.1 - April 2017</a></dd> <dd><a href="5_0_release_notes.html">Version 5.0 - June 2016</a></dd> <dd><a href="4_2_release_notes.html">Version 4.2 - December 2014</a></dd> <dd><a href="4_1_release_notes.html">Version 4.1 - April 2014</a></dd> <dd><a href="4_0_release_notes.html">Version 4.0 - June 2013</a></dd> <dd><a href="3_2_release_notes.html">Version 3.2 - January 2012</a></dd> <dd><a href="3_1_release_notes.html">Version 3.1 - August 2011</a></dd> <dd><a href="3_0_release_notes.html">Version 3.0 - August 2010</a></dd> <dd><a href="2_3_release_notes.html">Version 2.3 - March 2009</a></dd> <dd><a href="2_2_release_notes.html">Version 2.2 - November 2008</a></dd> </div> </dl> </div> </li> <li><a class="nav-item" href="contributing_to_ruby_on_rails.html">Contribute</a></li> <li class="guides-index guides-index-small js-only"> <label for="guides-selector"> Navigate to a guide: </label> <select id="guides-selector" class="guides-index-item nav-item"> <option value="index.html">Guides Index</option> <optgroup label="Start Here"> <option value="getting_started.html">Getting Started with Rails</option> </optgroup> <optgroup label="Models"> <option value="active_record_basics.html">Active Record Basics</option> <option value="active_record_migrations.html">Active Record Migrations</option> <option value="active_record_validations.html">Active Record Validations</option> <option value="active_record_callbacks.html">Active Record Callbacks</option> <option value="association_basics.html">Active Record Associations</option> <option value="active_record_querying.html">Active Record Query Interface</option> <option value="active_model_basics.html">Active Model Basics</option> </optgroup> <optgroup label="Views"> <option value="action_view_overview.html">Action View Overview</option> <option value="layouts_and_rendering.html">Layouts and Rendering in Rails</option> <option value="action_view_helpers.html">Action View Helpers</option> <option value="form_helpers.html">Action View Form Helpers</option> </optgroup> <optgroup label="Controllers"> <option value="action_controller_overview.html">Action Controller Overview</option> <option value="routing.html">Rails Routing from the Outside In</option> </optgroup> <optgroup label="Other Components"> <option value="active_support_core_extensions.html">Active Support Core Extensions</option> <option value="action_mailer_basics.html">Action Mailer Basics</option> <option value="action_mailbox_basics.html">Action Mailbox Basics</option> <option value="action_text_overview.html">Action Text Overview</option> <option value="active_job_basics.html">Active Job Basics</option> <option value="active_storage_overview.html">Active Storage Overview</option> <option value="action_cable_overview.html">Action Cable Overview</option> </optgroup> <optgroup label="Digging Deeper"> <option value="i18n.html">Rails Internationalization (I18n) API</option> <option value="testing.html">Testing Rails Applications</option> <option value="security.html">Securing Rails Applications</option> <option value="error_reporting.html">Error Reporting in Rails Applications</option> <option value="debugging_rails_applications.html">Debugging Rails Applications</option> <option value="configuring.html">Configuring Rails Applications</option> <option value="command_line.html">The Rails Command Line</option> <option value="asset_pipeline.html">The Asset Pipeline</option> <option value="working_with_javascript_in_rails.html">Working with JavaScript in Rails</option> <option value="autoloading_and_reloading_constants.html">Autoloading and Reloading</option> <option value="caching_with_rails.html">Caching with Rails: An Overview</option> <option value="api_app.html">Using Rails for API-only Applications</option> <option value="tuning_performance_for_deployment.html">Tuning Performance for Deployment</option> </optgroup> <optgroup label="Advanced Active Record"> <option value="active_record_multiple_databases.html">Multiple Databases</option> <option value="active_record_composite_primary_keys.html">Composite Primary Keys</option> </optgroup> <optgroup label="Extending Rails"> <option value="rails_on_rack.html">Rails on Rack</option> <option value="generators.html">Creating and Customizing Rails Generators & Templates</option> </optgroup> <optgroup label="Contributing"> <option value="contributing_to_ruby_on_rails.html">Contributing to Ruby on Rails</option> <option value="api_documentation_guidelines.html">API Documentation Guidelines</option> <option value="ruby_on_rails_guides_guidelines.html">Guides Guidelines</option> <option value="development_dependencies_install.html">Installing Rails Core Development Dependencies</option> </optgroup> <optgroup label="Policies"> <option value="maintenance_policy.html">Maintenance Policy</option> </optgroup> <optgroup label="Release Notes"> <option value="upgrading_ruby_on_rails.html">Upgrading Ruby on Rails</option> <option value="7_2_release_notes.html">Version 7.2 - August 2024</option> <option value="7_1_release_notes.html">Version 7.1 - October 2023</option> <option value="7_0_release_notes.html">Version 7.0 - December 2021</option> <option value="6_1_release_notes.html">Version 6.1 - December 2020</option> <option value="6_0_release_notes.html">Version 6.0 - August 2019</option> <option value="5_2_release_notes.html">Version 5.2 - April 2018</option> <option value="5_1_release_notes.html">Version 5.1 - April 2017</option> <option value="5_0_release_notes.html">Version 5.0 - June 2016</option> <option value="4_2_release_notes.html">Version 4.2 - December 2014</option> <option value="4_1_release_notes.html">Version 4.1 - April 2014</option> <option value="4_0_release_notes.html">Version 4.0 - June 2013</option> <option value="3_2_release_notes.html">Version 3.2 - January 2012</option> <option value="3_1_release_notes.html">Version 3.1 - August 2011</option> <option value="3_0_release_notes.html">Version 3.0 - August 2010</option> <option value="2_3_release_notes.html">Version 2.3 - March 2009</option> <option value="2_2_release_notes.html">Version 2.2 - November 2008</option> </optgroup> </select> </li> </ul> </nav> </div> </header> <hr class="hide" /> <main id="main"> <article> <header id="feature"> <div class="wrapper"> <h1>Ruby on Rails Guides Guidelines</h1><p>This guide documents guidelines for writing Ruby on Rails Guides. This guide follows itself in a graceful loop, serving itself as an example.</p><p>After reading this guide, you will know:</p> <ul> <li>About the conventions to be used in Rails documentation.</li> <li>How to generate guides locally.</li> </ul> <nav id="column-side" aria-label="Chapter" class="guide-index" data-turbo="false"> <a id="chapter-nav-skip-link" href="#article-body" class="skip-link"> Skip to article body </a> <h2 class="chapter"> <picture aria-hidden="true">  <source srcset="images/icon_book-close-bookmark-1-wht.svg" media="(prefers-color-scheme: dark)" /> <img src="images/icon_book-close-bookmark-1.svg" alt="Chapter Icon" /> </picture> Chapters </h2> <ol class="chapters"> <li><a href="#markdown">Markdown</a></li> <li><a href="#prologue">Prologue</a></li> <li><a href="#headings">Headings</a></li> <li><a href="#notes-tips-and-warnings">Notes, Tips and Warnings</a> <ul> <li><a href="#note">NOTE</a></li> <li><a href="#tip">TIP</a></li> <li><a href="#warning">WARNING</a></li> </ul></li> <li><a href="#links">Links</a> <ul> <li><a href="#linking-to-the-api">Linking to the API</a></li> </ul></li> <li><a href="#column-wrapping">Column Wrapping</a></li> <li><a href="#api-documentation-guidelines">API Documentation Guidelines</a></li> <li><a href="#html-guides">HTML Guides</a> <ul> <li><a href="#html-guides-generation">Generation</a></li> <li><a href="#validation">Validation</a></li> </ul></li> <li><a href="#kindle-guides">Kindle Guides</a> <ul> <li><a href="#kindle-guides-generation">Generation</a></li> </ul></li> </ol> </nav> </div> </header> <div class="wrapper"> <div id="column-main"> <section id="article-body"> <h2 id="markdown"><a class="anchorlink" href="#markdown" data-turbo="false"><span>1</span> Markdown</a></h2><p>Guides are written in <a href="https://help.github.com/articles/github-flavored-markdown">GitHub Flavored Markdown</a>. There is comprehensive <a href="https://daringfireball.net/projects/markdown/syntax">documentation for Markdown</a>, as well as a <a href="https://daringfireball.net/projects/markdown/basics">cheatsheet</a>.</p><h2 id="prologue"><a class="anchorlink" href="#prologue" data-turbo="false"><span>2</span> Prologue</a></h2><p>Each guide should start with motivational text at the top (that's the little introduction in the blue area). The prologue should tell the reader what the guide is about, and what they will learn. As an example, see the <a href="routing.html">Routing Guide</a>.</p><h2 id="headings"><a class="anchorlink" href="#headings" data-turbo="false"><span>3</span> Headings</a></h2><p>The title of every guide uses an <code>h1</code> heading; guide sections use <code>h2</code> headings; subsections use <code>h3</code> headings; etc. Note that the generated HTML output will use heading tags starting with <code><h2></code>.</p><div class="interstitial code"> <pre><code class="highlight markdown"><span class="gu">Guide Title =========== </span> <span class="gh">Section ------- </span> <span class="gu">### Sub Section</span> </code></pre> <button class="clipboard-button" data-clipboard-text="Guide Title =========== Section ------- ### Sub Section ">Copy</button> </div> <p>When writing headings, capitalize all words except for prepositions, conjunctions, internal articles, and forms of the verb "to be":</p><div class="interstitial code"> <pre><code class="highlight markdown"><span class="gu">#### Assertions and Testing Jobs inside Components</span> <span class="gu">#### Middleware Stack is an Array</span> <span class="gu">#### When are Objects Saved?</span> </code></pre> <button class="clipboard-button" data-clipboard-text="#### Assertions and Testing Jobs inside Components #### Middleware Stack is an Array #### When are Objects Saved? ">Copy</button> </div> <p>Use the same inline formatting as regular text:</p><div class="interstitial code"> <pre><code class="highlight markdown"><span class="gu">##### The `:content_type` Option</span> </code></pre> <button class="clipboard-button" data-clipboard-text="##### The `:content_type` Option ">Copy</button> </div> <h2 id="notes-tips-and-warnings"><a class="anchorlink" href="#notes-tips-and-warnings" data-turbo="false"><span>4</span> Notes, Tips and Warnings</a></h2><p>Sometimes a paragraph deserves a little more attention. For example, to clarify a common misunderstanding or warn about something that could break an application.</p><p>To highlight a paragraph, prefix it with <code>NOTE:</code>, <code>TIP:</code> or <code>WARNING:</code>:</p><div class="interstitial code"> <pre><code class="highlight markdown">NOTE: Use <span class="sb">`NOTE`</span>, <span class="sb">`TIP`</span> or <span class="sb">`WARNING`</span> to highlight a paragraph. </code></pre> <button class="clipboard-button" data-clipboard-text="NOTE: Use `NOTE`, `TIP` or `WARNING` to highlight a paragraph. ">Copy</button> </div> <p>This will wrap the paragraph in a special container resulting in the following:</p><div class="interstitial note"><p>Use <code>NOTE</code>, <code>TIP</code> or <code>WARNING</code> to highlight a paragraph.</p></div><h3 id="note"><a class="anchorlink" href="#note" data-turbo="false"><span>4.1</span> NOTE</a></h3><p>Use <code>NOTE</code> to highlight something in relation to the subject and the context. Reading it will help your understanding of that subject or context, or clarify an important item.</p><p>For example, a section describing locale files could have the following <code>NOTE</code>:</p><div class="interstitial note"><p>You need to restart the server when you add new locale files.</p></div><h3 id="tip"><a class="anchorlink" href="#tip" data-turbo="false"><span>4.2</span> TIP</a></h3><p>A <code>TIP</code> is just an additional bit of information regarding the subject, but not necessarily relevant to the understanding. It can point you to another guide or website:</p><div class="interstitial info"><p>To learn more about routing, see <a href="routing.html">Rails Routing from the Outside In</a>.</p></div><p>Or show a helpful command to see more options to dig deeper:</p><div class="interstitial info"><p>For further help with generators, run <code>bin/rails generate --help</code>.</p></div><h3 id="warning"><a class="anchorlink" href="#warning" data-turbo="false"><span>4.3</span> WARNING</a></h3><p>Use <code>WARNING</code> for things to avoid that could break the application:</p><div class="interstitial warning"><p>Refrain from using methods like <code>update</code>, <code>save</code>, or any other methods that cause side effects on the object within your callback methods.</p></div><p>Or warn about things that could compromise your application's security.</p><div class="interstitial warning"><p>Keep your master key safe. Do not commit your master key.</p></div><h2 id="links"><a class="anchorlink" href="#links" data-turbo="false"><span>5</span> Links</a></h2><p>Use descriptive links and avoid "here" and "more" links:</p><div class="interstitial code"> <pre><code class="highlight markdown"><span class="gh"># BAD</span> See the Rails Internationalization (I18n) API documentation for <span class="p">[</span><span class="nv">more details</span><span class="p">](</span><span class="sx">i18n.html</span><span class="p">)</span>. <span class="gh"># GOOD</span> See the <span class="p">[</span><span class="nv">Rails Internationalization (I18n) API documentation</span><span class="p">](</span><span class="sx">i18n.html</span><span class="p">)</span> for more details. </code></pre> <button class="clipboard-button" data-clipboard-text="# BAD See the Rails Internationalization (I18n) API documentation for [more details](i18n.html). # GOOD See the [Rails Internationalization (I18n) API documentation](i18n.html) for more details. ">Copy</button> </div> <p>Use descriptive links for internal links as well:</p><div class="interstitial code"> <pre><code class="highlight markdown"><span class="gh"># BAD</span> We will cover this <span class="p">[</span><span class="nv">below</span><span class="p">](</span><span class="sx">#multiple-callback-conditions</span><span class="p">)</span>. <span class="gh"># GOOD</span> We will cover this in the <span class="p">[</span><span class="nv">multiple callback conditions section</span><span class="p">](</span><span class="sx">#multiple-callback-conditions</span><span class="p">)</span> shown below. </code></pre> <button class="clipboard-button" data-clipboard-text="# BAD We will cover this [below](#multiple-callback-conditions). # GOOD We will cover this in the [multiple callback conditions section](#multiple-callback-conditions) shown below. ">Copy</button> </div> <h3 id="linking-to-the-api"><a class="anchorlink" href="#linking-to-the-api" data-turbo="false"><span>5.1</span> Linking to the API</a></h3><p>Links to the API (<code>api.rubyonrails.org</code>) are processed by the guides generator in the following manner:</p><p>Links that include a release tag are left untouched. For example</p><div class="interstitial code"> <pre><code class="highlight plaintext">https://api.rubyonrails.org/v5.0.1/classes/ActiveRecord/Attributes/ClassMethods.html </code></pre> <button class="clipboard-button" data-clipboard-text="https://api.rubyonrails.org/v5.0.1/classes/ActiveRecord/Attributes/ClassMethods.html ">Copy</button> </div> <p>is not modified.</p><p>Please use these in release notes, since they should point to the corresponding version no matter the target being generated.</p><p>If the link does not include a release tag and edge guides are being generated, the domain is replaced by <code>edgeapi.rubyonrails.org</code>. For example,</p><div class="interstitial code"> <pre><code class="highlight plaintext">https://api.rubyonrails.org/classes/ActionDispatch/Response.html </code></pre> <button class="clipboard-button" data-clipboard-text="https://api.rubyonrails.org/classes/ActionDispatch/Response.html ">Copy</button> </div> <p>becomes</p><div class="interstitial code"> <pre><code class="highlight plaintext">https://edgeapi.rubyonrails.org/classes/ActionDispatch/Response.html </code></pre> <button class="clipboard-button" data-clipboard-text="https://edgeapi.rubyonrails.org/classes/ActionDispatch/Response.html ">Copy</button> </div> <p>If the link does not include a release tag and release guides are being generated, the Rails version is injected. For example, if we are generating the guides for v5.1.0 the link</p><div class="interstitial code"> <pre><code class="highlight plaintext">https://api.rubyonrails.org/classes/ActionDispatch/Response.html </code></pre> <button class="clipboard-button" data-clipboard-text="https://api.rubyonrails.org/classes/ActionDispatch/Response.html ">Copy</button> </div> <p>becomes</p><div class="interstitial code"> <pre><code class="highlight plaintext">https://api.rubyonrails.org/v5.1.0/classes/ActionDispatch/Response.html </code></pre> <button class="clipboard-button" data-clipboard-text="https://api.rubyonrails.org/v5.1.0/classes/ActionDispatch/Response.html ">Copy</button> </div> <p>Please don't link to <code>edgeapi.rubyonrails.org</code> manually.</p><h2 id="column-wrapping"><a class="anchorlink" href="#column-wrapping" data-turbo="false"><span>6</span> Column Wrapping</a></h2><p>Do not reformat old guides just to wrap columns. But new sections and guides should wrap at 80 columns.</p><h2 id="api-documentation-guidelines"><a class="anchorlink" href="#api-documentation-guidelines" data-turbo="false"><span>7</span> API Documentation Guidelines</a></h2><p>The guides and the API should be coherent and consistent where appropriate. In particular, these sections of the <a href="api_documentation_guidelines.html">API Documentation Guidelines</a> also apply to the guides:</p> <ul> <li><a href="api_documentation_guidelines.html#wording">Wording</a></li> <li><a href="api_documentation_guidelines.html#american-english">English</a></li> <li><a href="api_documentation_guidelines.html#example-code">Example Code</a></li> <li><a href="api_documentation_guidelines.html#file-names">Filenames</a></li> <li><a href="api_documentation_guidelines.html#fonts">Fonts</a></li> </ul> <h2 id="html-guides"><a class="anchorlink" href="#html-guides" data-turbo="false"><span>8</span> HTML Guides</a></h2><p>Before generating the guides, make sure that you have the latest version of Bundler installed on your system. To install the latest version of Bundler, run <code>gem install bundler</code>.</p><p>If you already have Bundler installed, you can update with <code>gem update bundler</code>.</p><h3 id="html-guides-generation"><a class="anchorlink" href="#html-guides-generation" data-turbo="false"><span>8.1</span> Generation</a></h3><p>To generate all the guides, just <code>cd</code> into the <code>guides</code> directory, run <code>bundle install</code>, and execute:</p><div class="interstitial code"> <pre><code class="highlight console"><span class="gp">$</span><span class="w"> </span><span class="nb">bundle exec rake </span>guides:generate </code></pre> <button class="clipboard-button" data-clipboard-text="bundle exec rake guides:generate ">Copy</button> </div> <p>or</p><div class="interstitial code"> <pre><code class="highlight console"><span class="gp">$</span><span class="w"> </span><span class="nb">bundle exec rake </span>guides:generate:html </code></pre> <button class="clipboard-button" data-clipboard-text="bundle exec rake guides:generate:html ">Copy</button> </div> <p>Resulting HTML files can be found in the <code>./output</code> directory.</p><p>To process <code>my_guide.md</code> and nothing else use the <code>ONLY</code> environment variable:</p><div class="interstitial code"> <pre><code class="highlight console"><span class="gp">$</span><span class="w"> </span><span class="nb">touch </span>my_guide.md <span class="gp">$</span><span class="w"> </span><span class="nb">bundle exec rake </span>guides:generate <span class="nv">ONLY</span><span class="o">=</span>my_guide </code></pre> <button class="clipboard-button" data-clipboard-text="touch my_guide.md bundle exec rake guides:generate ONLY=my_guide ">Copy</button> </div> <p>By default, guides that have not been modified are not processed, so <code>ONLY</code> is rarely needed in practice.</p><p>To force processing all the guides, pass <code>ALL=1</code>.</p><p>If you want to generate guides in a language other than English, you can keep them in a separate directory under <code>source</code> (e.g. <code>source/es</code>) and use the <code>GUIDES_LANGUAGE</code> environment variable:</p><div class="interstitial code"> <pre><code class="highlight console"><span class="gp">$</span><span class="w"> </span><span class="nb">bundle exec rake </span>guides:generate <span class="nv">GUIDES_LANGUAGE</span><span class="o">=</span>es </code></pre> <button class="clipboard-button" data-clipboard-text="bundle exec rake guides:generate GUIDES_LANGUAGE=es ">Copy</button> </div> <p>If you want to see all the environment variables you can use to configure the generation script just run:</p><div class="interstitial code"> <pre><code class="highlight console"><span class="gp">$</span><span class="w"> </span><span class="nb">rake</span> </code></pre> <button class="clipboard-button" data-clipboard-text="rake ">Copy</button> </div> <h3 id="validation"><a class="anchorlink" href="#validation" data-turbo="false"><span>8.2</span> Validation</a></h3><p>Please validate the generated HTML with:</p><div class="interstitial code"> <pre><code class="highlight console"><span class="gp">$</span><span class="w"> </span><span class="nb">bundle exec rake </span>guides:validate </code></pre> <button class="clipboard-button" data-clipboard-text="bundle exec rake guides:validate ">Copy</button> </div> <p>Particularly, titles get an ID generated from their content and this often leads to duplicates.</p><h2 id="kindle-guides"><a class="anchorlink" href="#kindle-guides" data-turbo="false"><span>9</span> Kindle Guides</a></h2><h3 id="kindle-guides-generation"><a class="anchorlink" href="#kindle-guides-generation" data-turbo="false"><span>9.1</span> Generation</a></h3><p>To generate guides for the Kindle, use the following rake task:</p><div class="interstitial code"> <pre><code class="highlight console"><span class="gp">$</span><span class="w"> </span><span class="nb">bundle exec rake </span>guides:generate:kindle </code></pre> <button class="clipboard-button" data-clipboard-text="bundle exec rake guides:generate:kindle ">Copy</button> </div> </section> <hr> <footer aria-labelledby="heading-feedback" role="region"> <h2 id="heading-feedback">Feedback</h2> <p> You're encouraged to help improve the quality of this guide. </p> <p> Please contribute if you see any typos or factual errors. To get started, you can read our <a href="https://edgeguides.rubyonrails.org/contributing_to_ruby_on_rails.html#contributing-to-the-rails-documentation">documentation contributions</a> section. </p> <p> You may also find incomplete content or stuff that is not up to date. Please do add any missing documentation for main. Make sure to check <a href="https://edgeguides.rubyonrails.org">Edge Guides</a> first to verify if the issues are already fixed or not on the main branch. Check the <a href="ruby_on_rails_guides_guidelines.html">Ruby on Rails Guides Guidelines</a> for style and conventions. </p> <p> If for whatever reason you spot something to fix but cannot patch it yourself, please <a href="https://github.com/rails/rails/issues">open an issue</a>. </p> <p>And last but not least, any kind of discussion regarding Ruby on Rails documentation is very welcome on the <a href="https://discuss.rubyonrails.org/c/rubyonrails-docs">official Ruby on Rails Forum</a>. </p> </footer> </div> </article> </main> <hr class="hide" /> <footer id="complementary"> <div class="wrapper"> <p>This work is licensed under a <a href="https://creativecommons.org/licenses/by-sa/4.0/">Creative Commons Attribution-ShareAlike 4.0 International</a> License</p> <p>"Rails", "Ruby on Rails", and the Rails logo are trademarks of David Heinemeier Hansson. All rights reserved.</p> </div> </footer> <a href="#main-skip-link" class="back-to-top" data-turbo="false"><span class="visibly-hidden">Back to top</span></a> </body> </html>

CINXE.COM

Ruby on Rails Guides Guidelines — Ruby on Rails Guides