Ruby on Rails 指南指导方针 — Ruby on Rails Guides

每篇文章的开头要有介绍性文字（蓝色区域中的简短介绍）。序言应该告诉读者文章的主旨，以及能让读者学到什么。可以以Rails 路由全解为例。

每篇文章的标题使用 h1 标签，文章中的小节使用 h2 标签，子节使用 h3 标签，以此类推。注意，生成的 HTML 从 <h2> 标签开始。

Guide Title
===========

Section
-------

### Sub Section

标题中除了介词、连词、冠词和“to be”这种形式的动词之外，每个词的首字母大写：

#### Middleware Stack is an Array
#### When are Objects Saved?

行内格式与正文一样：

##### The `:content_type` Option

指南生成程序使用下述方式处理指向 API（api.rubyonrails.org）的链接。

包含版本号的链接原封不动。例如，下述链接不做修改：

http://api.rubyonrails.org/v5.0.1/classes/ActiveRecord/Attributes/ClassMethods.html

请在发布记中使用这种链接，因为不管生成哪个版本的指南，发布记中的链接不应该变。

如果链接中没有版本号，而且生成的是最新开发版的指南，域名会替换成 edgeapi.rubyonrails.org。例如：

http://api.rubyonrails.org/classes/ActionDispatch/Response.html

会变成：

http://edgeapi.rubyonrails.org/classes/ActionDispatch/Response.html

如果链接中没有版本号，而生成的是某个版本的指南，会在链接中插入版本号。例如，生成 v5.1.0 的指南时，下述链接：

http://api.rubyonrails.org/classes/ActionDispatch/Response.html

会变成：

http://api.rubyonrails.org/v5.1.0/classes/ActionDispatch/Response.html

请勿直接链接到 edgeapi.rubyonrails.org。

指南和 API 应该连贯一致。尤其是API 文档指导方针中的下述几节，同样适用于指南：

在生成指南之前，先确保你的系统中安装了 Bundler 的最新版。写作本文时，要在你的设备中安装 Bundler 1.3.5 或以上版本。

安装最新版 Bundler 的方法是，执行 gem install bundler 命令。

若想生成全部指南，进入 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 是从标题的内容中生成的，往往会重复。生成指南时请设定 WARNINGS=1，监测重复的 ID。提醒消息中有建议的解决方案。

如果想生成 Kindle 版指南，使用下述 Rake 任务：

$ bundle exec rake guides:generate:kindle

我们鼓励您帮助提高本指南的质量。

如果看到如何错字或错误，请反馈给我们。您可以阅读我们的文档贡献指南。

您还可能会发现内容不完整或不是最新版本。请添加缺失文档到 master 分支。请先确认 Edge Guides 是否已经修复。关于用语约定，请查看Ruby on Rails 指南指导。

无论什么原因，如果你发现了问题但无法修补它，请创建 issue。

最后，欢迎到 rubyonrails-docs 邮件列表参与任何有关 Ruby on Rails 文档的讨论。