AsciiDoc 的相关整理

Install on macOS

Install with Homebrew

You can use Homebrew, the macOS package manager, to install Asciidoctor. If you don’t have Homebrew on your computer, complete the installation instructions at brew.sh first.

Once Homebrew is installed, you’re ready to install the asciidoctor gem. Open a terminal and type:

$ brew install asciidoctor

Homebrew installs the asciidoctor gem into an exclusive prefix that’s independent of system gems.

If the gem installed successfully, Asciidoctor’s command line interface (CLI) will be available on your PATH. To confirm that Asciidoctor is available, execute:

$ asciidoctor --version

You should see information about the Asciidoctor version and your Ruby environment printed in the terminal.

Asciidoctor 2.0.15 [https://asciidoctor.org]
Runtime Environment (ruby 2.6.3p62 (2019-04-16 revision 67580) [universal.x86_64-darwin20]) (lc:UTF-8 fs:UTF-8 in:UTF-8 ex:UTF-8)

https://docs.asciidoctor.org/asciidoctor/latest/install/macos/

Convert Your First AsciiDoc File

Assumptions:

You’ve installed Asciidoctor.
You’ve confirmed that the Asciidoctor command line interface (CLI) is available on your PATH.

On this page, you’ll learn how to run Asciidoctor on an AsciiDoc document and convert it to HTML.

Generate HTML using the default converter

Let’s generate HTML 5 using Asciidoctor’s default converter and stylesheet from an AsciiDoc document.

To follow along with the steps below, copy the contents of Example 1 into a new plain text file or use your own AsciiDoc document.

Example 1. my-document.adoc

= The Dangers of Wolpertingers
:url-wolpertinger: https://en.wikipedia.org/wiki/Wolpertinger

Don't worry about gumberoos or splintercats.
Something far more fearsome plagues the days, nights, and inbetweens.
Wolpertingers.

== Origins

Wolpertingers are {url-wolpertinger}[ravenous beasts].

Make sure to save the file with the .adoc file extension.
Open a terminal and switch (cd) into the directory where your AsciiDoc document is saved.
```
$ cd directory-name
```
Call Asciidoctor with the asciidoctor command, followed by file name of the AsciiDoc document. Since HTML 5 is Asciidoctor’s default output, we don’t need to specify a converter.
$ asciidoctor my-document.adoc
As long as the document didn’t contain any syntax errors, you won’t see any messages printed to your terminal.
Type ls to list the files in the directory.
$ ls my-document.adoc my-document.html
You should see a new file named my-document.html. Asciidoctor derives the name of the output file from the name of the input document.
Open my-document.html in your web browser. The converted document should look like the example below.

https://docs.asciidoctor.org/asciidoctor/latest/get-started/

asciidoctor
Step1:下载安装 rubyinstaller-devkit

https://asciidoctor.org/

(c) Windows

To use Asciidoctor with Windows, you have two easy options.

Chocolatey

When you already use chocolatey on your machine, you can use:

choco install ruby

Then follow gem installation instructions.

Rubyinstaller

Or you use the Rubyinstaller, download the package for your Windows Version and after the installation go ahead with gem installation instructions.

Step2:

Open a terminal and type:

$ gem install asciidoctor

If you want to install a pre-release version (e.g., a release candidate), use:

$ gem install asciidoctor --pre

When you install a new version of the gem using gem install, you end up with multiple versions installed. Use the following command to remove the old versions:

$ gem cleanup asciidoctor

Step3:

Usage

If the Asciidoctor gem installed successfully, the asciidoctor command line interface (CLI) will be available on your PATH. To verify it’s available, run the following in your terminal:

$ asciidoctor --version

You should see information about the Asciidoctor version and your Ruby environment printed in the terminal.

Asciidoctor 2.0.10 [https://asciidoctor.org]
Runtime Environment (ruby 2.6.0p0 [x86_64-linux]) (lc:UTF-8 fs:UTF-8 in:- ex:UTF-8)

Asciidoctor also provides an API. The API is intended for integration with other Ruby software, such as Rails, Sinatra and GitHub, and other languages, such as Java (via AsciidoctorJ) and JavaScript (via Asciidoctor.js).

Command line interface (CLI)

The asciidoctor command allows you to invoke Asciidoctor from the command line (i.e., a terminal).

The following command converts the file README.adoc to HTML and saves the result to the file README.html in the same directory. The name of the generated HTML file is derived from the source file by changing its file extension to .html.

$ asciidoctor README.adoc

Asciidoc Book Editor based on JavaFX 8

Asciidoc FX is a book / document editor to build PDF, Epub, Mobi and HTML books, documents and slides. AsciidocFX is also a winner of Duke’s Choice Award 2015.

Figure 1. AsciidocFX - Duke’s Choice Award 2015 winner

Features

Real-Time Preview
Multi-platform (Windows, Mac, Linux)
Creating Asciidoc Books
Creating Markdown Books
Creating PDF, HTML, Epub, Mobi, Odt, Docbook
Epub Viewer
External Browser Support
Table Generator
MathJax Extension
PlantUML Extension
ditaa Extension
Filesystem Tree Extension
JavaFX Charts Extension
Source Code Highlighter
Reveal.js Converter
Deck.js Converter
Nashorn support
Pseudo Terminal Emulator
Themeing (Dark & White) _New _

https://asciidocfx.com/

文前说明

作为码农中的一员，需要不断的学习，我工作之余将一些分析总结和学习笔记写成博客与大家一起交流，也希望采用这种方式记录自己的学习之旅。

本文仅供学习交流使用，侵权必删。
不用于商业目的，转载请注明出处。

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 <doc.writer@asciidoctor.org>
v1.0, 2018-04-11
:toc:
:imagesdir: assets/images
:homepage: https://asciidoctor.org

My document provides...

1.1.2 标题

需要靠左侧顶格。
可以包含文档头、第 1 ~ 第 5 章节标题。
当使用项目文档类型（默认值）时，只能有一个 0 级的节标题（即，文档标题），并且它必须位于文档头中。
等号的数目与 HTML 输出中的标题级别相匹配。
- 例如，（=）转换成为 <h2> 标签。

= 文档标题 (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 属性。这样会导致每一行之后增加可见的换行标记（例如 <BR>）。

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 格式输出。

<div class="admonitionblock note">
<table>
<tr>
<td class="icon">
<i class="fa icon-note" title="Note"></i>
</td>
<td class="content">
Asciidoctor supports font-based admonition icons, powered by Font Awesome!
</td>
</tr>
</table>
</div>

AsciiDoc 中添加了 Awesome 的字体超强样式表和字体文件的引用。

<link rel="stylesheet" href="http://cdnjs.cloudflare.com/ajax/libs/font-awesome/3.1.0/css/font-awesome.min.css">

1.1.3.3.2 Unicode 文本图标

代替图像或基于字体的图标，可以通过使用一个小技巧使用 Unicode 文本来表示警告图标。
如果在文档上没有设置图标属性，AsciiDoc 输出一个标识警告类型的文本标签。此标签的文本来自 AsciiDoc 属性。
- 属性的名称是 <类型> 标题，其中 <类型> 是小写中的警告类型。例如，提示提示的属性是提示字幕。
可以将一个 Unicode 字形赋值给这个属性，而不是单词。

:tip-caption: 💡

[TIP]
It's possible to use Unicode glyphs as admonition icons.

HTML 格式输出。

<td class="icon">
<div class="title">💡</div>
</td>

1.1.3.3.3 内联图标

图标可以插入到段落内容的任意位置，内嵌宏。

icon:tags[] ruby, asciidoctor

HTML 格式输出。

<div class="paragraph">
<p><span class="icon"><i class="fa fa-tags"></i></span> ruby, asciidoctor</p>
</div>

内联图标宏和角色语法。

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 清单块（列表块）

用于计算机的输出和文件列表、可用于程序代码。
里面特殊字符不替换。
列表块内容被转换为 <PRE> 文本。
- 列表块中的内容只受特殊字符和标注替换的限制。
列表块名称应用于内容的两种方式。
- 在元素上设置列表属性。
- 包含分隔符列表块中的内容。
将列表块名称应用于元素，例如段落，通过在该元素上设置列表属性。

[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"]
----
<dependency>
  <groupId>org.asciidoctor</groupId>
  <artifactId>asciidoctor-java-integration</artifactId>
  <version>{version}</version>
</dependency>
----

滚动支持
- nowrap 会增加（css 样式 white-space:nowrap 和 word-wrap: normal）到 <PRE> 元素上。

[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' // <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.

具有不可选标注的 XML 代码块

[source,xml]
----
<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.

代码列表块启动语法高亮可以在文档头中设置。
- 高亮属性有 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 可查询通用字符集。

&#xhhhh;

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]]
链接：<<A88,chapter titles>>

1.1.7.6 图片

块图像

image::sunset.jpg[]

image::sunset.jpg[Sunset]

.A mountain sunset
[#img-sunset]
[caption="Figure 1: ",link=https://www.flickr.com/photos/javh/5448336655]
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 <doc.writer@asciidoctor.org>
v1.0, 2013-08-01
:toc: right

1.1.7.10 参考文献

_The Pragmatic Programmer_ <<pp>> should be required reading for all developers.
To learn all about design patterns, refer to the book by the "`Gang of Four`" <<gof>>.

[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}&#10004;{endsb}]

Check out {url-home}[Asciidoctor]!

{summary}

Be sure to read the {link-docs} too!

{checkedbox} That's done!

计数器属性

[caption=""]
.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 +<+ and +>+ are still escaped.

pass 宏直译

pass:[<u>underline me</u>] is also underlined.

三（+）直译

+++<u>underline me</u>+++ 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/

作者：羽杰
链接：https://www.jianshu.com/p/f76b1c6c9442
来源：简书
简书著作权归作者所有，任何形式的转载都请联系作者获得授权并注明出处。

posted @ 2019-05-28 11:51 沧海一滴阅读(2414) 评论(0) 编辑收藏举报

会员力量，点亮园子希望

刷新页面返回顶部

沧海一滴

不积小流，无以成江海