参考文档

文件路径示例

当前文件目录：/drone/src/src/main/asciidoc

当前文件路径：/drone/src/src/main/asciidoc/blog/asciidoc/blog_asciidoc.adoc

当前文件名称：blog_asciidoc

path1：https://doc.itlym.cn/blog_asciidoc.html

path2：/drone/src/src/main/asciidoc/blog_asciidoc

nofollow:https://baidu.com[baidu]

文档结构

标题

=文档标题 (书)
在文档标题和一级标题之间的段落为摘要。

== 一级标题 (章)
=== 二级标题 (节)
==== 三级标题
===== 四级标题
====== 五级标题

如果标题不纳入 ToC 则在标题前加入分离 [discrete]，有该关键字时，标题可以跳级。

=== 二级标题 (节)

[discrete]
===== 四级标题

[discrete]
==== 三级标题

include

<<<
include::mydoc/demo.adoc[leveloffset=1]
<<<
include::mydoc/about.adoc[leveloffset=1]
[source,java]
----
include::mydoc/Hello.java[]
----

  1. <<< 为 PDF 分页符号。

  2. leveloffset=1 表示将 demo.adoc 的标题降 1 级，如为 -1 则为升 1 级。

水平分隔线 (Horizontal Rules)

这样：---
这样：- - -
这样：***
这样：* * *

输出结果:

错误示范

为了展示写错了会被渲染成什么情况，这里特加入错误示例，也便于错误扫描。

示例：include::mydoc/not_exist_demo.adoc[leveloffset=1]

示例：not exist demo2

示例：这个`引用`是错的

示例：=== 这可能是错误的标题

示例：[.line-through]这可能是错误的下划线

示例：* 这可能是错误的列表

文本样式

引号替换 (Quotes Substitutions)

示例：* 粗体 斜体 删除线 加底线 上标线 高亮度
示例：* 黄色 红色黄底
示例：* 加大 正常 缩小 上标 下标
示例：* Hello world (正常)
示例：* Hello world (等宽)
示例：* “双弯引号” ‘单弯引号’

  • 粗体 斜体 删除线 加底线 上标线 高亮度

  • 黄色 红色黄底

  • 加大 正常 缩小 上标 下标

  • Hello world (正常)

  • Hello world (等宽)

  • “双弯引号” ‘单弯引号’

颜色参见：css

替换符若 (前后其一) 没有「字符串边界」 (字符串边界: 字符串间有非文本的字符；如空白，中英的逗号、句号、括号 …​)，必须采用两个替换符。在大部份的情况前后应该会有「字符串边界」那么只需要一个替换字符。不过在某些情况需要两个替换符，如字符串第一个字或最后一个字为空白字符时，需要二个替换字符 (就算前后有「字符串边界」也一样)。
建议固定采用二个替换符，避免显示错误

符号替换 (Replacements Substitutions)

  • ⇐ 左双箭头 ← 左箭头 破折号 — 右箭头 → 右双箭头 ⇒

  • 版权© 注册商标® 商标™ 省略号 …​

  • We couldn’t find Olaf’s keyboard since the ’60s.

示例：

  • ⇐ 左双箭头 ← 左箭头 破折号 — 右箭头 → 右双箭头 ⇒

  • 版权© 注册商标® 商标™ 省略号 …​

  • We couldn’t find Olaf’s keyboard since the ’60s.

链接

在标题中指定锚点 (ID)

[[linkx,label]]
== 链接

其中的 label 为选项功能，不设置时为标题名称。设置时，则会影响 连接 的名称，本例是设置为 Link-Label。

亦可采用下列格式

[#link]
== 链接

连接至内部或其他文档锚点 (宏替换 Macros Substitutions)，语法如下：

标题名称

在不同的文档中，锚点ID 必须前置文档名称如 adoc-syntax#link。如果是本文档则锚点为 锚点ID 或 #锚点ID 都可以。不指定 标题名称 则为缺省的名称。 注：原始语法就需要两个小于 ( << ) 及两个大于 ( >> )，跟防替代没有关系。

链接-标题 其中的标题名称若不设置，则会显示成 「锚点ID」。

<> <<#link>> <>
<<#link, 我的链接>>

link:#link[Alias]]
link:#link[]

  1. 加号 + 为换行替换 (Post Replacement Substitutions)。

连接至外部网址

https://asciidoctor.org/docs/user-manual/#url[URLs | Asciidoctor User Manual icon:external-link[set=fas]^]

在 [ 链接文本 ] 内的尾端加入 ^ (脱字符) 将以新分页打开链接。 另外 Icon 在 Font Awesome 4.x 为 external-link[set=fas]；5.x 为 external-link-alt[set=fas]。

防止替换

  • \ 转义

  • ` 转义

  • + 转义

  • 三个 + 转义

  • pass:[ 需要转移的内容（如html）] 转义

列表 (List)

无序列表

示例：* deep 1
示例：** deep 2
示例：* deep 3…​5

  • one

  • two

  • three

  • one

  • one

  • one

  • one

  • deep 1

    • deep 2

      • deep 3

有序列表

. Order 1
. Order 2
.. Order 2a
.. Order 2b
. Order 3

[start=3]

  1. Order 3

  2. Order 4

反转列表 [%reversed] 数值反排列

[%reversed]

  1. Order 3

  2. Order 2

  3. Order 1

检查清单 Checked list

  • checked

  • checked

  • unchecked

  • normal

如果是行内的 checked 可采用 icon:check-square-o[] checked，
unchecked 则为 icon:square-o[] unchecked。

[options="interactive"]

  • Milk 请按我取消打勾

  • Chocolate

  • Sugar

描述列表 (Description)

CPU:: The brain of the computer. Hard drive:: Permanent storage for operating system and/or user files./

CPU

The brain of the computer.

Hard drive

Permanent storage for operating system and/or user files.

要使描述和内容显示在同一行上，则加入水平样式 [horizontal]。

[horizontal] CPU:: The brain of the computer. Hard drive:: Permanent storage for operating system and/or user files./

CPU

The brain of the computer.
Hard drive

Permanent storage for operating system and/or user files.
Operating Systems
Linux

  1. Fedora

    • Desktop

  2. Ubuntu

    • Desktop

    • Server

BSD

  1. FreeBSD

  2. NetBSD

描述列表问题

原代码区块的标注 (Callouts) 之后如果有「描述列表」，如果要分开「描述列表」，增加空行及注解来解决。 事实上，不只区块会有非预期合并的情况，「水平分隔线」也可能合并，需要增加空行及注解来分开。

Q&A

  1. What is Asciidoctor?

    An implementation of the AsciiDoc processor in Ruby.

  2. What is the answer to the Ultimate Question?

    42

区块 (Block)

[source,语言高亮度,subs="增减替换[, 增减替换]"]

(Name)

require 'sinatra' (1)
get '/hi' do (2) (3)
  "Hello World!"
end
1 Library import
2 URL mapping
3 Response block
xml 一样可以用标注
<section>
  <title>Section Title</title> (1)
</section>
1 The section title is required.
引入源代码
Unresolved directive in blog_asciidoc.adoc - include::app.rb[]
引入相对位置源代码
package org.shoulder.docs.start;


/**
 * Just test include
 *
 * @author lym
 */
public class Test {

}
引入源码部分行
Unresolved directive in blog_asciidoc.adoc - include::lib/document.rb[lines=5..10]

代码列表块启动语法高亮可以在文档头中设置。

  • 高亮属性有 coderay、highlightjs、prettify 和 pygments。

  • 如：:source-highlighter: pygments

内部使用 asciidoc 语法

System.out.println("Hello bold text").
Title (这是代码)
Example
Example 1. Title (这是范例)

Example

Title (这是花絮)

Sidebar

自定义代码块语法
<dependency>
  <groupId>org.asciidoctor</groupId>
  <artifactId>asciidoctor-java-integration</artifactId>
  <version>{version}</version>
</dependency>
nowrap 代码
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(".*");
   }
}
带标题的列表块
GEM
  remote: https://rubygems.org/
  specs:
    asciidoctor (1.5.6.1)

PLATFORMS
  ruby

DEPENDENCIES
  asciidoctor (~> 1.5.6.1)

组件图

component diagram

序列图

sequence diagram

提示

+++.NOTE, TIP, WARNING, CAUTION, IMPORTANT+++

NOTE: Note

TIP: Tip

WARNING: Warning

CAUTION: Caution

IMPORTANT: Important
Note
Title
title Tip
Warning
Caution
Important

ruby, asciidoctor

外框：

无外框
外框为范例区块
外框为花絮区块

嵌套

第一层

第二层

花絮区块 (第二层)

花絮区块 (第三层)

原代码区块
-----
原代码区块，不支持多层。
-----

引言 (Quote)

行1 行2

— 作者 (选项)
出处 (选项)

诗句 (Verse)

诗句 (Verse)
行1
行2
— 作者 (选项)
出处 (选项)