1. Markdown
指南采用 GitHub Flavored Markdown 编写。有全面的 Markdown 文档，以及一份 备忘单。
2. 序言
每份指南都应以顶部的激励性文本开头（即蓝色区域的小引言）。序言应告诉读者本指南的主题以及他们将学到什么。例如，请参阅路由指南。
3. 标题
每份指南的标题都使用 h1 标题；指南章节使用 h2 标题；小节使用 h3 标题；等等。请注意，生成的 HTML 输出将使用从 <h2> 开始的标题标签。
Guide Title
===========
Section
-------
### Sub Section
撰写标题时，除介词、连词、内部冠词和动词“to be”的各种形式外，所有单词的首字母均大写
#### Assertions and Testing Jobs inside Components
#### Middleware Stack is an Array
#### When are Objects Saved?
使用与常规文本相同的内联格式
##### The `:content_type` Option
4. 注意、提示和警告
有时，一个段落值得更多关注。例如，为了澄清常见的误解或警告可能破坏应用程序的事情。
要突出显示某个段落，请在其前面加上 NOTE:、TIP: 或 WARNING:
NOTE: Use `NOTE`, `TIP` or `WARNING` to highlight a paragraph.
这将把段落包装在一个特殊的容器中，结果如下
使用 NOTE、TIP 或 WARNING 来突出显示一个段落。
4.1. 注意
使用 NOTE 来突出显示与主题和上下文相关的内容。阅读它将有助于您理解该主题或上下文，或澄清重要事项。
例如，描述区域设置文件的部分可以包含以下 NOTE
添加新的区域设置文件时，需要重新启动服务器。
4.2. 提示
TIP 只是关于主题的额外信息，但不一定与理解相关。它可以指向另一份指南或网站
要了解有关路由的更多信息，请参阅 从外部理解 Rails 路由。
或者显示一条有用的命令，以查看更多选项以深入挖掘
有关生成器的更多帮助，请运行 bin/rails generate --help。
4.3. 警告
使用 WARNING 表示应避免的可能破坏应用程序的事项
避免在回调方法中使用 update、save 或任何其他会引起对象副作用的方法。
或警告可能危及应用程序安全性的事项。
妥善保管您的主密钥。请勿提交您的主密钥。
5. 链接
使用描述性链接，避免“此处”和“更多”链接
# 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.
内部链接也使用描述性链接
# 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.
5.1. 链接到 API
指向 API (api.rubyonrails.org) 的链接由指南生成器按以下方式处理
包含发布标签的链接保持不变。例如
https://api.rubyonrails.cn/v5.0.1/classes/ActiveRecord/Attributes/ClassMethods.html
未被修改。
请在发布说明中使用这些链接，因为它们应该指向相应的版本，无论生成的目标是什么。
如果链接不包含发布标签，并且正在生成 Edge 指南，则域名将被替换为 edgeapi.rubyonrails.org。例如，
https://api.rubyonrails.cn/classes/ActionDispatch/Response.html
变为：
https://api.rubyonrails.cn/classes/ActionDispatch/Response.html
如果链接不包含发布标签，并且正在生成发布指南，则会注入 Rails 版本。例如，如果我们要生成 v5.1.0 的指南，则链接
https://api.rubyonrails.cn/classes/ActionDispatch/Response.html
变为：
https://api.rubyonrails.cn/v5.1.0/classes/ActionDispatch/Response.html
请不要手动链接到 edgeapi.rubyonrails.org。
6. 列换行
不要仅仅为了列换行而重新格式化旧指南。但新章节和指南应在 80 列处换行。
7. API 文档准则
指南和 API 在适当时应保持连贯和一致。特别是，API 文档准则的这些部分也适用于指南
8. HTML 指南
在生成指南之前，请确保您的系统上已安装最新版本的 Bundler。要安装最新版本的 Bundler，请运行 gem install bundler。
如果已安装 Bundler，可以使用 gem update bundler 进行更新。
8.1. 生成
要生成所有指南，只需 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
8.2. 验证
请使用以下命令验证生成的 HTML
$ bundle exec rake guides:validate
特别是，标题会根据其内容生成一个 ID，这通常会导致重复。
9. Kindle 指南
9.1. 生成
要生成 Kindle 指南，请使用以下 rake 任务
$ bundle exec rake guides:generate:kindle