Table of Contents
::
AsciiDoc 是一种文本文档格式，可以用于书写文档，文章，手册，书籍和 UNIX 手册。AsciiDoc 文件可以使用 asciidoc 命令转换成 HTML 和 DocBook 文件格式。AsciiDoc 结构先进：AsciiDoc 语法和输出标签（几乎可以转换成任意的 SGML/XML 标记）都可以由用户自己定义和扩展。
普通
段落不需要写任何特殊标记。一个段落只能是一行或多行连续文本。 在开始新的段落前使用至少一行的空白行分隔。
段落不需要写任何特殊标记。一个段落只能是一行或多行连续文本。
在开始新的段落前使用至少一行的空白行分隔。
换行
Rubies are red, + Topazes are blue. [%hardbreaks] Ruby is red. Java is black.
Rubies are red,
Topazes are blue.
Ruby is red.
Java is black.
literal
A normal paragraph. A paragraph offset by at least one space becomes a literal paragraph. All lines in a literal paragraph must be adjacent. A literal paragraph is displayed as preformatted text. The text is shown in a fixed-width font. Spaces and newlines, like the ones in this sentence, are preserved. Another normal paragraph.
A normal paragraph.
A paragraph offset by at least one space becomes a literal paragraph. All lines in a literal paragraph must be adjacent.
A literal paragraph is displayed as preformatted text. The text is shown in a fixed-width font. Spaces and newlines, like the ones in this sentence, are preserved.
Another normal paragraph.
= 书名 作者 v0.1, 2018-05 :doctype: book [preface] == 前言标题 前言内容 == 章节标题 章节内容 === 小节标题 小节内容 [appendix] == 附录标题 附录内容 [bibliography] == 参考文献标题 参考文献内容 [index] == 索引标题
|
重要
|
文件头是可选项 |
|
注意
|
文件头不应含有空白行，使用空白行与正文分离 |
只有标题
= 我的文件头 我的文件正文
标题和作者信息
= 我的文件标题 作者1; 作者2 <myname@email.com> 文件正文
|
提示
|
AsciiDoctor 允许在作者信息处写多个作者。多个作者之间使用 ; 分隔
|
标题, 作者, 修订信息
= 文件标题 作者 <myname@email.com> v1.0, 2014-01-01 文件正文
|
重要
|
如果要写修订信息一定要先写作者信息，共同使用 |
含有属性设置的文件头
= 文件标题 作者 <myname@email.com> v1.0, 2018-04-11 :toc: :imagesdir: assets/images :homepage: https://asciidoctor.org 文件正文
|
注意
|
文件头只能写在文件开头，且只能有一个文件头 |
基本区块是一行或多行文本，也可以包括其他基本区块。
AsciiDoc 基本区块概括如下[这是一个大概的结构指南，不是严格的语法定义]：
文档 ::= (头部?,前言?,章节*) 头部 ::= (标题,(作者,修订?)?) 作者 ::= (名字,(中间名?,姓氏)?,Email地址?) 修订 ::= (版本?,日期) 前言 ::= (段落) 章节 ::= (标题,段落?,(章节)*) 段落 ::= ((区块标题?,区块)|宏块)+ 区块 ::= (自然段|独立块|列表|表格) 列表 ::= (无序列表|有序列表|定义列表|标注列表) 无序列表 ::= (项目)+ 有序列表 ::= (项目)+ 标注列表 ::= (项目)+ 定义列表 ::= (条目)+ 条目 ::= (标签,项目) 标签 ::= (项目+) 项目 ::= (项目文本,(列表|段落列表|列表后续)*)
注释:
-
'?' 表示0或1个，'+' 表示0或多个，'*' 表示1或多个。
-
所有的基本区块有独立的界线分开.
-
下面的基本部分不能包含空行: 头部，标题，段落，项目文本。
头部包含文档标题、作者和版本信息。头部可选但是必须在文档的顶部。
= 使用 AsciiDoc 编写文档 = Joe Bloggs <jbloggs@mymail.com> v2.0, February 2003: Rewritten for version 2 release.
需要靠左边顶格
= 文档标题 (0级) = == 段落标题 (1级) == === 段落标题 (2级) === ==== 段落标题 (3级) ==== ===== 段落标题 (4级) =====
.段落，列表，表格或区块标题
下面的格式标签前后要有空格，没有空格的时候需要是双符号。
_强调_ 强调
\'强调' '强调'
*粗体* 粗体
+等宽字体+ 等宽字体
`等宽字体` 等宽字体 里面的格式命令无效
\`单引号引用' `单引号引用'
\``双引号引用'' ``双引号引用''
#无格式文本# 无格式文本 里面的格式命令无效
[字体CSS颜色,背景CSS颜色,文字em大小] 使用在格式前面可以显示颜色和大小可以使用[,,2]的形式
^上标\^ 上标
~下标\~ 下标
(C) © 版权
(TM) ™ 商标
(R) ® 注册商标
-- -- 破折号
... …省略号
-> → 右箭头
<- ← 左箭头
=> ⇒ 右双箭头
<= ⇐ 左双箭头
➊ ➊
¶ ¶
//// CommentBlock（注释块）不输出到目标文件 ////
++++ PassthroughBlock，不转换内部的特殊字符 ++++
---- ListingBlock（清单块） 用于计算机的输出和文件列表。也可用于程序代码。里面特殊字符不替换。 ----
.... LiteralBlock（文字块） 就像普通文字段落，保留了空格，使用[listing]块标题可以在内部引用其他块样式。 ....
**** SidebarBlock（侧边栏） 有边框和背景 ****
____ QuoteBlock（引用块） ____
==== ExampleBlock（例子块） 会使用数字编号的例子标题[caption="例1: "] 可以使用NOTE, TIP, IMPORTANT, WARNING, CAUTION标题[NOTE]表示提示块 ====
-- OpenBlock（开放块） --
'Tip’提示, 'Note’注意, 'Important’重要, 'Warning’警告 和 'Caution’警示。例子：
NOTE: 这是一个注意的例子。
或使用替代语法:
[NOTE] 这是一个注意的例子。
|
提示
|
如果警告多于一个段落使用警告段落替代. |
|
注意
|
警告可以定制 icons, iconsdir, icon 和 caption 参数。
|
默认生成文本标题替换图标链接，生成图标链接需要使用`-a icons`命令行参数。 你可以使用`icon`参数制定图标的路径。例如：
[icon="./images/icons/wink.png"] NOTE: What lovely war.
使用 caption 参数定义警告标题下例屏蔽图标并定义了注释警告的标题（在警告图标设置为可用时`icons` 参数必须设置为`icons=None`）：
[icons=None, caption="特殊提示"] NOTE: This is my special note.
手动序号序号使用下面一种
1. 阿拉伯数字标注的列表项目. a. 小写字母标注的列表项目. F. 大写字母标注的列表项目. iii) 小写罗马数字标注的列表项目. IX) 大写罗马数字标注的列表项目.
自动符号列表项目是1-5个句点，跟着是一些空格和文本。句点个数表示级别。例如：
. 阿拉伯数字标注的列表项目. .. 小写字母标注的列表项目. ... 小写罗马数字标注的列表项目. .... 大写字母标注的列表项目. ..... 大写罗马数字标注的列表项目.
字母或数字开始1-4个冒号或两个分号结束。
项目1::
项目2::
项目说明.
项目说明.
项目3:: 项目说明.
* 列表项.
* 列表项.
项目4::
说明1.
二级项目;;
二级说明.
二级项目;;
二级说明.
二级项目;;
二级说明.
三级项目::: 三级说明.
三级项目::: 三级说明.
*水平项目*:: 水平说明.
水平说明.
A footnote footnote:[An example footnote.]; a second footnote with a reference ID footnoteref:[note2,Second footnote.]; finally a reference to the second footnote footnoteref:[note2].
'http'，'https'，'ftp'，'file'，'mailto’和’callto’超链接。直接书写就行，参数是显示名称，空格使用%20。
http://www.methods.co.nz/asciidoc/[The AsciiDoc home page] http://www.methods.co.nz/asciidoc/ mailto:joe.bloggs@foobar.com[email Joe Bloggs] joe.bloggs@foobar.com
[width="40%",cols="^,2m",frame="topbot",options="header,footer"] |====================== |Column 1 |Column 2 |1 |Item 1 |2 |Item 2 |3 |Item 3 |6 |Three items |======================
表格参数：
frame边框topbot(上和下)，all(全部边，默认), none and sides (左和右)。 align对齐left，right和center。 options选项header（有标题）footer（有底部） width宽度1-99%
行参数：
[<multiplier>*][<align>][<width>][<style>] 左缩进，对齐，宽度，样式
单元格参数：
[<span>*|+][<align>][<style>] *缩进，+合并 span语法[水平][.垂直]参数中<，^和>分别表示水平左中右和垂直上中下。
{include:<filename>} 得到`<filename>`的内容。
{sys:<command>} 得到执行脚本命令`<command>`的标准输出。
{sys2:<command>} 得到执行脚本命令`<command>`的标准输出和标准错误。
{sys3:<command>} 直接输出结果不进行任何处理。
{amp} 显示字符 (&)
{asciidoc-dir} asciidoc(1)程序文件夹
{asciidoc-file} asciidoc(1)脚本的完整路径
{asciidoc-version} asciidoc(1)的版本
{author} 作者姓名
{authored} 空字符串 '' 如果 {author} 或 {email} 已经指定,
{authorinitials} 作者缩写 (from document header)
{backend-<backend>} 空字符串 ''
{<backend>-<doctype>} 空字符串 ''
{backend} document backend specified by `-b` option
{backslash} 反斜杠
{basebackend-<base>} 空字符串 ''
{basebackend} html 或 docbook
{brvbar} 竖线 (|)
{revdate} 文档修订日期 (from document header)
{docdate} 文档最后修改日期
{doctime} 文档最后修改时间
{docname} 文档文件名不含扩展名
{docfile} 文档文件名 (note 5)
{docdir} document input directory name (note 5)
{doctitle} 文档标题 (from document header)
{doctype-<doctype>} 空字符串 ''
{doctype} 文档类型使用`-d`设置指定
{email} 作者email (from document header)
{empty} 空字符串 ''
{encoding} 指定输入输出编码
{filetype-<fileext>} 空字符串 ''
{filetype} 输出文件的扩展名
{firstname} 作者名字 (from document header)
{gt} 大于号 (>)
{id} running block id generated by BlockId elements
{indir} 输出文件的文件夹名称 (note 2,5)
{infile} 输入文件名称 (note 2,5)
{lastname} 作者姓氏 (from document header)
{level} 标题级别 1..4 (in section titles)
{listindex} the list index (1..) of the most recent list item
{localdate} 当前日期
{localtime} 当期时间
{lt} 小于号 (<)
{manname} manpage name (defined in NAME section)
{manpurpose} manpage (defined in NAME section)
{mantitle} document title minus the manpage volume number
{manvolnum} manpage volume number (1..8) (from document header)
{middlename} 作者中间名 (from document header)
{nbsp} 空格
{outdir} 文档输出文件夹名 (note 2)
{outfile} 输出文件名 (note 2)
{reftext} running block xreflabel generated by BlockId elements
{revnumber} 文档修订版本号 (from document header)
{sectnum} formatted section number (in section titles)
{showcomments} 在输出文件中显示注释行
{title} 章节标题 (in titled elements)
{two_colons} 双冒号
{two_semicolons} 双分号
{user-dir} ~/.asciidoc文件夹 (如果存在)
{verbose} defined as '' if --verbose command option specified