AsciiDoc快速入门教程：轻量级标记语言详解

AsciiDoc快速入门教程：轻量级标记语言详解

learnxinyminutes-docs Code documentation written as code! How novel and totally my idea! 项目地址: https://gitcode.com/gh_mirrors/le/learnxinyminutes-docs

什么是AsciiDoc

AsciiDoc是一种轻量级标记语言，类似于Markdown，但功能更为强大。它由Stuart Rackham于2002年创建，适用于从书籍到博客等各种文档编写场景。与Markdown相比，AsciiDoc提供了更丰富的格式控制选项，同时保持了简洁易用的特点。

文档头部结构

AsciiDoc文档的头部是可选的，但必须遵循特定格式规则：

仅标题

= 文档标题

这里是文档的第一句话。

带作者信息

= 文档标题
张三 <zhangsan@example.com>

文档正文开始部分。

多作者情况

= 文档标题
李四 <lisi@test.com>; 王五 <wangwu@demo.com>; 赵六 <zhaoliu@sample.com>

多作者文档的起始部分。

带版本信息

= 文档标题 V1.0
文档作者 <author@example.com>
v1.0, 2023-05-20

这里是文档的引言部分。

段落与换行

AsciiDoc中的段落处理非常简单自然：

段落之间只需空一行即可分隔。

这是第二个段落。

要强制换行而不开始新段落，+
可以在行末使用加号。

文本格式化

AsciiDoc提供了多种文本格式化选项：

_下划线表示斜体_
*星号表示粗体*
*_可以组合使用_*
`反引号表示等宽字体`
`*等宽加粗*`

标题层级

AsciiDoc支持多级标题，最多可达5级：

= 一级标题（仅用于文档标题）

== 二级标题

=== 三级标题

==== 四级标题

===== 五级标题

列表处理

无序列表

使用星号创建无序列表：

* 项目一
* 项目二
* 项目三

有序列表

使用点号创建有序列表：

. 第一项
. 第二项
. 第三项

嵌套列表

通过增加星号或点号数量实现嵌套，最多支持5级：

* 一级
** 二级
*** 三级
**** 四级
***** 五级

. 一级
.. 二级
... 三级
.... 四级
..... 五级

高级特性

除了上述基础语法，AsciiDoc还支持：

1. 表格：可以创建复杂的数据表格
2. 代码块：支持语法高亮
3. 交叉引用：文档内部链接
4. 注释：添加不影响输出的注释
5. 包含指令：引用其他文件内容

处理工具

目前主要有两种AsciiDoc处理工具：

1. AsciiDoc：原始的Python实现，稳定但处于维护模式
2. Asciidoctor：基于Ruby的实现，支持更多新特性和输出格式

学习建议

对于初学者，建议从基础语法开始，逐步掌握更复杂的特性。可以先尝试编写简单的文档，然后逐步添加格式化元素、列表和标题等。随着熟练度提高，可以探索表格、代码块等高级功能。

AsciiDoc特别适合需要精细控制文档格式，但又不想使用复杂排版工具的场景。它的语法直观，学习曲线平缓，是技术文档写作的优秀选择。

learnxinyminutes-docs Code documentation written as code! How novel and totally my idea! 项目地址: https://gitcode.com/gh_mirrors/le/learnxinyminutes-docs