asciidoctor常用指令

段落

普通段落

段落之间是以空行划分的,编辑的时候简单的使用回车换行并不会生成一个新的段落。例如:

adoc书写内容
这是第一段,
回车换行并不会另起一段。

这是第二段
Example 1. 显示结果

这是第一段, 回车换行并不会另起一段。

这是第二段

换行

asciidoctor中换行的书写就是在行尾加上空格和+,例如:

adoc书写内容
这是第一段, +
回车换行并不会另起一段,但是通过空格加+号可以换行。

这是第二段
Example 2. 显示结果

这是第一段,
回车换行并不会另起一段,但是通过空格加+号可以换行。

这是第二段

文字段落

adoc书写内容
普通段落。

  以至少一个空格开头的一系列行是文字段落。
  文字段落被视为预格式化的文本。
  文本以固定宽度的字体显示
  并且保留了终点线。

另一个正常段落。
Example 3. 显示结果

普通段落。

以至少一个空格开头的一系列行是文字段落。
文字段落被视为预格式化的文本。
文本以固定宽度的字体显示
并且保留了终点线。

另一个正常段落。

警告

警告的书写是在段落的行首增加一个标签,Asciidoctor可以使用 Font Awesome和CSS“描绘”图标。将文档属性icons的值设置为font来启用该特性。Asciidoctor会在文档中添加HTML标记,通过这些标记来从Font Awesome字体为每一个警告块选择一个合适的字符来展示。图标还可以使用inline和styled。Asciidoctor内置的几种标签类型:NOTE、TIP、IMPORTANT、WARNING、CAUTION。例如:

adoc书写内容
NOTE: 这是一个提醒段落,NOTE必须用全大写,否则不起作用。
Example 4. 显示结果
Note
这是一个提醒段落,NOTE必须用全大写同时还要注意冒号与空格,否则不起作用。

还有一种写法是创建警示块,例如:

adoc书写内容
[NOTE]
====
普通警示是只是针对一个段落,警示块可以包含复杂的内容。

.列表
- one
- two
- three

另一个段落。
====
Note
显示结果

普通警示是只是针对一个段落,警示块可以包含复杂的内容。

列表
  • one

  • two

  • three

另一个段落。

概要段落

默认的Asciidoctor样式会自动将序文的第一段作为摘要段落。

adoc书写内容
[.lead]
这段文字将作为一个概要,[.lead]是概要段落的指令。
Example 5. 显示结果

这段文字将作为一个概要,[.lead]是概要段落的指令。

格式化文本

仅列举一些常见的加粗、斜体等。

adoc书写内容
_斜体的文字前后加上下划线_

如果一句话中只需要部分内容是斜体,则需要在__斜体__内容的前后加上两个下划线

*粗体与斜体类似,只是粗体的标记是星号*

如果一句话中只需要部分内容是粗体,则需要在**粗体**内容的前后加上两个星号

*_粗体加斜体必须粗体在外斜体在内,否则不生效_*

**__个别__**字的**__粗体加斜体__**与前面的个别粗体或斜体类似
Example 6. 显示结果

斜体的文字前后加上下划线

如果一句话中只需要部分内容是斜体,则需要在斜体内容的前后加上两个下划线

粗体与斜体类似,只是粗体的标记是星号

如果一句话中只需要部分内容是粗体,则需要在粗体内容的前后加上两个星号

粗体加斜体必须粗体在外斜体在内,否则不生效

个别字的粗体加斜体与前面的个别粗体或斜体类似

上标和脚注

adoc书写内容
上标^符号^

下标~符号~
Example 7. 显示结果

上标符号

下标符号

文本颜色

adoc书写内容
[red]#字体颜色# and [big red yellow-background]*大号字体颜色加背景*.

[underline]#下划线#, [overline]#上划线#,
[blue line-through]*带颜色的中划线*.

颜色可以是下面16中的任何一种:

* [white]#白色:white#
* [silver]#银色:silver#
* [gray]#灰色:gray#
* [black]#黑色:black#
* [red]#红色:red#
* [maroon]#暗红色:maroon#
* [yellow]#黄色:yellow#
* [olive]#橄榄色:olive#
* [lime]#亮绿色:lime#
* [green]#绿色:green#
* [aqua]#浅绿色:aqua#
* [teal]#蓝绿色:teal#
* [blue]#蓝色:blue#
* [navy]#深蓝色:navy#
* [fuchsia]#紫红色:fuchsia#
* [purple]#紫色:purple#
Example 8. 显示结果

字体颜色 and 大号字体颜色加背景.

下划线, 上划线带颜色的中划线.

颜色可以是下面16中的任何一种:

  • 白色:white

  • 银色:silver

  • 灰色:gray

  • 黑色:black

  • 红色:red

  • 暗红色:maroon

  • 黄色:yellow

  • 橄榄色:olive

  • 亮绿色:lime

  • 绿色:green

  • 浅绿色:aqua

  • 蓝绿色:teal

  • 蓝色:blue

  • 深蓝色:navy

  • 紫红色:fuchsia

  • 紫色:purple

文档标题

标题是可选的。标题不能包含空号,并且下面必须紧跟至少一个空行。

标题

adoc书写内容
= 文档标题

文档内容……
Example 9. 显示结果

= 文档标题

文档内容……

标题以及作者行

Asciidoctor允许在作者行中出现多位作者,使用分号来分割开来。

adoc书写内容
= 文档标题
张三<mail@www.com>

文档内容……

标题、作者行以及版本行

不能只写版本行而不写作者行!

adoc书写内容
= 文档标题
张三<mail@www.com>
v1.0, 2020-10-10

文档内容……

带属性的文档标题

adoc书写内容
= 文档标题
张三<mail@www.com>
v1.0, 2020-10-10
:toc:
:imagesdir: assets/images
:homepage: https://magicletters.github.io

文档内容……

章节标题

当使用文章标题类型时,默认只能有一个级别为0的文章标题(也就是文档标题),并且必须在文档头部。书籍标题类型与文章标题类型类似,不过允许出现多个0级标题。

adoc书写内容
= 最高级别标题

== 一级

=== 二级

==== 三级

===== 四级

====== 五级

== 另一个一级
Example 10. 显示结果

= 最高级别标题

== 一级

=== 二级

==== 三级

===== 四级

====== 五级

== 另一个一级

水平线和分页符

水平线

adoc书写内容
'''
Example 11. 显示结果

分页符

adoc书写内容
<<<

列表

列表前后的空行是必须的。

无序列表

adoc书写内容
* 张三
* 李四
* 王五
Example 12. 显示结果
  • 张三

  • 李四

  • 王五

无序嵌套列表

adoc书写内容
* level 1
** level 2
*** level 3
**** level 4
***** level 5
* level 1
Example 13. 显示结果
  • level 1

    • level 2

      • level 3

        • level 4

          • level 5

  • level 1

清单

adoc书写内容
- [*] checked
- [x] also checked
- [ ] not checked
- normal list item
Example 14. 显示结果
  • ✓ checked

  • ✓ also checked

  • ❏ not checked

  • normal list item

有序列表

adoc书写内容
. Step 1
. Step 2
. Step 3
Example 15. 显示结果
  1. Step 1

  2. Step 2

  3. Step 3

有序最大嵌套列表

adoc书写内容
. level 1
.. level 2
... level 3
.... level 4
..... level 5
. level 1
Example 16. 显示结果
  1. level 1

    1. level 2

      1. level 3

        1. level 4

          1. level 5

  2. level 1

标签列表

adoc书写内容
第一条:: 第一条的解释 +
回车换行
第二条::
标签列表的第二种写法
Example 17. 显示结果
第一条

第一条的解释
回车换行

第二条

标签列表的第二种写法

常见问题以及解答

adoc书写内容
[qanda]
Asciidoctor是什么::
用Ruby实现的AsciiDoc的处理器。
QA是否有另一种写法:: 是的,这就是另一种写法。
Example 18. 显示结果
  1. Asciidoctor是什么?

    用Ruby实现的AsciiDoc的处理器。

  2. QA是否有另一种写法?

    是的,这就是另一种写法。

混合样式列表

adoc书写内容
Operating Systems::
  Linux:::
    . Fedora
      * Desktop
    . Ubuntu
      * Desktop
      * Server
  BSD:::
    . FreeBSD
    . NetBSD

Cloud Providers::
  PaaS:::
    . OpenShift
    . CloudBees
  IaaS:::
    . Amazon EC2
    . Rackspace
Example 19. 显示结果
Operating Systems
Linux
  1. Fedora

    • Desktop

  2. Ubuntu

    • Desktop

    • Server

BSD
  1. FreeBSD

  2. NetBSD

Cloud Providers
PaaS
  1. OpenShift

  2. CloudBees

IaaS
  1. Amazon EC2

  2. Rackspace

混合样式列表

adoc书写内容
* Every list item has at least one paragraph of content,
  which may be wrapped, even using a hanging indent.
+
Additional paragraphs or blocks are adjoined by putting
a list continuation on a line adjacent to both blocks.
+
list continuation:: a plus sign (`{plus}`) on a line by itself

* A literal paragraph does not require a list continuation.

 $ gem install asciidoctor

* AsciiDoc lists may contain any complex content.
+
[cols="2", options="header"]
|===
|Application
|Language

|AsciiDoc
|Python

|Asciidoctor
|Ruby
|===
Example 20. 显示结果
  • Every list item has at least one paragraph of content, which may be wrapped, even using a hanging indent.

    Additional paragraphs or blocks are adjoined by putting a list continuation on a line adjacent to both blocks.

    list continuation

    a plus sign (+) on a line by itself

  • A literal paragraph does not require a list continuation.

    $ gem install asciidoctor
  • AsciiDoc lists may contain any complex content.

    Application Language

    AsciiDoc

    Python

    Asciidoctor

    Ruby

链接

外部链接

adoc书写内容
http://asciidoctor.org - automatic!

http://asciidoctor.org[Asciidoctor]

https://github.com/asciidoctor[Asciidoctor @ *GitHub*]
Example 21. 显示结果

图片

adoc书写内容
image::sunset.jpg[]

image::sunset.jpg[Sunset]

[[img-sunset]]
image::sunset.jpg[caption="Figure 1: ", title="A mountain sunset", alt="Sunset", width="300", height="200", link="http://www.flickr.com/photos/javh/5448336655"]

image::http://asciidoctor.org/images/octocat.jpg[GitHub mascot]

image:sunset.jpg[Sunset,150,150,role="right"] What a beautiful sunset!
Example 22. 显示结果
sunset
Sunset
Sunset
Figure 1: A mountain sunset
GitHub mascot

Sunset What a beautiful sunset!

源代码

表格