Ruby on Rails指南指南

1 Markdown

指南使用GitHub Flavored Markdown進行編寫。有詳細的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 論壇上進行。