AsciiDoc：发现并掌握语法以实现高效文档
Publié le 20 June 2025
引言
AsciiDoc 是一种轻量级标记语言，专为编写结构化的技术文档、文章、书籍或演示文稿而设计。它以其可读性、丰富的语法以及能够生成多种格式（HTML、PDF、DocBook 等）的能力而脱颖而出。本文将探讨 AsciiDoc 的基本语法，并提供一些快速上手的技巧。
什么是 AsciiDoc？
AsciiDoc 是一种文档描述语言，类似于 Markdown 但功能更强大。它能够高效地组织文本、标题、列表、表格、代码块等，而且还有更多功能。其多功能性使其成为开源项目文档、书籍撰写和网页发布的热门选择。
为什么选择 AsciiDoc？
-
语法易读且直观。
-
对复杂结构（表格、笔记、警告等）的原生支持。
-
多格式生成 (HTML, PDF, ePub, DocBook…)
-
与JBake或Antora等静态站点生成器实现轻松集成。
-
使用属性和扩展的高级自定义。
用例图 (Use Case)
用例图可以呈现用户与系统之间的主要交互。以下是一个文档系统的简单示例：
思维导图图
思维导图（脑图）非常适合用于探索与 AsciiDoc 相关的概念及其关系：
流程图（流量）
流程图可用于描述生成一个 AsciiDoc 文档的过程：
AsciiDoc 文件的基本结构
一个 AsciiDoc 文件通常以标题开始，然后是可选属性，随后是结构化内容。以下是一个最小示例：
= Titre Principal
Auteur
2024-09-03
:toc:
:icons: font
Votre contenu commence ici...基本语法
标题和章节
AsciiDoc 支持多个标题级别：
= Titre de niveau 1
== Titre de niveau 2
=== Titre de niveau 3
==== Titre de niveau 4粗体、斜体和等宽文本
*gras* _italique_ `monospace`项目符号列表和编号列表
* Élément 1
* Élément 2
. Premier
. Deuxième
. Troisième链接和图片
Lien standard : https://asciidoc.org[AsciiDoc]
Image : image::images/logo.png[AsciiDoc Logo]代码块
[source,python]def hello(): print("Bonjour AsciiDoc !")
表格
|===
| Colonne 1 | Colonne 2
| Valeur A
| Valeur B
| Valeur C
| Valeur D
|===注释和警告
AsciiDoc 提供可视化信息块：
NOTE: Ceci est une note importante.
TIP: Conseil utile pour l’utilisateur.
WARNING: Attention à ce point.使用属性和变量
自定义属性允许重用值或配置行为：
:project-name: AsciiDoc Explorer
Le projet s’appelle {project-name}.常见的用例
-
开源项目文档（README, 技术指南） 编写书籍和电子书 - 自动生成静态网站 (JBake, Antora) - 技术演示
最佳实践
-
使用一致的标题和自动目录 (:toc:). - 建议使用提示框来突出关键点。 - 组织您的文件以便于维护。 - 利用带注释的代码块来说明示例。
结论
AsciiDoc 是一种功能强大且易于使用的工具，可用于编写任何技术文档或结构化文章。其丰富的语法结合多格，使其成为开发者和要求严格的编辑者的理想伙伴。请在您的下一个项目中尝试使用 AsciiDoc，体验其中的差别！
更进一步
-
官方文档：https://asciidoc.org - Asciidoctor : https://asciidoctor.org - JBake 和 AsciiDoc : https://jbake.org/docs/2.6.4/#asciidoc_support
在评论中分享你的经验和技巧！