Ruby on Rails指南指南

1 Markdown

每个指南应以顶部的动机性文本开始（即蓝色区域中的简介）。序言应告诉读者指南的内容以及他们将学到什么。例如，参见路由指南。

每个指南的标题使用h1标题；指南的章节使用h2标题；子章节使用h3标题；等等。请注意，生成的HTML输出将使用以<h2>开头的标题标签。

指南标题
===========

章节
-------

### 子章节

在编写标题时，除了介词、连词、内部冠词和动词“to be”的形式外，所有单词都要大写：

#### 在组件内部进行断言和测试作业
#### 中间件堆栈是一个数组
#### 对象何时保存？

使用与常规文本相同的内联格式：

##### `:content_type`选项

指向API（api.rubyonrails.org）的链接将由指南生成器按以下方式处理：

包含发布标签的链接保持不变。例如

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

不会被修改。

请在发布说明中使用这些链接，因为它们应该指向相应的版本，无论生成的目标是什么。

如果链接不包含发布标签并且正在生成边缘指南，则将域名替换为edgeapi.rubyonrails.org。例如，

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

变成

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

如果链接不包含发布标签并且正在生成发布指南，则注入Rails版本。例如，如果我们正在为v5.1.0生成指南，则链接

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

变成

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

请不要手动链接到edgeapi.rubyonrails.org。

指南和API应在适当的情况下保持一致。特别是，API文档准则的以下部分也适用于指南：

在生成指南之前，请确保您的系统上安装了最新版本的Bundler。要安装最新版本的Bundler，请运行gem install bundler。

如果已经安装了Bundler，可以使用gem update 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，这经常导致重复。

要为Kindle生成指南，请使用以下rake任务：

$ bundle exec rake guides:generate:kindle

欢迎您帮助改进本指南的质量。

如果您发现任何拼写错误或事实错误，请贡献您的意见。要开始，请阅读我们的文档贡献部分。

您还可能会发现不完整的内容或过时的内容。请为主要内容添加任何缺失的文档。请先检查 Edge 指南，以验证问题是否已经修复或尚未修复。请参阅 Ruby on Rails 指南准则以了解样式和规范。

如果您发现需要修复但无法自行修复的问题，请提交问题。

最后但同样重要的是，欢迎您在官方 Ruby on Rails 论坛上讨论有关 Ruby on Rails 文档的任何问题。