Asciidoctor基础语法

简介

Asciidoctor是一个快速文本处理器和发布工具链，用于将文本内容转为HTML,PDF,PPT或者其他格式
默认提供了一系列样式,用于表现HTML内容.

Asciidoctor可以运行在Ruby,JVM或者NodeJS环境中,具体参考 官网

文章及更新出自我的博客,CSDN不定期维护,更多内容参考
我的博客

安装

需要安装Ruby运行环境
安装
gem install asciidoctor
查看版本
asciidoctor --version
升级版本
gem update asciidoctor

AsciiDoc语法

以下语法仅为官网推荐语法,不包括用户或者第三方自定义实现.

与markdown语法区别

需求	Markdown	AsciiDoc
加粗	**加粗内容**	*加粗内容*
加粗(不受约束)	**加粗**内容	**加粗**内容
斜体	*斜体内容*	_斜体内容_
斜体(不受约束)		_斜体_内容
等宽	`等宽内容`	`等宽内容`
等宽(不受约束)	`等宽`内容	``等宽``内容
链接	[链接提示](网址URL)	网址URL[链接提示]
相对链接	[链接提示](相对路径)	link:相对路径[链接提示] xref:相对路径[链接提示]
文件链接	[文件名称](文件URL)	link:文件位置
参考链接	#H标签ID[提示]	<<标题名称>>
参考锚点	<h2 id=“锚点”>标题</h2>	[#锚点] ==标题
内联锚点		.[[步骤]] 提示
图片		image:图片地址[图片描述]
图片(无描述)		image::图片地址[图片描述]
标题	## 二级标题	== 二级标题
引用	> 引用内容 > 引用内容	____ 引用内容 ____
文字块	$ 文字内容	制表 文字内容 .... 文字内容 ....
代码块	``` 语法 代码块 ```	[source, 语法] ---- 代码块 ----
无序列表	* 一级列表 ** 二级列表 *** 三级列表	* 一级列表 ** 二级列表 *** 三级列表
有序列表	1. 一级列表 2. 二级列表 3. 三级列表	. 一级列表 . 二级列表 . 三级列表
主题打断	*** * * * --- - - - ___ _ _ _	‘’’
文档描述信息	--- title: 文档标题 ---	= 文档标题 :awestruct-layout: base
警告		TIP: 讲警告内容
侧边栏
加粗标题
包含其他文档		include:: 文档.adoc[]
URI跳转	[页面ID]: 页面地址 “页面描述” Go [页面ID]	:页面ID: 页面地址 Go {页面ID}[页面描述].
自定义CSS		[.path] __样式文本__

属性

属性名称不区分大小写,同时各环境中的相同属性名称具有优先级先后
API或CLI中定义的属性 > 文档中定义的属性 > 属性的默认值
另外,可以人为修改属性值优先级顺序.

：leveloffset：方式声明一个属性
：leveloffset：3方式声明并赋值一个属性
!leveloffset： 或 ：leveloffset !: 取消一个属性
我们可以在文档的头信息中设置属性信息,如果value中有空格,逗号等特殊字符,需要用""双引号包裹.
:name: value

内置属性

:toc: 文章目录
:toc: right 文章目录,右浮动显示
:imagesdir: ./images 图片默认目录
:iconsdir: ./icons 图标默认目录
:stylesdir: ./styles CSS样式默认目录

文档标记语法

介绍了基本的语法规则,至于预览文件,可以参考附件.

文档名称

通过 = 开头,指定文档名.同时,可以在文档下面标识属性.

= 模板示例
:keywords: adoc, example
:author: Jion
:email: [e-mail]
:revnumber: v1.0
:revdate: 2019-05-01
:toc: left
:toc-title: 目录
:toclevels: 2

这是一个模板,介绍了相关语法. +
{author}写作,更多联系 <[e-mail]>

文件类型

doctype 可选参数有
book 图书,具有顶级标题,附录等,由article构成

article 文章,具有附录,摘要等…

manpage 手册,简短的描述

inline 片段,被以上包含

注释

使用 // 和 分别表示单行注释和多行注释.

// 这是注释内容

这是多行注释,
这是多行注释

目录

建议使用属性 toc , toc-title , toclevels 分别表示启用目录及其对齐, 目录标题, 目录层深度

摘要

在文件标题和一级标题之间的段落,会被自动设置为摘要.

= 文档标题

摘要内容,........

== 标题一

段落标题

正常的标题

= 文件标题
== 一级标题
=== 二级标题
==== 三级标题
===== 四级标题
====== 五级标题

在标题中指定ID

[#header-id]
====== 带有ID的标题

带有属性的文件标题

更多属性参考标题属性

= 文档标题
:revdate: 1.0
:author: jionjion
:email: {author_email}

文本样式

粗体

使用 \* 或者 ** 包裹,构成粗体字体

*主题样式*

**粗体样式**

斜体

使用 \_ 或者 __ 包裹,构成斜体字体

_斜体样式_

__斜体样式__

等宽

使用 `` 包裹,构成等宽字体
多用在特殊名词或者其他特定解释词语

`等宽样式`

`Hello Word`

角标

使用 ~ 包裹作为下脚标
使用 ^ 包裹作为上角标

H~2~O

E=mc^2^

列表

无序列表

使用 - 作为基本的无序列表

- 无序列表

无序列表嵌套

使用 * 可以进行无序列表之间的嵌套

* 无序列表
** 列表嵌套
*** 列表嵌套
**** 列表嵌套
***** 列表嵌套

清单列表

具有icon图标的代办信息

* [*] 完成
* [x] 完成
* [ ] 未完成

有序列表

通过数字指定列表

通过 序号 . 的形式进行列表的序号指定.

1. 列表一
2. 列表二
3. 列表三

自动匹配数字

当然,也可以通过 . 自动进行序号的匹配

. 列表一
. 列表二
. 列表三

指定列表起始数字

[start=起始数字] 进行列表的起始数字的指定

[start=6]
. 列表六
. 列表七

反转列表

[%reversed] 可以对列表数字进行倒序排列

[%reversed]
. 列表三
. 列表二
. 列表一

更多支持

支持列表嵌套,自定义列表序号格式

表述列表

词释

关键词1:: 关键词1解释
关键词2:: 关键词2解释

列表

标题::
  计划:::
    . 事件一
    . 事件二

问答样式

[qanda]
问题?::
  答案.........

表格

基本表格

简单的分配行列的表格

|===

| 第一行,第一列 | 第一行,第二列

| 第二行,第一列 | 第二行,第二列

|===

指定列数的表格

只是指定列数,自动分配行数的表格
3* 表示具有三个完全一样配置的列配置

[cols="3*"]
|===
| 单元格1
| 单元格2
| 单元格3

| 单元格4
| 单元格5
| 单元格6
|===

水平对齐方式

使用 < , ^ , > 分别表示水平左对齐,水平居中对齐,水平右对齐.
默认使用水平左对齐

[cols="<,^,>"]
|===
| 第一行,第一列,左对齐
| 第一行,第二列,居中对齐
| 第一列,第三列,右对齐

| 第二行,第一列,左对齐
| 第二行,第二列,居中对齐
| 第三行,第三列,右对齐
|===

垂直对齐

使用 .< , .^ , .> 分别表示垂直顶部对齐,垂直居中对齐,垂直底部对齐
默认使用垂直顶部对齐

[cols=", .<, .^, .>"]
|===
| 第一行,第一列,内容............................................
| 第一行,第一列
| 第一行,第二列,内容
| 第一列,第三列,右对齐

| 第一行,第一列,内容............................................
| 第二行,第一列,左对齐
| 第二行,第二列,居中对齐
| 第三行,第三列,右对齐
|===

调整表格宽度

可以采用百分比的方式进行调整各列所占的宽度. +
数字在[1,99]之间,表示占总数的百分比

[cols="2,5,3"]
|===
| 占宽比20%
| 占宽比50%
| 占宽比30%
|===

重复列,跨列,跨行

使用 3*| 开头表示当前单元格重复3次 +
使用 2+| 开头表示当前单元格跨列2列 +
使用 .2+| 开头表示当前单元格跨行2行

|===

| 第一行,第一列 | 第一行,第二列 | 第一行,第三列 | 第一行,第四列

3*| 第二行,重复的 | 第二行,第四列

| 第三行,第一列
| 第三行,第二列
2+| 第三行,跨列

| 第四行,第一列
.2+| 第四行,跨行
| 第四行,第三列
| 第四行,第四列

| 第五行,第一列
| 第五行,第三列
| 第五行,第四列

|===

表头

通过使用 options="header" 开启表头,使第一行成为表头

[cols=2*,options="header"]
|===
| 第一列表头
| 第二列表头

| 第二行,第一列
| 第二行,第二列
|===

表脚

通过使用 options="footer" 开启表脚,使最后一行变为表脚

[options="footer"]
|===
| 第一列表头 | 第二列表头

| 第二行,第一列
| 第二行,第二列

| 第一列表脚
| 第二列表脚
|===

表宽

[%autowidth] 可以使表格整体根据表格内容调整宽度

[%autowidth]
|===
| 第一行,第一列
| 第一行,第二列
|===

[width=75%] 可以使表格整体宽度占当前页面 70%

[width=75%]
|===
| 第一行,第一列
| 第一行,第二列
|===

边界线表

[grid=rows] 可以使表格为只显示行与行之间的边框,可选值为 rows，cols 或 none

[grid=rows]
|===
| 第一列 | 第二列 | 第三列

| 第二行,第一列
| 第二行,第二列
| 第二行,第三列

| 第三行,第一列
| 第三行,第二列
| 第三行,第三列
|===

更多属性

参考 官网

水平线

可以使用 --- , - - -, ***, * * * 完成水平线

---
- - -
***
* * *

分页

使用 <<< 进行分页

网络链接

网址

默认会将正文中的网络地址,转为超链接.
如果不需要,则需要在网路链接前加 \

此外,可以将链接指向文件,或者其他相对位置

不显示下划线的超链接
\https://asciidoctor.org/docs/user-manual

只显示链接提示
https://asciidoctor.org/docs/user-manual[官网]

宏链接

对于一些需要特殊命令执行的链接,如查看网页源代码,可以使用宏链接指向

link:view-source:asciidoctor.org[查看Asciidoctor官网源代码]

交叉引用

在当前AsciiDoc文档中指向其他标题或者另外一个AsciiDoc.称之为交叉引用.
使用标题时,系统会自动根据标题其创建锚点,但是对于中文不友好,更多情况下我们自定义锚点,并在其他地方引用.

自定义锚点

使用 [[ID]] 或者 [#ID] 自定义锚点,锚点不限于标题,也可以在段落,表格上增添,或者直接在内容前指定.

[#header_anchor]
== 示例标题

[[text_anchor]]
这是一段示例描述自然段...

[[inner_text_anchor]]这是一个内联的锚点...

引用锚点

使用 <<ID,描述>> 跳转到已经定义的锚点上.如果是通过标题自动生成的锚点,使用 <<标题>> 直接进行跳转.

跳转锚点 <<text_anchor, 这是...>>

跳转锚点 xref:text_anchor[这是].

文件间引用

参考 官网

指令

include

将一个文件导入到当前文件.
语法 include::path[<attrlist>] ,其中 path 为文档的绝对路径或者相对路径. [] 中的 attrlist 为可选参数.

包含一个子文件,文件名为content
include::content.adoc[]

可以通过声明属性表示文件路径,配合包含文档或者代码文件

:includedir: _includes
:sourcedir: ../src/main/java

include::{includedir}/fragment1.adoc[]

[source,java]
----
include::{sourcedir}/org/asciidoctor/Asciidoctor.java[]
----

图片

引入图片

使用 image:: 引入一个块图片,占据整行.如果要使用内联图片,则使用 image: 命令.
后跟网络或者本地位置. [] 中指定参数.参数顺序依次为标题,宽,高.

一个具有提示标题,宽,高的超链接图片

[link=https://www.flickr.com/photos/javh/5448336655]
image::sunset.jpg[Sunset,300,200]

指定描述宽高

使用 alt 表示图片描述, width 表示图片宽度, height 表示图片高度

image::sunset.jpg[alt=Flower,width=640,height=480]

外联或者内联图片

使用 image:: 和 image: 分别表示内联图片和外联图片.

image:https://upload.wikimedia.org/wikipedia/commons/3/35/Tux.svg[Linux,25,35] everywhere these days.
image::https://upload.wikimedia.org/wikipedia/commons/3/35/Tux.svg[Tux,250,350]

图片默认路径

文件路径由属性 imagesdir 控制,默认为空,并自动添加到每个图像目标的开头,无需明确设置.

浮动并对齐

使图片右浮动,并居中

image::tiger.png[Tiger,200,200,float="right",align="center"]

更多属性

更多属性参考 官网

视频

语法

video::video_file.mp4[]

更多属性参考 官网

音频

语法

audio::ocean_waves.mp3[options="autoplay,loop"]

更多属性参考 官网

文档提示块

• NOTE 小贴士,用来提示友好的提示
• TIP 新的主意,表示一个提问或者新的方向
• IMPORTANT 错误,红色感叹号,表示十分重要
• CAUTION 注意,表示一个可能会引起错误的地方
• WARNING 警告,表示一个不被允许的操作

表示不同的提示等级.注意,必须大写

简单提示

关键字必须大写,且后空一格

NOTE: 这是一个 NOTE 提示

TIP: 这是一个 TIP 提示

IMPORTANT: 这是一个 IMPORTANT 提示

CAUTION: 这是一个 CAUTION 提示

WARNING: 这是一个 WARNING 提示

段落提示

通过 [] 在 ==== 示例块上标注提示属性,进而将整体作为一个提示

[TIP]
====
这是一大段提示内容
各种提示的格式

- 提示1
- 提示2
====

文档花絮块

通过使用 **** 包裹内容,使其独立于文档内容之外,有其独立的标题,内容

.关于作者
****
一条咸菜鱼,又闲又菜又多余.
****

文档示例块

通过 ==== 包裹内容,作为一个示例内容.并将内容原文本输出

.示例文档标题
====
以下内容会被格式输出,作为一个示例

- 示例格式
- 示例格式

The document header is useful, but not required.
====

文档文本块

通过使用 ` ` ` 进行包裹,将文档只显示源格式,不会对文档进行格式的替换

文档代码块

常用作代码块的编写,用 ---- 包裹.其中 %nowrap 表示当代码过长时,不进行自动换行,而是显示水平线.

[source%nowrap, java]
----
  System.out.println('Hello Word!');
----

引用摘要块

行引用

通过 [quote] 属性进行引用

[quote, 作者(可选), 副标题或者出处(可选)]
这是引用的正文

块引用

使用 ____ 进行包裹,然后标注属性 [quote] 输出格式

[quote, 作者(可选)]
____
自然段1.......

自然段2......
____

引用诗歌

改引用方式可以在保持换行和缩进,便于读取
通过 [verse] 进行诗歌的引用

律诗格式

[verse, 作者(可选), 副标题或者出处(可选)]
首联,
颔联.
颈联,
尾联.

词牌格式

当诗歌之间出现空行时,采用这种方式.

[verse, 作者(可选), 副标题或者出处(可选)]
____
(仄)仄仄平平，(仄)仄平平仄。

(仄)仄平平仄仄平，(仄)仄平平仄。

(仄)仄仄平平，(仄)仄平平仄。

(仄)仄平平仄仄平，(仄)仄平平仄。
____

开放块

使用 -- 包裹并配合 [] 属性可以作为以上各种块

数学公式

参考 官网

ICON图标

参考 官网

将当前文档输出为HTML

使用命令 asciidoctor Example.adoc 将文件输出为HTML

转为PDF

使用第三方支持插件完成转换
参考 官网

将MakerDown文档转为AsciiDoc文档

参考 官网