ガイドはGitHub Flavored Markdown で書かれています。まとまったMarkdownドキュメントとチートシートがあります。
ガイドの冒頭には、読者の開発意欲を高めるような文を置いてください。ガイドの青い部分がこれに該当します。プロローグでは、そのガイドの概要と、ガイドで学ぶ項目について記載してください。例についてはルーティングガイドを参照してください。
ガイドのタイトルにはh1、ガイドのセクション見出しにはh2、ガイドのサブセクション見出しにはh3をそれぞれ使ってください。なお、実際に生成されるHTMLの見出しは<h2>から始まります。
ガイドのタイトル =========== セクション ------- ### サブセクション
冠詞、前置詞、接続詞、be動詞以外の単語は冒頭を大文字にします。
#### Middlewareスタックは配列 #### オブジェクトが保存されるタイミング
通常のテキストと同じタイポグラフィをお使いください。
##### `:content_type`オプション
APIサイト（api.rubyonrails.org）へのリンクは、以下の方法を用いてガイドのジェネレータで処理されます。
リリース番号（v5.0.1など）タグを含むリンクに対しては何も処理を行いません（例↓）。
http://api.rubyonrails.org/v5.0.1/classes/ActiveRecord/Attributes/ClassMethods.html
上は変更されません。
リリースノートではこの書式でリンクを書いてください。今後どんな対象が生成されても、リリースノートに対応したバージョンを指すようにすべきです。
リンクにリリース番号タグが含まれていない場合やedgeガイドが生成される場合は、ドメイン名の部分がedgeapi.rubyonrails.orgに置き換えられます（例↓）。
http://api.rubyonrails.org/classes/ActionDispatch/Response.html
上は以下に置き換えられます。
http://edgeapi.rubyonrails.org/classes/ActionDispatch/Response.html
リンクにリリース番号タグが含まれていない場合や、正規版のガイドが生成される場合は、Railsのバージョン番号が挿入されます。たとえば、Rails 5.1.0向けのガイドを生成すると以下のようなリンクになります。
http://api.rubyonrails.org/classes/ActionDispatch/Response.html
上は以下に置き換えられます。
http://api.rubyonrails.org/v5.1.0/classes/ActionDispatch/Response.html
edgeapi.rubyonrails.orgには手動でリンクしないでください。
古いガイドの行を折り返すためだけの目的で再フォーマットしないでください。ただし、新しいセクションとガイドは80文字目で折り返す必要があります。
ガイドとAPIは、必要な箇所が互いに首尾一貫している必要があります。APIドキュメント作成ガイドラインの以下のセクションを参照してください
上記のガイドラインは、ガイドについても適用されます。
ガイドを生成する前に、システムに最新のBundlerがインストールされていることを確認してください。最新のBundlerをインストールするにはgem install bundlerコマンドを実行してください。
Bundlerを既にインストールしている場合は、gem update bundlerで最新のBundlerに更新できます。
すべてのガイドを生成するには、cdコマンドでguidesディレクトリに移動し、bundle installを実行してから以下のいずれかを実行します。
$ bundle exec rake guides:generate
または
$ bundle exec rake guides:generate:html
生成されたHTMLファイルは、./outputディレクトリに配置されます。
my_guide.mdファイルだけを生成したい場合は環境変数ONLYに設定します。
$ touch my_guide.md $ bundle exec rake guides:generate ONLY=my_guide
デフォルトでは、変更のないガイドは生成がスキップされるので、ONLYを使う機会はあまりないと思われます。
すべてのガイドを強制的に生成するにはALL=1を指定します。
英語以外の言語向けに生成を行いたい場合は、sourceディレクトリの下にたとえばsource/esのようにその言語用のディレクトリを作成し、GUIDES_LANGUAGE環境変数を設定します。
$ bundle exec rake guides:generate GUIDES_LANGUAGE=es
生成スクリプトの設定に使える環境変数をすべて知りたい場合は、単に以下を実行してください。
$ rake
生成されたHTMLをバリデーション（検証）するには以下を実行します。
$ bundle exec rake guides:validate
特に、タイトルを元にIDが生成される関係上、タイトルでの重複が生じやすくなっています。
Kindle向けにガイドを生成するには、以下のrakeタスクを実行します。
$ bundle exec rake guides:generate:kindle
Railsガイドは GitHub の yasslab/railsguides.jp で管理・公開されております。本ガイドを読んで気になる文章や間違ったコードを見かけたら、気軽に Pull Request を出して頂けると嬉しいです。Pull Request の送り方については GitHub の README をご参照ください。
原著における間違いを見つけたら『Rails のドキュメントに貢献する』を参考にしながらぜひ Rails コミュニティに貢献してみてください 🛠💨✨
本ガイドの品質向上に向けて、皆さまのご協力が得られれば嬉しいです。
Railsガイド運営チーム (@RailsGuidesJP)
Railsガイドは下記の協賛企業から継続的な支援を受けています。支援・協賛にご興味あれば協賛プランからお問い合わせいただけると嬉しいです。
