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[提示] | <<标题名称>> |
| 参考锚点 | 标题 |
[#锚点] ==标题 |
| 内联锚点 | .[[步骤]] 提示 | |
| 图片 |  | 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: [email protected]
:revnumber: v1.0
:revdate: 2019-05-01
:toc: left
:toc-title: 目录
:toclevels: 2
这是一个模板,介绍了相关语法. +
{author}写作,更多联系
文件类型
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]]这是一个内联的锚点...
引用锚点
使用 < 跳转到已经定义的锚点上.如果是通过标题自动生成的锚点,使用 <<标题>> 直接进行跳转.
跳转锚点 <>
跳转锚点 xref:text_anchor[这是].
文件间引用
参考 官网
指令
include
将一个文件导入到当前文件.
语法 include::path[ ,其中 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文档
参考 官网