AsciiDoc是VSCode中比Markdown更强大严谨的轻量级标记语言，需安装asciidoctor.asciidoctor-vscode扩展、配置asciidoctor路径、用.adoc后缀和=标题启用预览、利用角色/块属性等语法增强表达，并通过Export导出PDF/EPUB。
如果您希望在VSCode中使用一种比Markdown功能更丰富、结构更严谨的轻量级标记语言来编写技术文档，则AsciiDoc是一个值得深入使用的选项。以下是关于在VSCode中配置与使用AsciiDoc的具体说明：
本文运行环境：MacBook Air，macOS Sequoia。
一、安装AsciiDoc扩展
VSCode本身不原生支持AsciiDoc渲染与预览，需通过官方推荐的扩展启用完整功能。该扩展提供语法高亮、实时预览、代码片段及导出能力。
1、打开VSCode，点击左侧活动栏的扩展图标（或按快捷键Ctrl+Shift+X）。
2、在搜索框中输入AsciiDoc，找到由asciidoctor.asciidoctor-vscode发布的扩展。
3、点击“安装”，安装完成后重启VSCode以激活全部功能。
二、配置AsciiDoc处理器路径
AsciiDoc扩展依赖本地AsciiDoc处理器（如Asciidoctor）执行解析与转换。若未配置可执行路径，预览将无法正常工作。
1、打开VSCode设置（Cmd+,），切换至“工作区”标签页。
2、在搜索框中输入asciidoctor.asciidoctorPath。
3、点击“编辑 in settings.json”，在JSON中添加键值对："asciidoctor.asciidoctorPath": "/usr/local/bin/asciidoctor"（路径需与实际安装位置一致）。
三、启用实时HTML预览
AsciiDoc扩展默认支持内联预览，但需确保文档保存为.adoc后缀且文件头包含有效文档声明，否则渲染可能不完整。
1、新建文件，保存为README.adoc。
本文档是OpenGL入门教程；目的是让大家放弃TC的老旧图形接口，让大家接触一些新事物。OpenGL作为当前主流的图形API之一，它在一些场合具有比DirectX更优越的特性。OpenGL（全写Open Graphics Library）是指定义了一个跨编程语言、跨平台的编程接口规格的专业的图形程序接口。它用于三维图像（二维的亦可），是一个功能强大，调用方便的底层图形库。有需要的朋友可以下载看看
2、在首行输入文档标题，格式为= 文档标题。
3、按下Cmd+K V组合键，触发AsciiDoc预览面板，内容将以HTML形式动态渲染。
四、使用AsciiDoc特有语法增强表达力
相较于Markdown，AsciiDoc原生支持角色（role）、块属性（block attributes）、条件包含（ifdef）、自定义样式等高级特性，适用于复杂文档结构。
1、为段落添加CSS类：在段落前插入[.highlight]#这是高亮段落#。
2、插入带编号的代码块：在代码块上方添加[source,rust,linenums]，随后换行输入代码。
3、创建多级目录：在文档顶部添加:toc: left和:toclevels: 3，保存后预览自动显示导航侧边栏。
五、导出为PDF或EPUB格式
AsciiDoc扩展集成了Asciidoctor工具链，可直接调用命令行工具生成高质量出版级输出，无需离开编辑器。
1、确保系统已安装asciidoctor-pdf：在终端执行gem install asciidoctor-pdf。
2、右键点击.adoc文件编辑区域，选择AsciiDoc: Export Document As...。
3、从弹出菜单中选择PDF，导出文件将保存在当前项目根目录下。
