来源头条作者:骑单车去带娃
1. AsciiDoc 简介
AsciiDoc 是一种文本文档格式（轻量级的标记语言），用于编写注释、文档、文章、书籍、电子书、幻灯片、网页、手册页和博客。
AsciiDoc 文件可以翻译成多种格式，包括 HTML、PDF、EPUB、手册页面等。
AsciiDoc 是高度可配置的，用户可以定制和扩展 AsciiDoc 源文件语法和后端输出标记（几乎可以是任何类型的 SGML/XML 标记）。
AsciiDoc 是免费软件，并根据 GNU 通用公共许可证版本 2（GPLV2）的条款进行许可。
1.1 语法
1.1.1 文档头
可以包含文档头、作者、修订行、自定义属性等。
头部可选但是必须在文档的顶部。
= My Document\’s Title
Doc Writer
v1.0, 2018-04-11
:toc:
:imagesdir: assets/images
:homepage: https://asciidoctor.org
My document provides…
1.1.2 标题
需要靠左侧顶格。
可以包含文档头、第 1 ~ 第 5 章节标题。
当使用项目文档类型（默认值）时，只能有一个 0 级的节标题（即，文档标题），并且它必须位于文档头中。
等号的数目与 HTML 输出中的标题级别相匹配。
例如，（=）转换成为
标签。
= 文档标题 (0级) =
== 段落标题 (1级) ==
=== 段落标题 (2级) ===
==== 段落标题 (3级) ====
===== 段落标题 (4级) =====
1.1.3 段落
段落不需要任何特殊的标记，段落只需要是连续文本的一行或多行。
开始新的段落需要用一个空行进行分隔。
文档中的大部分内容是段落文本，因此 AsciiDoc 不需要任何特殊的标记或属性来指定段落内容。
Paragraphs don’t require any special markup in AsciiDoc. A paragraph is just one or more lines of consecutive text.
To begin a new paragraph, separate it by at least one blank line. Newlines within a paragraph are not displayed.
1.1.3.1 换行
在 AsciiDoc 中，相邻或连续的文本行形成段落元素。若要在另一个元素（如节标题或表）之后开始新的段落，则插入空行，然后继续键入内容即可。
因为 AsciiDoc 转换文档时，相邻的文本行会被合并为单个段落，这意味着可以包装段落文本或将每个句子或短语放在单独的行上，输出中是不会出现换行的。
如果希望保留段落中的换行符，可以使用加号 （+） 后的空格或 hardbreaks 属性。这样会导致每一行之后增加可见的换行标记（例如
）。
Rubies are red, +
Topazes are blue.
[%hardbreaks]
Ruby is red.
Java is black.
通过将 hardbreaks 属性添加到文档头部，可以在整个文档中保留换行符。
:hardbreaks:
……
Rubies are red,
Topazes are blue.
1.1.3.2 文字段落
由至少一个空间偏移的段落成为文字段落，文字段落中的所有行必须是相邻的。
文本段落显示为预格式化文本，文本以固定宽度字体显示，空格和换行符都会被保留下来。
1.1.3.3 提示段落
主要是为了引起读者注意，用标签开头。
标签必须大写，后面跟着冒号（：）。
标签说明 NOTE 注释，TIP 提示，WARNING 警告，IMPORTANT 重要，CAUTION 注意。
TIP: Pro tip…
IMPORTANT: Don\’t forget…
WARNING: Watch out for…
CAUTION: Ensure that…
当想对复杂内容应用警告时，可以将标签设置为块上的样式属性。
下例是在分隔块上的属性列表中设置标签，标签必须大写。
[IMPORTANT]
.Feeding the Werewolves
====
While werewolves are hardy community members, keep in mind the following dietary concerns:
. They are allergic to cinnamon.
. More than two glasses of orange juice in 24 hours makes them howl in harmony with alarms and sirens.
. Celery makes them sad.
====
可以使用 icons 参数制定图标的路径。
[icons=\”./images/icons/wink.png\”]
NOTE: What lovely war.
使用 caption 参数定义警告标题返回的文本信息（在警告图标设置为可用时 icons 参数必须设置为 icons=None）。
[icons=None, caption=\”特殊提示\”]
NOTE: This is my special note.
1.1.3.3.1 图标
AsciiDoc 提供三种显示图标的策略。
作为文本
作为图像
作为从图标字体中选择的字符。
使用图标属性控制策略。默认行显示返回的文本。
如果希望使用图像显示图标，可以在文档头中将图标属性设置为空值。如果正在转换为 DocBook，或者希望使用一种简单的方法使 HTML 可以脱机查看，则建议采用此策略。DocBook 工具链提供了警告和标注等图标的图像，这些图标可以用自己的自定义图标替换。如果使用内联图标宏，则需要为这些图标提供图像。
也可以使用字体图标设置为 AsciiDoc 图标，若要使用此特性，需要将图标文件属性的值设置为文档标题中的字体。可以从 Awesome 中获得更多的字体图标。这种方式默认情况下需要在线访问。
= Document Title
:icons: font
……
NOTE: Asciidoctor supports font-based admonition icons, powered by Font Awesome!
HTML 格式输出。
Asciidoctor supports font-based admonition icons, powered by Font Awesome!
AsciiDoc 中添加了 Awesome 的字体超强样式表和字体文件的引用。
1.1.3.3.2 Unicode 文本图标
代替图像或基于字体的图标，可以通过使用一个小技巧使用 Unicode 文本来表示警告图标。
如果在文档上没有设置图标属性，AsciiDoc 输出一个标识警告类型的文本标签。此标签的文本来自 AsciiDoc 属性。
属性的名称是
标题，其中
是小写中的警告类型。例如，提示提示的属性是提示字幕。
可以将一个 Unicode 字形赋值给这个属性，而不是单词。
:tip-caption:
[TIP]
It\’s possible to use Unicode glyphs as admonition icons.
HTML 格式输出。
1.1.3.3.3 内联图标
图标可以插入到段落内容的任意位置，内嵌宏。
icon:tags[] ruby, asciidoctor
HTML 格式输出。
ruby, asciidoctor
内联图标宏和角色语法。
icon:tags[role=\”blue\”] ruby, asciidoctor
图标大小
默认为 1x
icon:heart[2x]
icon:heart[size=2x]
图标旋转和翻转
icon:shield[rotate=90, flip=vertical]
链接
icon:download[link=\”http://rubygems.org/downloads/asciidoctor-1.5.2.gem\”]
1.1.3.4 引文段落
将引文样式应用到任何段落，它将使用更大的字体大小。
自动将引文段落进行样式化。
可以采用 （.） 的方式设置引文角色和分配到段落上。
当将文档转换为 HTML 并使用默认样式表查看时，前导的第一段将自动样式化为前导段。
[.lead]
This text will be styled as a lead paragraph (i.e., larger font).
1.1.4 块结构
任何块都可以有一个标题，位于块的上方。块标题是从一个点开始的文本行。
1.1.4.1 文本块
文字块定义为三种方式
用一个或多个空格缩进段落的第一行。
将文字属性应用于段落或区块。
使用文字块定界符（…）。
error: The requested operation returned error: 1954 Forbidden search for defensive operations manual
absolutely fatal: operation initiation lost in the dodecahedron of doom
would you like to die again? y/n
….
Lazarus: Where is the *defensive operations manual*?
Computer: Calculating …
Can not locate object that you are not authorized to know exists.
Would you like to ask another question?
Lazarus: Did the werewolves tell you to say that?
Computer: Calculating …
….
注意：在输出中，粗体文本格式没有应用于文本。
当希望整个文本块是文本，并且不希望缩进时，可在元素的顶部设置文本属性。
[literal]
error: The requested operation returned error: 1954 Forbidden search for defensive operations manual
absolutely fatal: operation initiation lost in the dodecahedron of doom
would you like to die again? y/n
1.1.4.2 注释块
不会输出到目标文件。
行注释
行注释可用于分割元素，如两个相邻列表。
// A single-line comment.
块注释
////
CommentBlock
////
1.1.4.3 清单块（列表块）
用于计算机的输出和文件列表、可用于程序代码。
里面特殊字符不替换。
列表块内容被转换为
文本。
列表块中的内容只受特殊字符和标注替换的限制。
列表块名称应用于内容的两种方式。
在元素上设置列表属性。
包含分隔符列表块中的内容。
将列表块名称应用于元素，例如段落，通过在该元素上设置列表属性。
[listing]
This is an example of a paragraph styled with `listing`.
Notice that the monospace markup is preserved in the output.
包含分隔的列表块由四个连字符（—-）组成的行包围。
列表块有利于显示原始源代码，尤其是与源代码和源代码突出显示器属性一起使用时。
.app.rb
[source,ruby]
—-
require \’sinatra\’
get \’/hi\’ do
\”Hello World!\”
end
具有自定义替换语法的列表块。
:version: 1.5.6.1
[source,xml,subs=\”verbatim,attributes\”]
—-
org.asciidoctor
asciidoctor-java-integration
{version}
—-
滚动支持
nowrap 会增加（css 样式 white-space:nowrap 和 word-wrap: normal）到
元素上。
[source%nowrap,java]
—-
public class ApplicationConfigurationProvider extends HttpConfigurationProvider
{
@Override
public Configuration getConfiguration(ServletContext context)
{
return ConfigurationBuilder.begin()
.addRule()
.when(Direction.isInbound().and(Path.matches(\”/{path}\”)))
.perform(Log.message(Level.INFO, \”Client requested path: {path}\”))
.where(\”path\”).matches(\”.*\”);
}
}
—-
全局强制不换行 ，可以设置 prewrap 属性。
:prewrap!:
带标题的列表块
.Gemfile.lock
—-
GEM
remote: https://rubygems.org/
specs:
asciidoctor (1.5.6.1)
PLATFORMS
ruby
DEPENDENCIES
asciidoctor (~> 1.5.6.1)
—-
带标注的代码块
[source,ruby]
—-
require \’sinatra\’ //
get \’/hi\’ do //
\”Hello World!\” //
end
—-
Library import
URL mapping
HTTP response body
带不可选择标注的代码块
—-
line of code //
line of code #
line of code ;;
—-
A callout behind a line comment for C-style languages.
A callout behind a line comment for Ruby, Python, Perl, etc.
A callout behind a line comment for Clojure.
具有不可选标注的 XML 代码块
[source,xml]
—-
Section Title
—-
The section title is required.
直接引入源文件的代码块
[source,ruby]
—-
include::app.rb[]
—-
源文件相对源目录的代码块
:sourcedir: src/main/java
[source,java]
—-
include::{sourcedir}/org/asciidoctor/Asciidoctor.java[]
—-
引入源文件一部分的代码块
[source,ruby,indent=0]
—-
include::lib/document.rb[lines=5..10]
—-
无分隔符的代码块
[source,xml]
This is normal content.
代码列表块启动语法高亮可以在文档头中设置。
高亮属性有 coderay、highlightjs、prettify 和 pygments。
:source-highlighter: pygments
1.1.4.4 侧边栏块
有边框显示。
.AsciiDoc history
****
AsciiDoc was first released in Nov 2002 by Stuart Rackham.
It was designed from the start to be a shorthand syntax
for producing professional documents like DocBook and LaTeX.
****
1.1.4.5 引用文本块
文本块左上角显示一个双引号图片。
____
QuoteBlock
____
负责引用块
[quote, Abraham Lincoln, Address delivered at the dedication of the Cemetery at Gettysburg]
____
Four score and seven years ago our fathers brought forth
on this continent a new nation…
____
[quote, Albert Einstein]
A person who never made a mistake never tried anything new.
____
A person who never made a mistake never tried anything new.
____
[quote, Charles Lutwidge Dodgson, \’Mathematician and author, also known as http://en.wikipedia.org/wiki/Lewis_Carroll[Lewis Carroll]\’]
____
If you don\’t know where you are going, any road will get you there.
____
缩写块引用（只有 Asciidoctor 支持）
\”I hold it that a little rebellion now and then is a good thing,
and as necessary in the political world as storms in the physical.\”
— Thomas Jefferson, Papers of Thomas Jefferson: Volume 11
空引用
[, James Baldwin]
\”\”
Not everything that is faced can be changed.
But nothing can be changed until it is faced.
\”\”
1.1.4.6 案例文本块
可以使用 NOTE、TIP、IMPORTANT、WARNING、CAUTION 显示提示块。
====
ExampleBlock
====
1.1.4.7 混合使用
.Sample document
====
Here\’s a sample AsciiDoc document:
[listing]
….
= Title of Document
Doc Writer
:toc:
This guide provides…
….
The document header is useful, but not required.
====
[NOTE]
====
An admonition block may contain complex content.
.A list
– one
– two
– three
Another paragraph.
====
1.1.4.8 开放块
—
An open block can be an anonymous container,
or it can masquerade as any other block.
—
[source]
—
puts \”I\’m a source block!\”
—
1.1.5 列表
1.1.5.1 有序列表
通过在第一个列表之后插入一个空白行和一行注释，可以将两个相邻的列表分开。-
约定使用（//）作为行注释向其他作者提供一个提示，即它是一个列表分隔符。
1. ***数字标注的列表项目.
a. 小写字母标注的列表项目.
F. 大写字母标注的列表项目.
iii) 小写罗马数字标注的列表项目.
IX) 大写罗马数字标注的列表项目.
1.1.5.2 无序列表
– List item.
* List item.
** List item.
*** List item.
**** List item.
***** List item.
1.1.5.3 自定义列表
字母或数字开始 1-4 个冒号或两个分号结束。
Operating Systems::
Linux:::
. Fedora
* Desktop
. Ubuntu
* Desktop
* Server
BSD:::
. FreeBSD
. NetBSD
Cloud Providers::
PaaS:::
. OpenShift
. CloudBees
IaaS:::
. Amazon EC2
. Rackspace
1.1.5.4 问答列表
[qanda]
What is Asciidoctor?::
An implementation of the AsciiDoc processor in Ruby.
What is the answer to the Ultimate Question?:: 42
1.1.5.5 复选框列表
* [*] checked
* [x] also checked
* [ ] not checked
* normal list item
1.1.5.6 单行标记
first term:: definition of first term
second term:: definition of second term
1.1.5.7 多行标记
first term::
definition of first term
second term::
definition of second term
1.1.5.8 专业术语列表
[glossary]
术语1::
解释1.
术语2::
解释2.
1.1.6 文本格式
1.1.6.1 粗体
*bold phrase* & **char**acter**s**
1.1.6.2 斜体
_italic phrase_ & __char__acter__s__
1.1.6.3 等宽字体
`monospace phrase` & “char“acter“s“
如果要在等宽字体中用到（{name}）这样的格式（需要直译），那么可以使用（+ 和 +）符号或者转义符（\\）。
You can reference the value of a document attribute using the syntax `+{name}+`, where `name` is the attribute name.
1.1.6.4 混合使用
`*_monospace bold italic phrase_*` & “**__char__**“acter“**__s__**“
1.1.6.5 标记字体（黄色背景）
Werewolves are allergic to #cassia cinnamon#.
1.1.6.6 字体缩小
Did the werewolves read the [.small]##small print##?
1.1.6.7 字体扩大
[.big]##O##nce upon an infinite loop.
1.1.6.8 删除线
We need [.line-through]#ten# make that twenty VMs.
1.1.6.9 下划线
Where did all the [.underline]#cores# run off to?
1.1.6.10 上标
^super^script phrase
1.1.6.11 下标
~sub~script phrase
1.1.6.12 智能引号
如果不希望应用智能引号，可以使用 （\\）进行转义。
\”`double curved quotes`\”
\’`single curved quotes`\’
Olaf\’s desk was a mess.
All of the werewolves`\’ desks were a mess.
Olaf had been with the company since the `\’60s.
“double curved quotes”
‘single curved quotes’
Olaf’s desk was a mess.
All of the werewolves’ desks were a mess.
Olaf had been with the company since the ’60s.
1.1.6.13 文本替换
符号显示说明(C)?版权(TM)?商标(R)?注册商标…?…省略号->→右箭头
?右双箭头<=?左双箭头??数字–—破折号（只能在两个字符之间使用）
文本替换是指其字符的通用字符集 / Unicode 代码，使用格式。
https://en.wikipedia.org/wiki/List_of_XML_and_HTML_character_entity_references 可查询通用字符集。
hhhh;
1.1.7 其他标签
1.1.7.1 文件包含语句
如果不在相邻的文件包含语句之间插入空白行以保持内容分离，务必在源文档中添加空白行，以避免意外的结果，如吞并部分标题等。
= Reference Documentation
Lead Developer
This is documentation for project X.
include::basics.adoc[]
include::installation.adoc[]
include::example.adoc[]
包含 URL 文件
include::https://raw.githubusercontent.com/asciidoctor/asciidoctor/master/README.adoc[]
1.1.7.2 水平线
\’\’\’
1.1.7.3 分页符
<<<
1.1.7.4 超链接
外部链接
https://asciidoctor.org – automatic!
https://asciidoctor.org[Asciidoctor]
https://github.com/asciidoctor[Asciidoctor @ *GitHub*]
具有空格和特殊字符
link:++https://example.org/?q=[a b]++[URL with special characters]
link:https://example.org/?q=%5Ba%20b%5D[URL with special characters]
Windows 路径
link:\\\\server\\share\\whitepaper.pdf[Whitepaper]
相对路径
link:index.html[Docs]
电子邮件和 IRC
devel@discuss.arquillian.org
mailto:devel@discuss.arquillian.org[Discuss Arquillian]
mailto:devel-join@discuss.arquillian.org[Subscribe, Subscribe me, I want to join!]
irc://irc.freenode.org/#fedora
1.1.7.5 锚点
锚点：[[A88]]
链接：
>
1.1.7.6 图片
块图像
image::sunset.jpg[]
image::sunset.jpg[Sunset]
.A mountain sunset
[#img-sunset]
image::sunset.jpg[Sunset,300,200]
image::https://asciidoctor.org/images/octocat.jpg[GitHub mascot]
内联图
Click image:icons/play.png[Play, title=\”Play\”] to get the party started.
Click image:icons/pause.png[title=\”Pause\”] when you need a break.
具有定位角色的内联图
image:sunset.jpg[Sunset,150,150,role=\”right\”] What a beautiful sunset!
1.1.7.7 视频
块视频
video::video_file.mp4[]
video::video_file.mp4[width=640, start=60, end=140, options=autoplay]
1.1.7.8 源码
内联方式（等宽字体）
Reference code like `types` or `methods` inline.
内联方式（直译方法）
Output literal monospace text such as `+{backtick}+` by
enclosing the text in pluses, then again in backticks.
1.1.7.9 文档目录（ToC）
= AsciiDoc Writer\’s Guide
Doc Writer
v1.0, 2013-08-01
:toc: right
1.1.7.10 参考文献
_The Pragmatic Programmer_
> should be required reading for all developers.
To learn all about design patterns, refer to the book by the \”`Gang of Four`\”
>.
[bibliography]
== References
– [[[pp]]] Andy Hunt & Dave Thomas. The Pragmatic Programmer:
From Journeyman to Master. Addison-Wesley. 1999.
– [[[gof,2]]] Erich Gamma, Richard Helm, Ralph Johnson & John Vlissides. Design Patterns:
Elements of Reusable Object-Oriented Software. Addison-Wesley. 1994.
1.1.7.11 脚注
A statement.footnote:[Clarification about this statement.]
A bold statement!footnoteref:[disclaimer,Opinions are my own.]
Another bold statement.footnoteref:[disclaimer]
1.1.8 表格
除非指定了 cols 属性，否则列的数量等于块分隔符之间的第一行（非空）上的单元格分隔符字符的数量。
当空白行跟随第一个非空行时，第一行中的单元格将升迁到表标题。
.Table Title
|===
|Name of Column 1 |Name of Column 2 |Name of Column 3
|Cell in column 1, row 1
|Cell in column 2, row 1
|Cell in column 3, row 1
|Cell in column 1, row 2
|Cell in column 2, row 2
|Cell in column 3, row 2
|===
cols 属性中的（*）是重复运算符，意味着在列的其余部分重复列规范。
当头中的单元格没有在一行上定义时，必须使用 cols 属性设置表中的列数，使用 %header 选项（或 .=header 属性）将第一行提升到表头。
[%header,cols=2*]
|===
|Name of Column 1
|Name of Column 2
|Cell in column 1, row 1
|Cell in column 2, row 1
|Cell in column 1, row 2
|Cell in column 2, row 2
|===
下例中指定该表有三列，并设置它们的相对宽度。
[cols=\”1,1,2\”, options=\”header\”]
.Applications
|===
|Name
|Category
|Description
|Firefox
|Browser
|Mozilla Firefox is an open-source web browser.
It\’s designed for standards compliance,
performance, portability.
|Arquillian
|Testing
|An innovative and highly extensible testing platform.
Empowers developers to easily create real, automated tests.
|===
包含其他标签的表
[cols=\”2,2,5a\”]
|===
|Firefox
|Browser
|Mozilla Firefox is an open-source web browser.
It\’s designed for:
* standards compliance
* performance
* portability
http://getfirefox.com[Get Firefox]!
|===
CSV 格式的表
[%header,format=csv]
|===
Artist,Track,Genre
Baauer,Harlem Shake,Hip Hop
The Lumineers,Ho Hey,Folk Rock
|===
CSV 格式速记表（只有 Asciidoctor 支持）
,===
Artist,Track,Genre
Baauer,Harlem Shake,Hip Hop
,===
引入 CSV 文件表
|===
include::customers.csv[]
|===
DSV 数据使用速记表
:===
Artist:Track:Genre
Robyn:Indestructable:Dance
:===
带格式化、对齐和合并单元的表
[cols=\”e,m,^,>s\”, width=\”25%\”]
|===
|1 >s|2 |3 |4
^|5 2.2+^.^|6 .3+
m|7
^|8
|9 2+>|10
|===
1.1.9 属性
定义和使用
:url-home: https://asciidoctor.org
:link-docs: https://asciidoctor.org/docs[documentation]
:summary: Asciidoctor is a mature, plain-text document format for \\
writing notes, articles, documentation, books, and more. \\
It\’s also a text processor & toolchain for translating \\
documents into various output formats (i.e., backends), \\
including HTML, DocBook, PDF and ePub.
:checkedbox: pass:normal[{startsb}?{endsb}]
Check out {url-home}[Asciidoctor]!
{summary}
Be sure to read the {link-docs} too!
{checkedbox} That\’s done!
计数器属性
.Parts{counter2:index:0}
|===
|Part Id |Description
|PX-{counter:index}
|Description of PX-{index}
|PX-{counter:index}
|Description of PX-{index}
|===
1.1.10 直译方式
转移符直译
\\*Stars* is not rendered as bold text.
The asterisks around the word are preserved.
\\{author} is not resolved to the author name.
The curly brackets around the word are preserved.
`A\\–Z` connects A to Z in monospace using two dashes.
The dashes are not replaced by an em dash.
\\[[Word]] is not interpreted as an anchor.
The double brackets around the word are preserved.
[\\[[Word]]] is not interpreted as a bibliography anchor.
The triple brackets around the word are preserved.
In these cases, the backslash character is automatically removed.
（+）号直译
`+Text inside {plus} characters+` is not formatted.
However, special characters like ++ are still escaped.
pass 宏直译
pass:[
underline me
] is also underlined.
三（+）直译
+++
underline me
+++ is underlined.
1.2 兼容 Markdown
兼容 Markdown 标题
# Document Title (Level 0)
## Section Level 1
### Section Level 2
#### Section Level 3
##### Section Level 4
###### Section Level 5
兼容 Markdown 代码块
“`ruby
require \’sinatra\’
get \’/hi\’ do
\”Hello World!\”
end
\\“` \\\\ 去除第一个 \\ 符号
兼容 Markdown 引用块
> I hold it that a little rebellion now and then is a good thing,
> and as necessary in the political world as storms in the physical.
> — Thomas Jefferson, Papers of Thomas Jefferson: Volume 11
兼容 Markdown 引用块和块内容
> > What\’s new?
>
> I\’ve got Markdown in my AsciiDoc!
>
> > Like what?
>
> * Blockquotes
> * Headings
> * Fenced code blocks
>
> > Is there more?
>
> Yep. AsciiDoc and Markdown share a lot of common syntax already.
兼容 Markdown 水平线
—
– – –
***
* * *
参考资料
https://asciidoctor.org/docs/
