本文翻译自 AsciiDoc Syntax Quick Reference 。
段落
段落在 AsciiDoc 中不需要任何特殊标记。 段落就是一段或多行连续的文本。 要开始一个新的段落，至少用一个空行隔开它。
查看效果 段落
段落在 AsciiDoc 中不需要任何特殊标记。 段落就是一段或多行连续的文本。
要开始一个新的段落，至少用一个空行隔开它。
一个正常的段落。 一个文字段落。 可以单行或连续多行，至少有一个空格缩进。 文本以等宽字体（通常为 monospace）显示。 行被预格式化（即：在源代码中格式化） 空 格 和 换行符， 就像这句话， 将被保留。
查看效果 文字段落
一个正常的段落。
一个文字段落。 可以单行或连续多行，至少有一个空格缩进。
文本以等宽字体（通常为 monospace）显示。 行被预格式化（即：在源代码中格式化） 空 格 和 换行符， 就像这句话， 将被保留。
玫瑰是红色的， + 紫罗兰是蓝色的。 [%hardbreaks] Ruby 是红的。 Java 是黑的。
查看效果 硬换行符
玫瑰是红色的，
紫罗兰是蓝色的。
Ruby 是红的。
Java 是黑的。
[.lead] 这段文字将作为开头段落（即，更大的字体）。 这段文字不会。
查看效果 导语
这段文字将作为开头段落（即，更大的字体）。
这段文字不会。
| 如果在序言的第一段上没有指定任何角色，默认的 Asciidoctor 样式表会自动将该段作为导语。 |
文本格式
它对我有 *很强* 的意义。 这一点我再 _强调_ 也不为过。 键入 `OK` 以接受 那 *_真的_* 必须走。 不能选择一个？让我们 `*_都_*` 用上。
查看效果 有约束的粗体、斜体、等宽字体
它对我有 很强 的意义。
这一点我再 强调 也不为过。
键入 OK 以接受
那 真的 必须走。
不能选择一个？让我们 都 用上。
**C**reate, **R**ead, **U**pdate, and **D**elete (CRUD) That's fan__freakin__tastic! Don't pass generic ``Object``s to methods that accept ``String``s! It was Beatle**__mania__**!
查看效果 无约束的粗体、斜体、等宽字体
Create, Read, Update, and Delete (CRUD)
That’s fanfreakintastic!
Don’t pass generic Objects to methods that accept Strings!
It was Beatlemania!
狼人对 #肉桂# 过敏。 ##Mark##up refers to text that contains formatting ##mark##s. 所有的 [.underline]#核心# 都去了哪里？ 我们需要 [.line-through]#十个# 二十个虚拟机。 主题必须实现 [.myrole]#自定义角色# 。
查看效果 高亮、下划线、删除线、自定义角色
狼人对 肉桂 过敏。
Markup refers to text that contains formatting marks.
所有的 核心 都去了哪里？
我们需要 十个 二十个虚拟机。
主题必须实现 自定义角色 。
^上^标短语 ~下~标短语
查看效果 上标与下标
上标短语
下标短语
"`双引号`" '`单引号`' Olaf's desk was a mess. A ``std::vector```'s size is the number of items it contains. All of the werewolves`' desks were a mess. Olaf had been with the company since the `'00s.
查看效果 智能引号和撇号
“双引号”
‘单引号’
Olaf’s desk was a mess.
A std::vector’s size is the number of items it contains.
All of the werewolves’ desks were a mess.
Olaf had been with the company since the ’00s.
链接
https://asciidoctor.org - automatic! https://asciidoctor.org[Asciidoctor] 请参阅 <<_段落>> 了解如何编写段落。 了解如何将文档组织为多个 <<section-titles, 章节>> 。 devel@discuss.example.org mailto:devel@discuss.example.org[Discuss] mailto:join@discuss.example.org[Subscribe,Subscribe me,I want to join!]
查看效果 自动链接、 URL 宏、 mailto 宏
https://discuss.asciidoctor.org[Discuss Asciidoctor,role=external,window=_blank] https://discuss.asciidoctor.org[Discuss Asciidoctor^]
当目标以类似 https: 的 URL 方案开头时，link: 宏前缀不是必须的。
URL 方案充当隐式宏前缀。
|
| 如果链接文本包含逗号，并且文本后跟一个或多个命名属性，则必须将文本括在双引号中。 否则，文本将在逗号上切断（其余文本将被拉入属性解析）。 |
link:++https://example.org/?q=[a b]++[URL with special characters] https://example.org/?q=%5Ba%20b%5D[URL with special characters]
link:index.html[Docs]
link:\\server\share\whitepaper.pdf[Whitepaper]
[[bookmark-a]]内联锚点使任意内容可引用。 [#bookmark-b]#内联锚点可以应用于这样的短语。# anchor:bookmark-c[]使用交叉引用链接到此位置。 [[bookmark-d,最后一段]]xreflabel 属性将用作交叉参考链接中的链接文本。
https://asciidoctor.org - automatic! https://asciidoctor.org[Asciidoctor] 请参阅 <<_段落>> 了解如何编写段落。 了解如何将文档组织为多个 <<section-titles, 章节>> 。
查看效果 交叉引用
有关更多信息，请参阅 xref:document-b.adoc#section-b[Section B of Document B] 。 如果你从不返回 xref:document-b.adoc[Document B]，我们会发送帮助。
文档页眉
文档页眉 是可选的。 页眉不能包含任何空行，且必须用至少一个空行将内容分隔开。
= 文档标题 本文档提供……
= 文档标题 作者名 <author@email.org>; 作者名 <author@email.org> 本文档提供……
= 文档标题 作者名 <author@email.org> v2.0, 2019-03-22 本文档提供……
= 文档标题 作者名 <author@email.org> v2.0, 2019-03-22 :toc: :homepage: https://example.org This document provides...
章节标题
当文档类型为 article （默认）时，该文档只能具有一个 0 级标题（=），即章节标题（即，doctitle）。
= 文档标题（零级） == 一级章节标题 === 二级章节标题 ==== 三级章节标题 ===== 四级章节标题 ====== 五级章节标题 == 另一个一级章节标题 = 参考文档 开发项目负责人 这是项目 X 的文档。 include::basics.adoc[] include::installation.adoc[] include::example.adoc[]
查看效果 文章的章节等级
book 类型的文档可以有额外的 0 级章节标题，它们被解释为 部。
至少有一部的存在会隐式地使文档成为具有多部的书。
= 文档标题（零级） == 一级章节标题 = 零级章节标题（部） == 一级章节标题 === 二级章节标题 ==== 三级章节标题 ===== 四级章节标题 ====== 五级章节标题 = 另一个零级章节标题（部）
[discrete] === 这是一个独立的页眉！
包含
= 文档标题（零级） == 一级章节标题 === 二级章节标题 ==== 三级章节标题 ===== 四级章节标题 ====== 五级章节标题 == 另一个一级章节标题 = 参考文档 开发项目负责人 这是项目 X 的文档。 include::basics.adoc[] include::installation.adoc[] include::example.adoc[]
include::filename.txt[tag=definition] include::filename.txt[lines=5..10]
包含来自 URL 的内容有潜在的危险，因此如果安全模式为 SECURE 或更高，将禁用该功能。
假设安全模式小于 SECURE，那么还必须设置 allow-uri-read 属性以允许 AsciiDoc 处理器从 URL 读取内容。
|
列表
* 列表项 ** 嵌套列表项 *** 嵌套列表项 * 列表项 ** 另一个嵌套列表项 * 列表项
查看效果 无序列表
-
列表项
-
嵌套列表项
-
嵌套列表项
-
-
-
列表项
-
另一个嵌套列表项
-
-
列表项
在列表之前和之后，需要一个空行才能将其与其他块分开。
可以通过在第二个列表上方添加一个空属性列表（即 []）或通过插入空行，然后在第一个列表之后插入注释行来强制分隔两个相邻列表。
如果使用注释行，惯例是使用 //- 向其他作者提供提示，即它是列表分隔线。
|
* 一级列表项 ** 二级列表项 *** 三级列表项 **** 四级列表项 ***** 五级列表项 * 一级列表项
查看效果 无序列表最大级别嵌套
-
一级列表项
-
二级列表项
-
三级列表项
-
四级列表项
-
五级列表项
-
-
-
-
-
一级列表项
可以使用列表样式（例如：square）更改 无序的列表标记 。
. Step 1 . Step 2 .. Step 2a .. Step 2b . Step 3
查看效果 有序列表
-
Step 1
-
Step 2
-
Step 2a
-
Step 2b
-
-
Step 3
* 一级列表项 ** 二级列表项 *** 三级列表项 **** 四级列表项 ***** 五级列表项 * 一级列表项
查看效果 Ordered list max level nesting
-
一级列表项
-
二级列表项
-
三级列表项
-
四级列表项
-
五级列表项
-
-
-
-
-
一级列表项
Ordered lists support numeration styles such as lowergreek and decimal-leading-zero.
link:lists:example$checklist.adoc[tag=check]
link:lists:example$description.adoc[tag=qr-base]
link:lists:example$description.adoc[tag=qa]
link:lists:example$description.adoc[tag=3-mix]
| Lists can be indented. Leading whitespace is not significant. |
link:lists:example$complex.adoc[tag=b-complex]
Images
You can use the imagesdir attribute to avoid hard coding the common path to your images in every image macro.
The value of this attribute can be an absolute path, relative path, or base URL.
If the image target is a relative path, the attribute’s value is prepended (i.e., it’s resolved relative to the value of the imagesdir attribute).
If the image target is a URL or absolute path, the attribute’s value is not prepended.
link:macros:example$image.adoc[tag=base] link:macros:example$image.adoc[tag=alt] link:macros:example$image.adoc[tag=attr] link:macros:example$image.adoc[tag=ab-url]
查看效果 Block image macro
Two colons following the image keyword in the macro (i.e., image::) indicates a block image (aka figure), whereas one colon following the image keyword (i.e., image:) indicates an inline image.
(All macros follow this pattern).
You use an inline image when you need to place the image in a line of text.
Otherwise, you should prefer the block form.
link:macros:example$image.adoc[tag=inline]
link:macros:example$image.adoc[tag=in-role]
link:macros:example$image.adoc[tag=data]
When the data-uri attribute is set, all images in the document—including admonition icons—are embedded into the document as {url-data-uri}[data URIs].
You can also pass it as a command line argument using -a data-uri.
Audio
link:macros:example$audio.adoc[tag=basic] link:macros:example$audio.adoc[tag=attrs]
You can control the audio settings using additional attributes and options on the macro.
Videos
link:macros:example$video.adoc[tag=base] link:macros:example$video.adoc[tag=attr]
link:macros:example$video.adoc[tag=youtube]
link:macros:example$video.adoc[tag=vimeo]
You can control the video settings using additional attributes and options on the macro.
Keyboard, button, and menu macros
You must set the experimental attribute in the document header to enable these macros.
|
link:macros:example$ui.adoc[tag=qr-key]
Literals and source code
link:pass:example$pass.adoc[tag=backtick-plus]
link:verbatim:example$literal.adoc[tag=b-imp-code]
link:verbatim:example$literal.adoc[tag=b-block]
link:verbatim:example$listing.adoc[tag=qr-listing]
查看效果 Listing block with title
link:verbatim:example$listing.adoc[tag=qr-listing]
.Some Ruby code link:verbatim:example$source.adoc[tag=src-base]
查看效果 Source block with title and syntax highlighting
|
You must enable source highlighting by setting the :source-highlighter: rouge See asciidoctor:syntax-highlighting:index.html to learn which values are accepted when using Asciidoctor. |
link:verbatim:example$callout.adoc[tag=b-src]
link:verbatim:example$callout.adoc[tag=b-nonselect]
link:verbatim:example$source.adoc[tag=src-inc]
link:verbatim:example$source.adoc[tag=rel]
link:verbatim:example$source.adoc[tag=ind]
|
The indent attribute is frequently used when including source code by tagged region or lines. It can be specified on the include directive itself or the enclosing literal, listing, or source block. When indent is 0, the leading block indent is stripped. When indent is greater than 0, the leading block indent is first stripped, then a block is indented by the number of columns equal to this value. |
link:verbatim:example$source.adoc[tag=src-para]
Admonitions
link:blocks:example$admonition.adoc[tag=b-para]
link:blocks:example$admonition.adoc[tag=b-bl]
More delimited blocks
Any block can have a title, positioned above the block. A block title is a line of text that starts with a dot. The dot cannot be followed by a space.
link:blocks:example$example.adoc[tag=base]
link:blocks:example$quote.adoc[tag=bl] link:blocks:example$quote.adoc[tag=para] link:blocks:example$quote.adoc[tag=no-cite] link:blocks:example$quote.adoc[tag=link-text] link:blocks:example$quote.adoc[tag=abbr]
查看效果 Blockquotes
link:blocks:example$open.adoc[tag=base] link:blocks:example$open.adoc[tag=src]
link:pass:example$pass.adoc[tag=b-bl]
Tables
link:tables:example$table.adoc[tag=b-base-h-co]
| 1 | Unless the cols attribute is specified, the number of columns is equal to the number of cell separators on the first (non-empty) line. |
| 2 | When an empty line immediately follows a non-empty line at the start of the table, the cells in the first line get promoted to the table header. |
link:tables:example$table.adoc[tag=b-col-h-co]
| 1 | The * in the cols attribute is the repeat operator.
It means repeat the column specification across the remaining columns.
In this case, we are repeating the default formatting across 2 columns.
When the cells in the header are not defined on a single line, you must use the cols attribute to set the number of columns in the table and the %header option (or options=header attribute) to promote the first row to the table header. |
link:tables:example$table.adoc[tag=b-col-indv-co]
| 1 | In this example, the cols attribute has two functions.
It specifies that this table has three columns, and it sets their relative widths. |
link:tables:example$table.adoc[tag=b-col-a]
link:tables:example$data.adoc[tag=s-csv]
link:tables:example$data.adoc[tag=csv]
link:tables:example$data.adoc[tag=i-csv]
link:tables:example$data.adoc[tag=s-dsv]
link:tables:example$cell.adoc[tag=b-spec]
IDs, roles, and options
[#goals.incremental] * Goal 1 * Goal 2
|
[id="goals",role="incremental"] * Goal 1 * Goal 2
[#null-values] == Primitive types and null values
[#id-name.role-name]`monospace text` [#free-world.goals]*free the world*
[%header%footer%autowidth] |=== |Header A |Header B |Footer A |Footer B |===
[options="header,footer,autowidth"] |=== |Header A |Header B |Footer A |Footer B |=== // options can be shorted to opts [opts="header,footer,autowidth"] |=== |Header A |Header B |Footer A |Footer B |===
Comments
// A single-line comment //// A multi-line comment. Notice it's a delimited block. ////
Breaks
before ''' after
查看效果 Thematic break (aka horizontal rule)
before
after
<<<
Attributes and substitutions
:url-home: https://asciidoctor.org
:link-docs: https://asciidoctor.org/docs[documentation]
:summary: AsciiDoc 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!
查看效果 Attribute declaration and usage
Check out Asciidoctor! AsciiDoc 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. Be sure to read the documentation too! [✔] That’s done! |
To learn more about the available attributes and substitution groups see:
link:attributes:example$counter.adoc[tag=base]
Text replacements
Any named, numeric or hexadecimal {url-char-xml}[XML character reference^] is supported.
Escaping substitutions
link:subs:example$subs.adoc[tag=backslash]
link:pass:example$pass.adoc[tag=plus]
link:pass:example$pass.adoc[tag=b-3p-macro]
Markdown compatibility
Markdown compatible syntax is an optional feature of the AsciiDoc language and is currently only available when using Asciidoctor.
link:verbatim:example$source.adoc[tag=fence]
link:blocks:example$quote.adoc[tag=md]
link:blocks:example$quote.adoc[tag=md-alt]
--- - - - *** * * *