如果您发现文档有错误或者遗漏,请不要犹豫提交 issue 或发起一个带有修复的 pull request 。我们也支持你在 邮件列表 或者 聊天室 提出问题并讨论项目的任何方面。欢迎新的贡献者。

本手册假定你使用Asciidoctor来生成和转换你的文档。与传统AsciiDoc.py相比Asciidoctor实现了更多的语法,属性和功能。 从AsciiDoc Python迁移 列出了Asciidoctor和AsciiDoc处理器可用的功能。

Asciidoctor简介

1. 1. 什么是Asciidoctor?

Asciidoctor是一个快速文本处理器和发布工具链,用于将AsciiDoc内容转换为HTML5,EPUB3,PDF,DocBook 5(或4.5)slidedecks和其他格式。Asciidoctor使用Ruby编写打包为RubyGem并发布到了 RubyGems.org。Gem也打包在几个Linux发行版中,包括Fedora,Debian和Ubuntu。Asciidoctor是开源的, 托管在github上 ,并使用MIT协议发布。

1.1. 1.1. 概况

Asciidoctor读取以纯文本书写的内容,如下图中左侧面板所示,并将其转换为HTML5,如右侧面板所示。如图所示,Asciidoctor添加了一个默认样式到HTML5文档上,以提供愉悦的开箱即用体验。

zen-screenshot

2. 9. 格式化标记

有两种标记格式用于将样式(即格式化)应用于文本,受约束和不受约束。这些格式化标记在AsciiDoc语法中称为引用。本章介绍了它们的用途,差异以及如何应用它们。

2.1. 9.1 约束标记

简而言之,“constrained” 的意思是围绕一个单词或单词序列。

约束标记是放在单词放在单词周围的单个字符(通常时符号)。“around”的定义是单词字符不会出现在封闭标记之外。

你可以使用这种格式去单独格式化一个单词:

当单独格式化一个单词时
That is *strong* stuff!
当格式化一个单词序列时
That is *really strong* stuff!
或者格式化一个靠近标点的单词
This stuff sure is *strong*!

2.2. 9.2 非约束标记

简而言之,“unconstrained”意思是指可以用在任何位置,包括单词内部。

非约束标记是放在文本中任何位置的成对字符(通常是符号),包括在单词内部。“within”由单词字符可以出现在其中一个封闭标记之外的情况来定义。

非约束格式化
She spells her name with an "`h`", as in Sara**h**.

2.3. 9.3 什么时候我该使用非约束引用?

请考虑以下问题: * 在标记格式两侧是否有下划线? * 在起始标记前是否有冒号分号或右括号? * 格式标记内是否有空格?

如果你对这些问题中的任何一个回答是“是”,则需要切换到非约束标记(双重格式化)。

为帮助你确定特殊语法格式是否需要非约束格式化,考虑下面的场景:

Table 1. 约束标记或非约束标记
AsciiDoc 结果 标记类型 原因

Sara__h__

Sarah

非约束标记

a 和标记格式的左侧相邻

**B**old

Bold

非约束标记

o 与标记格式的右侧相邻

–**2016**

2016

非约束标记

; 和标记格式的左侧相邻

** bold **

bold

非约束标记

标记格式内部直接有空格

*2016*–

2016

约束标记

& 相邻的不是字母、数字、下划线、冒号或分号

*9*-*5*

9-5

约束标记

相邻的连字符不是字母、数字、下划线、冒号或分号

3. 10. 属性

属性是一个将Asciidoctor和其他轻量级标记语言区分开的特性之一。属性可以激活特性(行为,样式,交互等)或者替换(比如变量)内容。

在Asciidoctor中,属性分类如下:

4. 16. 章节

章节将文档按照内容层的次结构分区。在AsciiDoc中使用章节标题来定义章节。

一个章节标题做为这一章的标题。章节标题级别使用二到6个等号指定。标题前的等号数量表示在这一部分内的嵌套级别(使用基于0的索引)。

文档中可用的章节标题
= Document Title (Level 0)

== Level 1 Section Title

=== Level 2 Section Title

==== Level 3 Section Title

===== Level 4 Section Title

====== Level 5 Section Title

== Another Level 1 Section Title
Example 1. 呈现出的章节标题

Document Title (Level 0)

Level 1 Section Title

Level 2 Section Title

Level 3 Section Title

Level 4 Section Title
Level 5 Section Title

Another Level 1 Section Title

4.1. 16.4. 多锚

虽然一个章节标题只可以有一个主键,从Asciidoctor 1.5.7起,支持使用行内锚点在章节标题中注册附加锚点。无论你是否指定自定义ID此功能都有效。

以下是当使用自动生成ID时怎样注册附加锚点:

注册其他锚点
== [[secondary-id]][[tertiary-id]]Section Title
注册其他锚点
== Section Title[[secondary-id]][[tertiary-id]]

你可以将锚点放置在你想添加的章节标题的任意位置。你放置锚点的位置就是最终输出的位置,所以最好放到开头或结尾。开头是首选位置。

这些附加的锚点不影响生命的自定义ID。

在一个带有自定义ID主键的章节标题中注册附加锚点
[#primary-id]
== [[secondary-id]][[tertiary-id]]Section Title
或者你可以移动这个ID主键到章节标题后并和标题使用一个空格分隔。
== Section Title[[secondary-id]][[tertiary-id]] [[primary-id]]

然而我们不推荐在行内定义定义ID主键因为它更难以阅读。

4.2. 16.5. 链接

开启 sectlinks 属性将标题转换为链接。默认的Asciidoctor样式显示带链接的章节标题和没有链接的章节标题样式和颜色是一样的。

4.3. 16.6. 锚点

sectanchors 属性在一个文档中开启时,一个锚点被添加到章节标题前。默认Asciidoctor样式渲染锚点为一个浮动在章节标题左侧的分节符( § )。

4.4. 16.7. 编号

Asciidoctor允许在整篇文章中打开或关闭章节编号。你可以使用 sectnums 属性开启章节编号。

:sectnums:
为了兼容AsciiDoc Python,Asciidoctor仍支持 numbered 属性编号章节,但推荐使用 sectnums

你还可以在文档中任何标题上放使用次属性来切换自动编号设置。当你想要关闭编号时,可以在属性名后添加一个叹号:

:sectnums!:

== Unnumbered Section

对于文档中关闭章节编号的部分,这部分章节编号不会被累加。

比如:

= Document Title

:sectnums!:

== Colophon Section

== Another Colophon Section

== Last Colophon Section

:sectnums:

== Section One

== Section Two

== Section Three

这些章节将如下编号:

Colophon Section

Another Colophon Section

Last Colophon Section

1. Section One

2. Section Two

3. Section Three

Asciidoctor总是减掉文档中关闭章节编号部分的章节数。

如果 sectnums 在命令行中设置(或API),将会覆盖文档头中的值,但是他不会阻止文档中区域性的切换这个值。

如果 sectnums! 在命令行中设置,那么不管文档中如何设置编号都将会关闭。

灵活属性
sectnums 被称为灵活属性,

4.5. 16.8. 离散标题(又叫浮动标题)

要构造一个离散标题,你需要添加 discrete 属性到每个章节标题。离散标题的样式与章节标题类似,但不是章节层次结构的一部分,(即被从章节的层次结构中排除了),不包含后继的块,也不包含在目录中。 discrete 风格有效的降级章节标题为一个普通标题。

或者,你可以使用 float 标记一个离散标题。在这个情景中术语“float”不是布局的意思,也就是说它不左右浮动与其他内容块。意思只是它不被固定在层次结构中。

这里是一个使用浮动标题的例子。

**** (1)
Discrete headings are useful for making headings inside of other blocks, like this sidebar.

[discrete] (2)
== Discrete Heading (3)

Discrete headings can be used where sections are not permitted.
****
1 用于表示栏块开始的分隔线。
2 在文章标题上添加 discrete 属性将其降级为浮动标题。
3 离散标题的标题使用一到六个等号指定,和章节标题一样。

4.6. 16.9. 章节样式

Asciidoctor为期刊论文,学术论文和书籍提供常见的前页和及附属资料页的样式。 这些样式有:

  • 书籍的末页

  • 摘要

  • 前言

  • 赠言

  • 部分介绍

  • 附录

  • 术语(特殊用语)表

  • 索引

这些样式应可用于 articlebook 文档类型,书籍特有的部分介绍除外。

通常章节样式设置在一级章节标题或文本块上,例如,下面的例子展示如何标记一个章节为摘要。

[abstract]
== Documentation Abstract

Documentation is a distillation of many long, squiggly adventures.

每个章节样式的结构和使用规则在Structuring, Navigating, and Referencing Your Content中有解释。

5. 19. 文字格式

就像我们说话时强调某些单词或短语一样,我们可以在文本中使用格式进行强调。这些格式,比如粗体、等宽等,由周围带有简单标记的字母、单词或短语表示。当Asciidoctor处理附加有格式标记的文本时,在 引号替换阶段 这些标记被替换为对应的HTML或XML标签。者取决于你所使用的后端

文本格式与引号

6. 20. 无序列表

如果你想在邮件中创建一个列表,你会怎么做?有可能,你会使用和Asciidoctor用来识别列表项相同的字符标记列表项。

在下面的例子中,AsciiDoc语法使用星号(*)标记每一个列表项来声明无序列表。

* Edgar Allen Poe
* Sheri S. Tepper
* Bill Bryson

列表项行首文本必须距离标记(*)至少一个空格。如果你喜欢你可以也缩进列表项。列表前后必须包含一个空白行。另外列表项间的空白行是允许的,但不是必需的。

Example 2. 呈现无序列表
  • Edgar Allen Poe

  • Sheri S. Tepper

  • Bill Bryson

7. 有序列表

有时,我们需要对列表中的项编号。直接可能告诉你可以像下面列表一样为每项添加数字前缀:

1. Protons
2. Electrons
3. Neutrons

上面这样写工作正常,但是当编号很明显时,如果你省略编号AsciiDoc处理器将自动为你自动插入编号:

. Protons
. Electrons
. Neutrons
  1. Protons

  2. Electrons

  3. Neutrons

如果你使用有序列表,必须保持他们连续。这不同于其他轻量级标记语言。这是一种调整编号列表便宜的方法。例如,你可以输入:

4. Step four
5. Step five
6. Step six

不过一般最佳实践是使用 start 属性配置此类事情:

[start=4]
 . Step four
 . Step five
 . Step six

要倒序显示编号,添加 reversed 选项:

[%reversed]
.原子的一部分
. Protons
. Electrons
. Neutrons
Parts of an atom
  1. Protons

  2. Electrons

  3. Neutrons

你可以使用点开头做前缀的行后年直接跟文本(点后面没有任何空隙)

这里是一个带有标题的列表的例子:

.Parts of an atom
. Protons
. Electrons
. Neutrons
Parts of an atom
  1. Protons

  2. Electrons

  3. Neutrons

7.1. 嵌套

你可以在每个元素前添加一个或多个点创建嵌套列表

. Step 1
. Step 2
.. Step 2a
.. Step 2b
. Step 3

Asciidoctor对没一级嵌套选用不同的编号模式。这里显示的是上面列表怎样渲染的:

Example 3. 一个嵌套有序列表
  1. Step 1

  2. Step 2

    1. Step 2a

    2. Step 2b

  3. Step 3

8. 23. 表格

表格是AsciiDoc语法中最复杂也是最精致的一部分。承载少量数据的时候,你应该发现它即有利于创建又有利于读取原始数据。但是看似简单,实则非常复杂。 表格以 |=== 分隔,由单元格构成。默认表格数据格式为PSV(Prefix Separated Values),这意味着处理器每遇到一个竖线(|)时就创建一个单元格。单元格分组为一行行,考虑到每行或列的跨度,每行必须有相同数量的单元格。这样,一行中连续的每个单元格也都属于一列。

下面这个简单的表格示例包含两列三行。

简单表格
|=== (1)
(2)
| Cell in column 1, row 1 | Cell in column 2, row 1 (3)
(4)
| Cell in column 1, row 2 | Cell in column 2, row 2

| Cell in column 1, row 3 | Cell in column 2, row 3

|===
1 表格的内容边界由后面跟三个等号的竖线定义(|===)。
2 在第一行前插入一个空行是一个技巧,可以确保第一行不被当作表头。
3 新单元格由竖线表示(|)。
4 每行可以由任意数量的空行分隔。
Table 2. 结果:呈现为一个简单表格

Cell in column 1, row 1

Cell in column 2, row 1

Cell in column 1, row 2

Cell in column 2, row 2

Cell in column 1, row 3

Cell in column 2, row 3

9. 27. 交叉引用

链接到当前文档或其他文档的其他位置叫做交叉引用(也称作外部参考)。创建一个外部引用,首先需要定义引用所指向的位置。

10. 29. 图像

在一行内只包含一个图像,在文件名前使用 image:: 前缀并在之后跟一对方括号。

11. 36. 注释

行注释
// A single-line comment.
行注释可以用来分隔元素,比如两个临近的列表。
块注释
////
A multi-line comment.

Notice it's a delimited block.
////

12. 46. 源码语法高亮

开发者习惯看使用颜色和其他样式强调代码结构的代码。(例如:关键词,类型,分割符等)。这种技术被称为 源码语法高亮 (或简称源码高亮)。因为此技术如此流行 —可以说是意料之中的​—​Asciidoctor集成了大量高亮你文档中代码块的库。这个列表包括CodeRay,Pygments,highlight.js,和prettify。

12.1. 46.1. 开启源码高亮

当开启语法高亮时,语法高亮将被应用到指定有 source 和所用编程语言的列表或文本块上。无论如何,语法高亮默认 开启。

在一个文档中开启语法高亮,你必须设置 source-highlighter 文档属性。你可以在CLI或者API中设置此文档属性。

如果你在文档中设置该属性,它必须定义在 文档头 中。

= Document title
:source-highlighter: <value>

例如,这里展示如何使用CodeRay开启语法高亮:

= Document title
:source-highlighter: coderay

12.2. 46.2. 可用源码高亮

下面的表格列出了 source-highlighter 属性推荐的值。

13. 47. 标注

标注号(又叫标注)提供了一种向逐字块中的行添加注释的方法。

每个逐字块中使用的标注必号须出现两次。第一次使用,在逐字块中,标记被注释的行(即目标)。第二次使用,在逐字块下面,定义注释文本。多个标注可以使用在一行上。

标注必须放置在在一行(目标)的最后。

以下是使用标注的逐字块的基本示例:

require 'sinatra' (1)
get 'hi' do  (2) (3)
  "Hello World!"
end
1 导入库
2 URL映射
3 响应块

因为标注可能会影响他们注释的代码的语法,Asciidoctor提供了几个特性用来从源码和生成的文档中隐藏标注。下一小结详细介绍了这些特性。

13.1. 47.1. 可友好复制粘贴的标注

在Asciidoctor 0.1.4之前的版本中,当访问由Asciidoctor生成的HTML页面的读者在一个包含标注的列表中选择源代码并复制时,标注号将被捕获到复制的文本中。如果读者粘贴该代码并试图运行它,标注中的额外字符串可能会导致编译时错误或运行时错误。

另一方面,你不希望标注注释或CSS弄乱你的原始源代码。你可以把你的标注整洁的放在行内注释之后。Asciidoctor将会认出标注前的行注释字符,也可以使用空格调整其位置,在转换文档时将会移除他们。

以下是支持的行内注释:

----
line of code  // <1>
line of code  # <2>
line of code  ;; <3>
----
<1> C语言风格行注释后的标注。
<2> Ruby, Python, Perl等行注释后的标注。
<3> Clojure行注释后的标注。

以下是渲染后的样子:

line of code  (1)
line of code  (2)
line of code  (3)
1 C语言风格行注释后的标注。
2 Ruby, Python, Perl等行注释后的标注。
3 Clojure行注释后的标注。

13.1.1. 47.1.1. XML标注

XML没有行注释,因此我们“将标注放在行注释后”的技巧在这里不起作用。在XML中使用标注,你必须使用标注的尖括号扩起XML注释和标注号。

以下是它在列表中的呈现方式:

[source, xml]
----
<section>
  <title>Section Title</title> <!--1-->
</section>
----
<1> 章节标题是必须的。

以下是渲染后的样子:

<section>
  <title>Section Title</title> (1)
</section>
1 章节标题是必须的。

注意注释已经替换为无法选中的带圆圈数字(如果你不使用字体图标,标注将以不同的方式渲染并且可以选中)。现在你和读者可以复制粘贴带标注的XML源码而不用担心错误发生。

13.1.2. 47.2. 标注图标

这个字体图标设置可以开启使用CSS绘制标注。

= Document Title
:icons: font (1)

NOTE: Asciidoctor现在支持字体图标的警示图标,由Font Awesome提供支持!(2)
1 激活HTML5后端中的字体图标。
2 警示块使用字体图标。

结构和导航及即引用你的内容

52. 目录

目录(TOC)是在使用Asciidoctor转换文档时根据文档结构自动生成的章和节标题的索引。

开启自动生成目录,你必须设置 toc 属性。

toc 属性可以通过命令行指定( -a toc

通过命令行开启TOC
$ asciidoctor -a toc adventure.adoc

或者在文档头中( TOC )。

通过文档头开启TOC
= The Dangerous and Thrilling Documentation Chronicles
Kismet Chameleon
:toc:

This journey begins on a bleary...

== Cavern Glow

The river rages through the cavern, rattling its content...

如果未指定其他选项,TOC直接插入到文档头部(文档标题,作者和修订行),有一个目录标题并只包含一级和二级标题。

Example 4. 设置toc属性
默认目录

Asciidoctor 允许您自定义布局,位置,以及目录标题。但是,并非所有转换器支持所有的自定义。查看目录摘要可以找到每个后端可用的自定义内容。

52.1. 文档中的位置

toc 的默认值为 autopreamblemacro 将目录放置在主文档区域中。

当没有指定 toc 的值也就是说为 auto 时,目录直接插入到文档头下(文档标题,作者和修订版本)

toc 设置为 preamble ,时目录位于序文的正下方。

当时用 preamble 配置目录位置时,如果你的文档没有序言目录不会出现。修复这个问题只需要设置 toc 属性为空值(或 auto )。

设置 toc 属性为 macro 可以放置目录到文档中任何位置。只需要放置toc宏( toc:[] )到文档中你想要显示目录的地方。在任何文档中toc宏只显示最多一次。

如果没有设置 tocmacron ,文档中的任何toc宏都将被忽略。

设置toc值为宏,并使用toc宏
= The Dangerous and Thrilling Documentation Chronicles
Kismet Chameleon
:toc: macro (1)

This journey begins on a bleary...

== Cavern Glow

toc::[] (2)

The river rages through the cavern, rattling its content...
1 必须将toc属性值设置为 macro 才能启用toc宏。
2 在这个例子中,toc宏放在了第一章的标题下,指明当文档渲染时目录显示的位置。
Example 5. 设置toc值为宏,并使用toc

手动指定目录位置