AsciiDoc 是一种轻量级标记语言,它可以让我们以纯文本的形式来书写笔记、文章、文档、书籍、网页、幻灯片和 man 帮助。 本指南是常用的 AsciiDoc 文档和文字格式化标记的快速参考。
这些例子主要关注生成的 HTML 后端。 AsciiDoc 生成 PDF、EPUB 和 DocBook 时,它们之间是互补的。 很多标注着 仅 _Asciidoctor 可用 的特性通过 Asciidoctor 项目提供的 AsciiDoc 配置文件 也可以在传统的 AsciiDoc Python 处理器中使用。 |
段落
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.
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.
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.
A normal paragraph. A sequence of lines that begin with at least one space is a literal paragraph. Literal paragraphs are treated as preformatted text. The text is shown in a fixed-width font and endlines are preserved. Another normal paragraph.
A normal paragraph.
A sequence of lines that begin with at least one space is a literal paragraph. Literal paragraphs are treated as preformatted text. The text is shown in a fixed-width font and endlines are preserved.
Another normal paragraph.
NOTE: An admonition paragraph draws the reader's attention to auxiliary information. Its purpose is determined by the label at the beginning of the paragraph. Here are the other built-in admonition types: TIP: Pro tip... IMPORTANT: Don't forget... WARNING: Watch out for... CAUTION: Ensure that...
An admonition paragraph draws the reader’s attention to auxiliary information. Its purpose is determined by the label at the beginning of the paragraph. |
Here are the other built-in admonition types:
Pro tip… |
Don’t forget… |
Watch out for… |
Ensure that… |
你也可以创建 警示块. |
[.lead] This text will be styled as a lead paragraph (i.e., larger font).
This text will be styled as a lead paragraph (i.e., larger font).
默认的 Asciidoctor 样式会自动将序文的第一段作为摘要段落。 |
格式化文本
_italic phrase_ __i__talic le__tt__ers *bold phrase* **b**old le**tt**ers *_bold italic phrase_* **__b__**old italic le**__tt__**ers `monospace phrase` and le``tt``ers `_monospace italic phrase_` and le``__tt__``ers `*monospace bold phrase*` and le``**tt**``ers `*_monospace bold italic phrase_*` and le``**__tt__**``ers
italic phrase
italic letters
bold phrase
bold letters
bold italic phrase
bold italic letters
monospace phrase
and lett
ers
monospace italic phrase
and lett
ers
monospace bold phrase
and lett
ers
monospace bold italic phrase
and lett
ers
Werewolves are #allergic to cinnamon#. Do werewolves believe in [small]#small print#? [big]##O##nce upon an infinite loop.
Werewolves are allergic to cinnamon.
Do werewolves believe in small print?
Once upon an infinite loop.
^super^script phrase ~sub~script phrase
superscript phrase
subscript phrase
'`single curved quotes`' "`double 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.
‘single curved quotes’
“double 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.
文档标题
标题是可选的。 |
标题不能包含空号,并且下面必须紧跟至少一个空行。 |
= My Document's Title My document provides...
= My Document's Title Doc Writer <doc.writer@asciidoctor.org> My document provides...
Asciidoctor 允许在作者行中出现多位作者,使用分号来分割开来。 |
= My Document's Title Doc Writer <doc.writer@asciidoctor.org> v1.0, 2014-01-01 My document provides...
你不能只写版本行而不写作者行! |
= My Document's Title Doc Writer <doc.writer@asciidoctor.org> v1.0, 2014-01-01 :toc: :imagesdir: assets/images :homepage: http://asciidoctor.org My document provides...
章节标题
= Document Title (Level 0) == Level 1 Section Title === Level 2 Section Title ==== Level 3 Section Title ===== Level 4 Section Title ====== Level 5 Section Title == Another Level 1 Section Title
Document Title (Level 0)
Level 1 Section Title
Level 2 Section Title
Level 3 Section Title
Level 4 Section Title
Level 5 Section Title
Another Level 1 Section Title
当使用文章标题类型时,默认只能有一个级别为0的文章标题(也就是文档标题),并且必须在文档头部。 |
等号的数量与输出的 HTML 标题级别想匹配。
例如,Section Level 1 将会转化为 <h2> 标题。
|
= Document Title (Level 0) == Section Level 1 === Section Level 2 ==== Section Level 3 ===== Section Level 4 ====== Section Level 5 = Section Level 0
Document Title (Level 0)
Section Level 1
Section Level 2
Section Level 3
Section Level 4
Section Level 5
Section Level 0
[[primitives-nulls]] == Primitive types and null values
sectanchors
-
当设置该文档属性后,章节的锚点图标就会出现在章节标题前面。
sectlinks
-
当设置该文档属性后,章节标题就变成自链接。 这使得读者可以书签标记这个章节。
章节标题锚点依赖默认 Asciidoctor 样式的正确渲染。 |
包含文件
= Reference Documentation Lead Developer This is documentation for project X. include::basics.adoc[] include::installation.adoc[] include::example.adoc[]
Asciidoctor does not insert blank lines between adjacent include statements to keep the content separated. Be sure to add a blank line in the source document to avoid unexpected results, such as a section title being swallowed. |
:asciidoctor-source: https://raw.githubusercontent.com/asciidoctor/asciidoctor/master include::{asciidoctor-source}/README.adoc[]
Including content from a URI is potentially dangerous, so it’s disabled if the safe mode is SECURE or greater.
Assuming the safe mode is less than SECURE, you must also set the allow-uri-read attribute to permit Asciidoctor to read content from a URI.
|
列表
* Edgar Allen Poe * Sheri S. Tepper * Bill Bryson
-
Edgar Allen Poe
-
Sheri S. Tepper
-
Bill Bryson
NOTE:列表前后的空行是必须的。
你可以通过在列表中间放一行注释来将其分成两个列表,就像上面的演示示例一样。
注释中的文字(例如 ^ )是可选的,但是可以个作为给其他作者的一个提示,来说明改行是列表的结束行。
|
* level 1 ** level 2 *** level 3 **** level 4 ***** level 5 * level 1
-
level 1
-
level 2
-
level 3
-
level 4
-
level 5
-
-
-
-
-
level 1
可以通过 块样式 来改变无序列表的标识类型。 |
- [*] checked - [x] also checked - [ ] not checked - normal list item
-
checked
-
also checked
-
not checked
-
normal list item
清单可以使用 字体图标,还可互动。 |
. Step 1 . Step 2 . Step 3
-
Step 1
-
Step 2
-
Step 3
. Step 1 . Step 2 .. Step 2a .. Step 2b . Step 3
-
Step 1
-
Step 2
-
Step 2a
-
Step 2b
-
-
Step 3
. level 1 .. level 2 ... level 3 .... level 4 ..... level 5 . level 1
-
level 1
-
level 2
-
level 3
-
level 4
-
level 5
-
-
-
-
-
level 1
对于有序列表,Asciidoctor 支持不同的 数字样式,例如 lowergreek 和 decimal-leading-zero 。
|
first term:: definition of first term section term:: definition of second term
- first term
-
definition of first term
- section term
-
definition of second term
first term:: definition of first term section term:: definition of second term
- first term
-
definition of first term
- section term
-
definition of second term
[qanda] What is Asciidoctor?:: An implementation of the AsciiDoc processor in Ruby. What is the answer to the Ultimate Question?:: 42
-
What is Asciidoctor?
An implementation of the AsciiDoc processor in Ruby.
-
What is the answer to the Ultimate Question?
42
Operating Systems:: Linux::: . Fedora * Desktop . Ubuntu * Desktop * Server BSD::: . FreeBSD . NetBSD Cloud Providers:: PaaS::: . OpenShift . CloudBees IaaS::: . Amazon EC2 . Rackspace
- Operating Systems
-
- Linux
-
-
Fedora
-
Desktop
-
-
Ubuntu
-
Desktop
-
Server
-
-
- BSD
-
-
FreeBSD
-
NetBSD
-
- Cloud Providers
-
- PaaS
-
-
OpenShift
-
CloudBees
-
- IaaS
-
-
Amazon EC2
-
Rackspace
-
列表可以缩进。 开头空白不需要显示指定。 |
* Every list item has at least one paragraph of content, which may be wrapped, even using a hanging indent. + Additional paragraphs or blocks are adjoined by putting a list continuation on a line adjacent to both blocks. + list continuation:: a plus sign (`{plus}`) on a line by itself * A literal paragraph does not require a list continuation. $ gem install asciidoctor * AsciiDoc lists may contain any complex content. + [cols="2", options="header"] |=== |Application |Language |AsciiDoc |Python |Asciidoctor |Ruby |===
-
Every list item has at least one paragraph of content, which may be wrapped, even using a hanging indent.
Additional paragraphs or blocks are adjoined by putting a list continuation on a line adjacent to both blocks.
- list continuation
-
a plus sign (
+
) on a line by itself
-
A literal paragraph does not require a list continuation.
$ gem install asciidoctor
-
AsciiDoc lists may contain any complex content.
Application Language AsciiDoc
Python
Asciidoctor
Ruby
链接
http://asciidoctor.org - automatic! http://asciidoctor.org[Asciidoctor] https://github.com/asciidoctor[Asciidoctor @ *GitHub*]
link:++http://example.org/?q=[a b]++[URL with special characters] link:http://example.org/?q=%5Ba%20b%5D[URL with special characters]
link:\\server\share\whitepaper.pdf[Whitepaper]
link:index.html[Docs]
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/#asciidoctor
http://discuss.asciidoctor.org[Discuss Asciidoctor, role="external", window="_blank"] http://discuss.asciidoctor.org[Discuss Asciidoctor^] http://example.org["Google, Yahoo, Bing^", role="teal"]
带属性的链接(包含 mailto 链接的主题和正文)是唯有 Asciidoctor 支持的特性。
为了启用这个特性,必须在文档中设置 linkattrs 属性。
当启用这个特性时,如果链接内容包含逗号,则必须用引号将链接文本括起来。
|
[[bookmark-a]]Inline anchors make arbitrary content referenceable. anchor:bookmark-b[]Use a cross reference to link to this location. [[bookmark-c,last paragraph]]The xreflabel attribute will be used as link text in the cross-reference link.
See <<paragraphs>> to learn how to write paragraphs. Learn how to organize the document into <<section-titles,sections>>.
Refer to <<document-b.adoc#section-b,Section B>> for more information. See you when you get back from <<document-b#section-b,Section B>>!
图片
image::sunset.jpg[] image::sunset.jpg[Sunset] [[img-sunset]] image::sunset.jpg[caption="Figure 1: ", title="A mountain sunset", alt="Sunset", width="300", height="200", link="http://www.flickr.com/photos/javh/5448336655"] image::http://asciidoctor.org/images/octocat.jpg[GitHub mascot]
图片路径会被解析成一个相对于 imagesdir 文档属性 的一个值,默认是一个空字符串。
imagesdir 属性可以是绝对路径、相对路径或者是基本 URL。
如果图片的目标(target)是一个 URL 或者绝对路径,则 imagesdir 前缀就不会被添加。
|
应该使用 imagesdir 属性来避免在每一个图片宏中硬编码分享路径。
|
image:sunset.jpg[Sunset,150,150,role="right"] What a beautiful sunset!
What a beautiful sunset!
在 图片的位置和帧 中,有很多很多可用的属性。 |
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.
Click to get the party started.
Click when you need a break.
= Document Title :data-uri:
当 data-uri 属性被设置时,文档中的所有图片,包含警告图标,都会作为 数据 URI 嵌入到文档中。
|
除了在文档中声明 data-uri 属性,你还可以将 -a data-uri 参数传递给命令行。
|
视频
video::video_file.mp4[] video::video_file.mp4[width=640, start=60, end=140, options=autoplay]
video::rPQoq7ThGAU[youtube]
video::67480300[vimeo]
可以在宏中使用 附加属性及选项 来控制视频设置。 |
源码
Reference code like `types` or `methods` inline.
Reference code like types
or methods
inline.
Indent the line one space to insert a code snippet
Indent the line one space to insert a code snippet
.... 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 ....
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
.Gemfile.lock ---- GEM remote: https://rubygems.org/ specs: asciidoctor (0.1.4) PLATFORMS ruby DEPENDENCIES asciidoctor (~> 0.1.4) ----
GEM remote: https://rubygems.org/ specs: asciidoctor (0.1.4) PLATFORMS ruby DEPENDENCIES asciidoctor (~> 0.1.4)
[[app-listing]] [source,ruby] .app.rb ---- require 'sinatra' get '/hi' do "Hello World!" end ----
require 'sinatra'
get '/hi' do
"Hello World!"
end
[source,ruby] ---- require 'sinatra' // <1> get '/hi' do // <2> "Hello World!" // <3> end ---- <1> Library import <2> URL mapping <3> HTTP response body
require 'sinatra' (1)
get '/hi' do (2)
"Hello World!" (3)
end
1 | Library import |
2 | URL mapping |
3 | HTTP response body |
---- line of code // <1> line of code # <2> line of code ;; <3> ---- <1> A callout behind a line comment for C-style languages. <2> A callout behind a line comment for Ruby, Python, Perl, etc. <3> A callout behind a line comment for Clojure.
line of code (1) line of code (2) line of code (3)
1 | A callout behind a line comment for C-style languages. |
2 | A callout behind a line comment for Ruby, Python, Perl, etc. |
3 | A callout behind a line comment for Clojure. |
[source,xml] ---- <section> <title>Section Title</title> <!--1--> </section> ---- <1> The section title is required.
<section>
<title>Section Title</title> (1)
</section>
1 | 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] <meta name="viewport" content="width=device-width, initial-scale=1.0"> This is normal content.
<meta name="viewport"
content="width=device-width, initial-scale=1.0">
This is normal content.
启用语法高亮
启用语法高亮可以在文档头部设置 :source-highlighter: pygments 可用选项有: |
更多分隔块
.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. ****
任何块可以在块上面定义标题。 块标题是一行以点号开头的文字。 点号后面不能有空白。 |
.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. ====
Here’s a sample AsciiDoc document:
= 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. ====
An admonition block may contain complex content. A list
Another paragraph. |
警告和注标图标
Asciidoctor 可以使用 Font Awesome 和 CSS “描绘” 图标。 将文档属性 |
[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. ____
Four score and seven years ago our fathers brought forth on this continent a new nation…
Address delivered at the dedication of the Cemetery at Gettysburg
A person who never made a mistake never tried anything new.
A person who never made a mistake never tried anything new.
"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
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.
Papers of Thomas Jefferson: Volume 11
[, Richard M. Nixon] "" When the President does it, that means that it's not illegal. ""
When the President does it, that means that it’s not illegal.
++++ <p> Content in a passthrough block is passed to the output unprocessed. That means you can include raw HTML, like this embedded Gist: </p> <script src="http://gist.github.com/mojavelinux/5333524.js"> </script> ++++
Content in a passthrough block is passed to the output unprocessed. That means you can include raw HTML, like this embedded Gist:
-- An open block can be an anonymous container, or it can masquerade as any other block. -- [source] -- puts "I'm a source block!" --
An open block can be an anonymous container, or it can masquerade as any other block.
puts "I'm a source block!"
:version: 0.1.4 [source,xml,subs="verbatim,attributes"] ---- <dependency> <groupId>org.asciidoctor</groupId> <artifactId>asciidoctor-java-integration</artifactId> <version>{version}</version> </dependency> ----
<dependency>
<groupId>org.asciidoctor</groupId>
<artifactId>asciidoctor-java-integration</artifactId>
<version>0.1.4</version>
</dependency>
块ID,角色和选项
[[goals]] [role="incremental"] * Goal 1 * Goal 2
[#goals.incremental] * Goal 1 * Goal 2
|
[[free_the_world]][big goal]_free the world_
[#free_the_world.big.goal]_free the world_
[rolename]`monospace text`
[options="header,footer,autowidth"] |=== |Cell A |Cell B |===
[%header%footer%autowidth] |=== |Cell A |Cell B |===
评论
// A single-line comment.
单行注释可以用于划分元素,例如两个相邻的清单。 |
//// A multi-line comment. Notice it's a delimited block. ////
表格
.Table Title |=== |Name of Column 1 |Name of Column 2 |Name of Column 3 (1) (2) |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 |===
1 | 除非设置 cols 属性,否则行数就等于块区域中第一非空白行中竖线的数量。 |
2 | 当列开头下面紧跟一空白行时,列开头会自动渲染成列标题的样式。 |
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="2*", options="header"] (1) |=== |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 |===
1 | 在 cols 属性值中的 * 是复制符,用来按现有列的格式复制剩余部分。在这个例子中,它就代表重复默认的样式到 4 列。当标题行不是定义在一行里,就必须使用 cols 属性来设置列数,并使用 options 属性来将第一行设置成标题。 |
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"] (1) .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. |===
1 | 在这个例子中,cols 属性有两个功能:设置表格的列数及列之间相对的宽度。 |
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]! |===
Firefox |
Browser |
Mozilla Firefox is an open-source web browser. It’s designed for:
|
[format="csv", options="header"] |=== Artist,Track,Genre Baauer,Harlem Shake,Hip Hop The Lumineers,Ho Hey,Folk Rock |===
Artist | Track | Genre |
---|---|---|
Baauer |
Harlem Shake |
Hip Hop |
The Lumineers |
Ho Hey |
Folk Rock |
,=== Artist,Track,Genre Baauer,Harlem Shake,Hip Hop ,===
Artist | Track | Genre |
---|---|---|
Baauer |
Harlem Shake |
Hip Hop |
|=== include::customers.csv[] |===
:=== Artist:Track:Genre Robyn:Indestructable:Dance :===
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 |
2 |
3 |
4 |
5 |
|
|
|
8 |
|||
9 |
|
UI 宏
You must set the experimental attribute in the document header to enable these macros.
|
kbd
宏)|=== |Shortcut |Purpose |kbd:[F11] |Toggle fullscreen |kbd:[Ctrl+T] |Open a new tab |kbd:[Ctrl+Shift+N] |New incognito window |kbd:[Ctrl + +] |Increase zoom |===
Shortcut | Purpose |
---|---|
F11 |
Toggle fullscreen |
Ctrl+T |
Open a new tab |
Ctrl+Shift+N |
New incognito window |
Ctrl++ |
Increase zoom |
To save the file, select menu:File[Save]. Select menu:View[Zoom > Reset] to reset the zoom level to the default setting.
To save the file, select
.Select
to reset the zoom level to the default setting.Press the btn:[OK] button when you are finished. Select a file in the file navigator and click btn:[Open].
Press the OK button when you are finished.
Select a file in the file navigator and click Open.
属性与代换
:homepage: http://asciidoctor.org :docslink: http://asciidoctor.org/docs[Asciidoctor's Docs] :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 {homepage}[Asciidoctor]! {summary} Check out {docslink} too! {checkedbox} That's done!
Check out Asciidoctor! 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. Check out Asciidoctor’s Docs too! [✔] That’s done! |
-
传递给 API 或者 命令行且不以
@
结尾的属性 -
在文档中定义的属性
-
传递给 API 或者 命令行且以
@
结尾的属性 -
内置属性值(默认值)
为了使传递给 API 或者 命令行的属性有一个比文档中定义的属性有更低的优先级,则可以在属性值的末尾追加一个 @ 符号。
|
Attribute name | Replacement text | Appearance |
---|---|---|
blank |
nothing |
|
empty |
nothing |
|
sp |
single space |
|
nbsp |
  |
|
zwsp[4] |
​ |
|
wj[5] |
⁠ |
|
apos |
' |
' |
quot |
" |
" |
lsquo |
‘ |
‘ |
rsquo |
’ |
’ |
ldquo |
“ |
“ |
rdquo |
” |
” |
deg |
° |
° |
plus |
+ |
+ |
brvbar |
¦ |
¦ |
vbar |
| |
| |
amp |
& |
& |
lt |
< |
< |
gt |
> |
> |
startsb |
[ |
[ |
endsb |
] |
] |
caret |
^ |
^ |
asterisk |
* |
* |
tilde |
~ |
~ |
backslash |
\ |
\ |
backtick |
` |
` |
two-colons |
:: |
:: |
two-semicolons |
;; |
;; |
cpp |
C++ |
C++ |
[1] Some replacements are Unicode characters, whereas others are numeric character references. The character references (e.g., ") are used whenever the use of the Unicode character could interfere with the AsciiDoc syntax or confuse the renderer (i.e., the browser). It’s up to the converter to transform the reference into something the renderer understands (something both the manpage and PDF converter handle).
[2] Asciidoctor does not prevent you from reassigning predefined attributes. However, it’s best to treat them as read-only unless the output format requires the use of a different encoding scheme. These attributes are an effective tool for decoupling content and presentation.
[3] Asciidoctor allows you to use any of the named character references (aka named entities) defined in HTML (e.g., € resolves to €). However, using named character references can cause problems when generating non-HTML output such as PDF because the lookup table needed to resolve these names may not be defined. Our recommendation is avoid using named character references—with the exception of those defined in XML (i.e., lt, gt, amp, quot and apos). Instead, use numeric character references (e.g., €).
[4] The Zero Width Space (ZWSP) is a code point in Unicode that shows where a long word can be split if necessary.
[5] The word joiner (WJ) is a code point in Unicode prevents a line break at its position.
Attribute | Description | Example Value |
---|---|---|
|
Set if the current processor is Asciidoctor. |
|
|
Asciidoctor version. |
|
|
Backend used to create the output file. |
|
|
The backend value minus any trailing numbers.
For example, if the backend is |
|
|
Last modified date of the source document.[1,2] |
|
|
Last modified date and time of the source document.[1,2] |
|
|
Full path of the directory that contains the source document. |
|
|
Full path of the source document. |
|
|
Root name of the source document (no leading path or file extension). |
|
|
Last modified time of the source document.[1,2] |
|
|
Document type (article, book or manpage). |
|
|
Set if content is being converted to an embeddable document (body only). |
|
|
File extension of the output file name (without leading period). |
|
|
Syntax used when generating the HTML output (html or xhtml). |
|
|
Date when converted.[2] |
|
|
Date and time when converted.[2] |
|
|
Time when converted.[2] |
|
|
Full path of the output directory. |
|
|
Full path of the output file. |
|
|
Default file extension of output file (not the file extension of the specified output file).
Value depends on backend ( |
|
|
Numeric value of the safe mode setting. (UNSAFE=0, SAFE=10, SERVER=10, SECURE=20). |
|
|
Textual value of the safe mode setting. |
|
|
Set if the safe mode is UNSAFE. |
|
|
Set if the safe mode is SAFE. |
|
|
Set if the safe mode is SERVER. |
|
|
Set if the safe mode is SECURE. |
|
|
Home directory of the current user.
Resolves to |
|
none
|
Disables substitutions |
normal
|
Performs all substitutions except for callouts |
verbatim
|
Replaces special characters and processes callouts |
specialchars , specialcharacters
|
Replaces |
quotes
|
Applies text formatting |
attributes
|
Replaces attribute references |
replacements
|
Substitutes textual and character reference replacements |
macros
|
Processes macros |
post_replacements
|
Replaces the line break character ( |
[caption=""] .Parts{counter2:index:0} |=== |Part Id |Description |PX-{counter:index} |Description of PX-{index} |PX-{counter:index} |Description of PX-{index} |===
Part Id | Description |
---|---|
PX-1 |
Description of PX-1 |
PX-2 |
Description of PX-2 |
文本替换
Name | Syntax | Unicode Replacement | Rendered | Notes |
---|---|---|---|---|
Copyright |
(C) |
© |
© |
|
Registered |
(R) |
® |
® |
|
Trademark |
(TM) |
™ |
™ |
|
Em dash |
-- |
— |
— |
Only replaced if it is a word, i.e. surrounded by white space, line start, or line end. When white space characters are detected on both sides of the em dash, they are replaced by thin spaces ( ). |
ellipses |
... |
… |
… |
|
right single arrow |
-> |
→ |
→ |
|
right double arrow |
=> |
⇒ |
⇒ |
|
left single arrow |
<- |
← |
← |
|
left double arrow |
<= |
⇐ |
⇐ |
|
apostrophe |
Sam's |
Sam’s |
Sam’s |
The vertical form apostrophe is replaced with the curved form apostrophe. |
任意命名的,数值或十六进制的 XML 实体引用 都支持。 |
文字转义
\*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. The backslash character is automatically removed.
*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.
The backslash character is automatically removed.
+++<u>underline me</u>+++ renders as underlined text. pass:[<u>underline me</u>] also renders as underlined text.
underline me renders as underlined text.
underline me also renders as underlined text.
目录
= AsciiDoc Writer's Guide Doc Writer <doc.writer@asciidoctor.org> v1.0, 2013-08-01 :toc:
= AsciiDoc Writer's Guide Doc Writer <doc.writer@asciidoctor.org> v1.0, 2014-08-01 :toc: right
参考 目录的标题、级别和位置 可以自定义目录。 |
参考书目
_The Pragmatic Programmer_ <<prag>> should be required reading for all developers. [bibliography] - [[[prag]]] Andy Hunt & Dave Thomas. The Pragmatic Programmer: From Journeyman to Master. Addison-Wesley. 1999. - [[[seam]]] Dan Allen. Seam in Action. Manning Publications. 2008.
The Pragmatic Programmer [prag] should be required reading for all developers.
脚注
A statement.footnote:[Clarification about this statement.] A bold statement.footnoteref:[disclaimer,Opinions are my own.] Another bold statement.footnoteref:[disclaimer]
Markdown 兼容性
Markdown 可兼容语法只有在使用 Asciidoctor 可用。
# Document Title (Level 0) ## Section Level 1 ### Section Level 2 #### Section Level 3 ##### Section Level 4 ###### Section Level 5
Document Title (Level 0)
Section Level 1
Section Level 2
Section Level 3
Section Level 4
Section Level 5
```ruby require 'sinatra' get '/hi' do "Hello World!" end ```
require 'sinatra'
get '/hi' do
"Hello World!"
end
> 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
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.
Papers of Thomas Jefferson: Volume 11
> > 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.
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.
--- - - - *** * * *
用户手册以及帮助
想了解更多的 Asciidoctor 及功能,请查看其他 Asciidoctor 指南 和它的 用户手册。 同时,别忘记加入 Asciidoctor 邮件列表,在这里,你可以提问题,还可以留言评论。