Home

格式说明

总则

• 中英文之间添加一个空格。
• 中文没有“斜体”。
• 统一使用弯引号，禁止使用直角引号。

Asciidoc

• Asciidoc 的标题（heading）有些特殊，最高一级（=）用于编写书名和某一部分（part）的标题。一章的标题使用两个等号（==），x.x 节使用三个等号，x.x.x 节使用四个等号。

• 所有章名和小节都不要编号，排版系统会自动编号。

• 所有章名和小节都要指定 ID，方法举例：

  [[what-is-rails]]
  === What is Rails?
  

  ID 的值根据英文原文的标题确定。

• 交叉引用的格式为 <<file_name#id>>。例如，引用 getting_started.adoc 文件中的第 2 小节：<<getting_started#what-is-rails>>。文件名不带扩展名。

• 代码块的句法：

  [source,ruby]
  .Title
  ----
  def hello
    puts 'Hello'
  end
  ----
  

  其中，Title 是可选的。

• 如果想直接链接 URL，这样写：link:$$https://google.com$$[]。

• Rails Guides 每一篇文章的开头都有“内容摘要”，这部分的句法如下：

  [.chapter-abstract]
  --
  This guide covers getting up and running with Ruby on Rails.
  
  After reading this guide, you will know:
  
  - How to install Rails, create a new Rails application, and connect your application to a database.
  - The general layout of a Rails application.
  - The basic principles of MVC (Model, View, Controller) and RESTful design.
  - How to quickly generate the starting pieces of a Rails application.
  --
  

  [.chapter-abstract] 是指定这一部分内容的 CSS class。

• 文中的插图放在根目录下的 images 文件夹中。在文中引用时，直接指定图片的文件名即可，不用带 images 前缀，如下：

  [[image-id]]
  .Image Title
  image::image-filename.jpg[]