1 Markdown
指南使用 GitHub Flavored Markdown 编写。有关于 Markdown 的全面 文档，以及 速查表。
2 序言
每个指南都应在顶部以激励性文字开头（即蓝色区域中的简短介绍）。序言应告诉读者本指南的主题，以及他们将学到什么。例如，请参见 路由指南。
3 标题
每个指南的标题使用 h1 标题；指南部分使用 h2 标题；小节使用 h3 标题；依此类推。请注意，生成的 HTML 输出将使用从 <h2> 开始的标题标签。
Guide Title
===========
Section
-------
### Sub Section
编写标题时，所有单词都应大写，但介词、连词、内部冠词和“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 链接
使用描述性链接，避免使用“here”和“more”链接
# 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.net.cn/v5.0.1/classes/ActiveRecord/Attributes/ClassMethods.html
不会被修改。
请在发行说明中使用这些链接，因为无论目标是什么，它们都应指向对应版本。
如果链接未包含发行版标签，并且正在生成 Edge 指南，则该域将被替换为 edgeapi.rubyonrails.org。例如，
https://api.rubyonrails.net.cn/classes/ActionDispatch/Response.html
将变为
https://api.rubyonrails.net.cn/classes/ActionDispatch/Response.html
如果链接未包含发行版标签，并且正在生成发行版指南，则将注入 Rails 版本。例如，如果我们正在为 v5.1.0 生成指南，则链接
https://api.rubyonrails.net.cn/classes/ActionDispatch/Response.html
将变为
https://api.rubyonrails.net.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