简介

轻量级的标记语言已经有很多(Wikipedia),例如我用来写博客的 Markdown 就是目前十分流行的一种轻量级标记语言,包括 GithubStackOverflow 等很多网站以及个人都在使用。

Markdown 还不够吗

Markdown 语法简介,即便阅读未经渲染的源文件也有不错的可读性。但它对于较为复杂的格式例如表格的支持始终遭人诟病,许多网站使用各自不同的扩展语法来实现,也从而导致了各种方言的滋生。这也是为何会出现 Standard Markdown 项目的原因,虽然因为种种原因又更名为 Common Markdown,然而整个 Markdown 社区依然缺乏创建者的支持,Common Markdown 也很可能沦为另一个方言。

md standards
Figure 1. Markdown Standards

为什么选择 AsciiDoc

第一次接触到 AsciiDoc 是通过 O’Reilly 的图书,Atlas 的推荐语言就是 AsciiDoc。那么十多种标记语言中,为什么要选择 AsciiDoc 呢?其实在选择另一种标记语言时,我做过一些简单的研究:

  • LaTex : 大名鼎鼎的 LaTex 是除了 Markdown 之外我第一个投入精力学习的标记语言。不得不说 LaTex 十分强大,但与这份强大伴随而来则是复杂的语法,导致了写作过程的枯燥,也让我失去了对 LaTex 的兴趣。

  • reStructuredText : REST 也是一种松散的文本结构,功能也较为全面,但书写起来更像是在写 Python。

  • Org mode : 我想基本上只有 Emacs 社区的人在使用了吧。

  • Texy!,BBCode,Creole,Textile…​ : 事实上大部分轻量级的标记语言语法都较为类似,所以这场抉择很大程度上是使用范围、功能、兼容性、扩展性等多方面的比赛,这也是我为什么不选择这些语言的原因。

AsciiDoc 与 Markdown

AsciiDoc 的语法与 Markdown 十分类似,在学会 Markdown 的前提下很容易转向 AsciiDoc 阵营。

在的功能方面,前面已经说过许多功能 Markdown 要通过扩展语法和 HTML 来实现,前者直接导致了通用性的缺失,后者提高了后期编撰的成本,而 AsciiDoc 的学习成本也远不及多学一门 HTML 甚至多种扩展语法。

AsciiDoc 原生支持的特性就足以应付大多数电子文档的编撰需求,你可以使用标准的 AsciiDoc 语法为你的文档添加作者信息、版本信息、表格等特性,它还支持文档引入、自定义块语法等功能。

语法

标题

{ascii} 中的标题共分为六层,分别使用对应数量的 = 进行标识:

= 零级

== 一级

=== 二级

==== 三级

===== 四级

====== 五级
Example 1. result

零级

一级

二级

三级

四级
五级

目录

:toc:

:toc: right

:toc: left

样式

粗体

普通文字 *粗体字* 普通文字
Example 2. result

普通文字 粗体字 普通文字

斜体

普通文字 _斜体字_ 普通文字
Example 3. result

普通文字 斜体字 普通文字

*_粗体 & 斜体_*
Example 4. result

粗体 & 斜体

高亮

普通文字 #高亮内容# 普通文字
Example 5. result

普通文字 高亮内容 普通文字

下划线

[.underline]#下划线文字#
Example 6. result

下划线文字

删划线

[.line-through]#删划线文字#
Example 7. result

删划线文字

大小标记

普通文字中含有 [.small]#示例小标记# 以及 [.big]##示例大标记##。
Example 8. result

普通文字中含有 示例小标记 以及 示例大标记

上标下标

普通文字^上标^

普通文字~下标~
Example 9. result

普通文字上标

普通文字下标

横线

***
Example 10. result

分页

<<<

图片

行内图片

An image image:{image}/avatar/oschina_200.jpg[some, 50] here.
Example 11. result

An image some here.

块图片

image::{image}/avatar/oschina_200.jpg[caption="Caption: ", title="Blocked Image", 100]
Example 12. result
oschina 200
Caption: Blocked Image

视频

普通视频

video::video_file.mp4[]

video::video_file.mp4[width=640, start=60, end=140, options=autoplay]
Example 13. result

Youtube 视频

video::rPQoq7ThGAU[youtube]
Example 14. result

Vimeo 视频

video::67480300[vimeo]
Example 15. result

链接

获取更多详情,请link:{home}[点击这里], 或者 {home}[像这样]
Example 16. result

获取更多详情,请点击这里, 或者 像这样

标记

[#goals]
* Goal 1
* Goal 2

Jump to link:#golas[Link with id].
Example 17. result
  • Goal 1

  • Goal 2

Jump to Link with id.

列表

无序列表

* level 1
** level 2
*** level 3
**** level 4
***** level 5
* level 1
Example 18. result
  • level 1

    • level 2

      • level 3

        • level 4

          • level 5

  • level 1

有序列表

. level 1
.. level 2
... level 3
.... level 4
..... level 5
. level 1
Example 19. result
  1. level 1

    1. level 2

      1. level 3

        1. level 4

          1. level 5

  2. level 1

勾选列表

* [x] 已选
* [ ] 未选
*     普通
Example 20. result
  • 已选

  • 未选

  • 普通

混合列表

Operating Systems::
  Linux:::
    . Fedora
      * Desktop
    . Ubuntu
      * Desktop
      * Server
  BSD:::
    . FreeBSD
    . NetBSD

Cloud Providers::
  PaaS:::
    . OpenShift
    . CloudBees
  IaaS:::
    . Amazon EC2
    . Rackspace
Example 21. result
Operating Systems
Linux
  1. Fedora

    • Desktop

  2. Ubuntu

    • Desktop

    • Server

BSD
  1. FreeBSD

  2. NetBSD

Cloud Providers
PaaS
  1. OpenShift

  2. CloudBees

IaaS
  1. Amazon EC2

  2. Rackspace

标签列表

What is this?:: You tell me!

Why?:: I don't know.
Example 22. result
What is this?

You tell me!

Why?

I don’t know.

表格

简单列表

.表格标题
|===
|列标题 1 |列标题 2 |列标题 3

|列1行1
|列2行1
|列3行1

|列1行2
|列2行2
|列3行2
|===
Example 23. result
Table 1. 表格标题
列标题 1 列标题 2 列标题 3

列1行1

列2行1

列3行1

列1行2

列2行2

列3行2

[%header,cols=2*]
|===
|列标题 1
|列标题 2

|列1行1
|列2行1

|列1行2
|列2行2
|===
Example 24. result
列标题 1 列标题 2

列1行1

列2行1

列1行2

列2行2

嵌套语法

[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]!
|===
Example 25. result

Firefox

Browser

Mozilla Firefox is an open-source web browser.

It’s designed for:

  • standards compliance

  • performance

  • portability

停靠位置

在单元格分隔符 (|) 前使用 ^<> 符号分别表示该单元格横向居中、左对齐、右对齐。

在单元格分隔符 (|) 前使用 .^ 符号表示该单元格纵向居中。

|===
^|居中
<|左对齐
>|右对齐
|这是一个普通的单元格,使用默认的停靠规则
|===
Example 26. result

居中

左对齐

右对齐

这是一个普通的单元格,使用默认的停靠规则

合并单元格

在单元格分隔符 (|) 前使用 N\+ 表示该单元格横向占据 N 列。

在单元格分隔符 (|) 前使用 .N\+ 表示该单元格纵向占据 N 行。

|===
|列1|列2|列3
2+|横向占据2个单元格|cell
2.2+|横竖均占据2个单元格|cell
|cell
|===
Example 27. result

列1

列2

列3

横向占据2个单元格

cell

横竖均占据2个单元格

cell

cell

|===
|列1|列2|列3
2+^|横向占据2个单元格,横向居中|cell
2.2+^.^|横竖均占据2个单元格,横纵居中|cell
|cell
|===
Example 28. result

列1

列2

列3

横向占据2个单元格,横向居中

cell

横竖均占据2个单元格,横纵居中

cell

cell

|===
|cell .3+^.^|纵向占据三个单元格,横纵居中
m|cell
e|cell
|===
Example 29. result

cell

纵向占据三个单元格,横纵居中

cell

cell

区块

横栏块

.横栏
****
这是一个**横栏块**
****
Example 30. result
横栏

这是一个横栏块

示例块

.result
====
这是一个示例
====

透传块

++++
<a href="{home}">内嵌 HTML 代码</a>
++++
Example 31. result

引用块

[quote, 林肯, 第XX任美国总统]
____
Four score and seven years ago our fathers brought forth
on this continent a new nation...
____
[quote, 爱因斯坦]
A person who never made a mistake never tried anything new.
____
A person who never made a mistake never tried anything new.

Contains a link:{home}[link].
____
Example 32. result

Four score and seven years ago our fathers brought forth on this continent a new nation…​

— 林肯
第XX任美国总统
Example 33. result
A person who never made a mistake never tried anything new.
— 爱因斯坦
Example 34. result

A person who never made a mistake never tried anything new.

Contains a link.

警告块

AsciiDoctor 中, 使用这些图标需要在文档头配置 :icons: font

NOTE: 备注

TIP: 提示

IMPORTANT: 重要

WARNING: 警告

CAUTION: 当心

[NOTE]
====
一些备注内容
====
Example 35. result
备注
提示
重要
警告
当心

代码块

AsciiDoctor 中, 使用代码高亮需要在文档头配置 :source-highlighter: pygments

你可以通过 gem install pygments.rb 指令安装 pygmentsRuby 实现。除 pygments, 还可以使用 coderay, highlightjs, `prettify`等。

.index.html
[source, html, subs="verbatim, attributes"]
....
<div> // <1>
  <p>{author}</p>
</div>
....
<1> 标注信息
Example 36. result
index.html
<div> (1)
  <p>Elias Abel</p>
</div>
1 标注信息
Markdown 风格
```ruby
def some()
end
```
Example 37. result
def some()
end
Example 38. result
import UIKit

open class SomeClass {
  open let name: String

  public init(name) {
    self.name = name
  }
}

行内代码

普通文字 `<div>` 普通文字
Example 39. result

普通文字 <div> 普通文字

注释

// 单行注释

////
多行注释

多行注释
////

键盘

通过 kdb:[键位+键位+键位] 的语法使用键盘符号特性。

AsciiDoctor 中, 你需要在文档前标记 :experimental: 才能使用键盘符号特性。
kbd:[Ctrl+T]

kbd:[Command+Options+Control+T]

kbd:[⌘+N]
Example 40. result

Ctrl+T

Command+Options+Control+T

+N

导入

通过 include::文档路径[选项] 语法来包含文件,其中选项可以为空

include::../somedir/somefile.txt[]

include::../somedir/somefile.txt[tabsize=2]

在代码块中引用文件:

.index.adoc
[source, asciidoc]
....
include::./index.adoc[lines=1..5]
....
Example 41. result
index.adoc
:article: AsciiDoc 指引
:title: {article}
:author: Elias Abel
:mail: [email protected]
:home: https://meniny.cn

脚注

一些文字。footnote:[示例脚注1.]

一些文字。footnoteref:[tag,示例脚注2.]

一些文字。footnoteref:[tag]
Example 42. result

一些文字。[1]

一些文字。[2]

一些文字。[2]

工具

AsciidocFX

AsciidocFX 是一款开源 GUI 编辑器。

asciidocfx
Figure 2. AsciidocFX

Atom

来自 Github 的 Atom, 需要额外安装插件。

index ide screenshot 26fbe099e63e84c16a2a690e9de2b923
Figure 3. Atom

AsciiDoctor

AsciiDocor 是一个使用 Ruby 实现的 AsciiDoc 转换工具。你可以通过 gem install asciidoctor 进行安装。

asciidoctor MyDoc.adoc

asciidoctor -a stylesheet golo.css -o MyHTML.html MyDoc.adoc
screenshot
Figure 4. AsciiDoctor

关于


1. 示例脚注1.
2. 示例脚注2.