简介

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: jionjion@aliyun.com
:revnumber: v1.0
:revdate: 2019-05-01
:toc: left
:toc-title: 目录
:toclevels: 2这是一个模板,介绍了相关语法. +
{author}写作,更多联系 <jionjion@aliyun.com>

文件类型

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

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

manpage 手册,简短的描述

inline 片段,被以上包含

注释

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

// 这是注释内容


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

摘要

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

= 文档标题摘要内容,........== 标题一

段落标题

正常的标题

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

在标题中指定ID

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

带有属性的文件标题

更多属性参考标题属性

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

文本样式

粗体

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

*主题样式***粗体样式**

斜体

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

_斜体样式___斜体样式__

等宽

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

`等宽样式``Hello Word`

角标

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

H~2~OE=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/javainclude::{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文档

参考官网

Asciidoctor基础语法相关推荐

FPGA（2）基础语法 -- 按键控制led（alway@语句）
目录 1.module 文件名(端口) 2.声明关键字 3.always@语句代码 1.module 文件名(端口) 注:这里最好养成习惯,只在文件名后面的括号中声明引脚变量,输入输出.关键字类型 ...
javascript基础语法——表达式
前面的话一般地,关于javascript基础语法,人们听得比较多的术语是操作符和语句.但是,其实还有一个术语经常使用,却很少被提到,这就是javascript表达式(expression).本文将详 ...
Rust语言开发基础（六）基础语法
2019独角兽企业重金招聘Python工程师标准>>> 一.变量的定义和使用其它常见的编程语言对变量的定义通常是通过声明类型和使用关键new来创建一个变量,但Rust不是,Rust ...
python列表嵌套字典取值_Python基础语法：你不得不知的几种变量类型
(点击上方快速关注并设置为星标,一起学Python) 作者:kina_chen來源:简书 01. Python编码Python中默认的编码格式是 ASCII 格式,在没修改编码格式时无法正确打印汉字, ...
python赋值语句的一般格式为_Python 基础语法
Python 基础语法 Python 语言与 Perl,C 和 Java 等语言有许多相似之处.但是,也存在一些差异. 在本章中我们将来学习 Python 的基础语法,让你快速学会 Python 编程 ...
深入浅出CMake(二): 基础语法
在<深入浅出CMake(一):基础篇>文章中,我们已经知道了怎么依葫芦画瓢编写简单的 CMake 构建文件了,但如果应对复杂的工程的话,这还是远远不够的. CMake 是一套编译构建体系, ...
Python基础语法学习笔记
Python基础语法学习笔记想淘宝省钱看我简介,博客www.liangxin.name (一) 一.Print()函数 1.数字可以直接输出,无需加引号只能理解数字,却读不懂文字.因为数字和数学运 ...
Python的零基础超详细讲解（第三天）-Python的基础语法
多行语句 Python 通常是一行写完一条语句,但如果语句很长,我们可以使用反斜杠 \ 来实现多行语句,例如: duohang = item_one + \item_two + \item_three ...
Python的零基础超详细讲解（第二天）-Python的基础语法1
Python 基础语法打开python的编辑器这里注意的是,之前下载的python在电脑主页上没有快捷方式,需要在win开始界面中打开最终打开效果是一个白色的跟终端类似的编辑器,我们输入的时候是 ...

Asciidoctor基础语法

简介

安装

AsciiDoc语法

与markdown语法区别

属性

内置属性

文档标记语法

文档名称

文件类型

注释

目录

摘要

段落标题

正常的标题

在标题中指定ID

带有属性的文件标题

文本样式

粗体

斜体

等宽

角标

列表

无序列表

无序列表嵌套

清单列表

有序列表

通过数字指定列表

自动匹配数字

指定列表起始数字

反转列表

更多支持

表述列表

词释

列表

问答样式

表格

基本表格

指定列数的表格

水平对齐方式

垂直对齐

调整表格宽度

重复列,跨列,跨行

表头

表脚

表宽

边界线表

更多属性

水平线

分页

网络链接

网址

宏链接

交叉引用

自定义锚点

引用锚点

文件间引用

指令

include

图片

引入图片

指定描述宽高

外联或者内联图片

图片默认路径

浮动并对齐

更多属性

视频

音频

文档提示块

简单提示

段落提示

文档花絮块

文档示例块

文档文本块

文档代码块

引用摘要块

行引用

块引用

引用诗歌

律诗格式

与`markdown`语法区别