= ASCIIDoc 完整指南
:author: 文档作者
:email: author@example.com
:doctype: book
:toc: auto
:toclevels: 4
:numbered:
:icons: font
:sectanchors:
:source-highlighter: rouge
:revnumber: 1.0
:revdate: 2023-10-20

// 文档元数据 (头部属性)
:description: ASCIIDoc完整语法指南
:keywords: ASCIIDoc, 文档编写, 技术写作

[[introduction]]
== 第一章：基础语法

=== 文档结构
[source,asciidoc]
----
= 文档标题（仅限1个）
== 章节标题
=== 小节标题
==== 子小节标题
[discrete]  // 不列入目录的标题
===== 迷你标题（通常不推荐）
----

=== 段落与换行
普通段落之间需要空一行分隔。 +
使用`+`符号实现<<line-break,硬换行>>。

[NOTE]
.段落特性
- 自动换行（软换行）
- 支持 `.lead` 样式作为导语段落
- 可使用 `[.underline]` 等类名

[.lead]
这是引导段落，通常用于文章开头。

=== 文本样式
* *粗体文本* 或 **粗体替代语法**
* _斜体文本_ 或 __斜体替代语法__
* `等宽字体` 或 ``双反引号语法``
* ~删除线~ 或 ~~替代语法~~
* ^上标^ 例如 x^2^
* ~下标~ 例如 H~2~O
* [.underline]#下划线文本#
* [.line-through]#另一种删除线#
* 高亮标记 #Marked text#

=== 特殊字符
[%hardbreaks]
© 版权符号 | ® 注册商标
™ 商标 | ← 箭头
€ 欧元 | £ 英镑

[[lists]]
=== 列表系统

==== 无序列表
* 一级项目
** 二级项目
*** 三级项目
- 替代符号
+ 另一种样式

==== 有序列表
. 第一项
.. 子项
... 子子项
) 字母编号
a. 小写字母
A. 大写字母
i. 罗马数字(小写)
I. 罗马数字(大写)

==== 描述列表
CPU:: 中央处理器
GPU::
  图形处理器
  包含3D渲染单元

[[tables]]
=== 表格系统

[cols="1,2,1"]  // 列宽定义
|===
| 左对齐 | 居中对齐 | 右对齐

^| 表头1 ^| 表头2 ^| 表头3
>| 右对齐 |< 左对齐 |> 右对齐
2+| 合并两列 | 正常列
|===

// 高级表格示例
[%header,cols="30%,70%"]
|===
| 属性 | 描述

| `:toc:`
| 自动生成目录

| `:numbered:`
| 启用章节编号
|===

[[code]]
=== 代码与文本块

==== 基础代码块
[source,java]
----
public class Hello {
    public static void main(String[] args) {
        System.out.println("Hello ASCIIDoc!");
    }
}
----

==== 带行号和高亮
[source,ruby,linenums,highlight=2-3]
----
require 'sinatra'

get '/hello' do  # <1>
    "Hello World!"
end
----
<1> 这是路由定义

==== 其他文本块类型
[quote]
____
这是引用文本块
来自某著名书籍
____

[verse]
____
诗歌格式块
保留换行和缩进
____

[[multimedia]]
== 第二章：多媒体元素

=== 图像系统
image::sunset.jpg[日落照片, width=600, height=400, align=center]

// 内联图片
image:moon.png[月亮图标, width=24]

=== 视频嵌入
video::video123.mp4[width=640, height=360, options=autoplay]

=== 图表支持
[plantuml]
----
@startuml
Alice -> Bob: Authentication Request
Bob --> Alice: Authentication Response
@enduml
----

[[advanced]]
== 第三章：高级功能

=== 文档包含
include::chapters/introduction.adoc[]

=== 条件编译
ifdef::env-github[]
仅在GitHub环境显示的内容
endif::[]

ifndef::production[]
非生产环境显示警告
endif::[]

=== 属性系统
:baseurl: https://example.com
:imagesdir: assets/images

查看我们的 {baseurl}[官网]

=== 用户宏
// 定义宏
:google: https://google.com

// 使用宏
{google}[Google搜索]

=== 数学公式
[latexmath]
++++
\int_{a}^{b} x^2 \,dx
++++

=== 评论系统
// 单行注释

////
多行注释
不会出现在输出中
////

[[appendix]]
[appendix]
== 附录A：工具链

=== 转换命令
```bash
# 转换为HTML
asciidoctor document.adoc

# 转换为PDF
asciidoctor-pdf document.adoc

# 启用数学支持
asciidoctor -r asciidoctor-mathematical document.adoc

=== VS Code扩展推荐

• Asciidoctor扩展
• PlantUML支持
• 实时预览插件

== 参考资料

• https://asciidoctor.org/docs/user-manual/
• 《Asciidoctor权威指南》

关键特性说明：

1. **文档结构**：
   - 支持5级标题层次
   - 可禁用标题编号 `:numbered!:`
   - 离散标题不参与目录生成

2. **内容包含**：
   ```asciidoc
   include::content/{chapter}.adoc[leveloffset=+1]

3. 国际化：

   :lang: zh-CN
   :table-caption: 表
   :figure-caption: 图
   

4. 自定义模板：

   asciidoctor -T custom-templates/ document.adoc
   

5. 扩展集成：

   :revealjsdir: https://cdnjs.cloudflare.com/ajax/libs/reveal.js/3.9.2

最佳实践建议：
7. 保持每行不超过80字符
8. 使用imagesdir属性管理图片路径
9. 复杂表格建议使用CSV导入
10. 为代码块添加语言标识以获得语法高亮
11. 使用条件编译管理不同版本内容

转换输出示例：

# 生成带语法高亮的HTML
asciidoctor -r rouge -a source-highlighter=rouge doc.adoc

# 生成PDF（需安装asciidoctor-pdf）
asciidoctor-pdf -a pdf-style=default doc.adoc