使用VSCode编写和预览AsciiDoc与reStructuredText

在VSCode中实现AsciiDoc与reStructuredText实时预览需安装对应插件、配置处理器路径、关联文件类型并启用预览命令：先安装AsciiDoc和reStructuredText扩展，再分别配置Asciidoctor和docutils环境，最后设置文件关联与预览行为。

如果您在VSCode中编写AsciiDoc或reStructuredText文档，但无法实时预览渲染效果，可能是由于缺少对应语言支持或预览插件未正确配置。以下是实现编写与预览功能的具体操作步骤：

本文运行环境：MacBook Air，macOS Sequoia。

一、安装核心扩展插件

VSCode本身不原生支持AsciiDoc和reStructuredText的语法高亮与预览，需依赖社区开发的扩展提供解析与渲染能力。安装适配度高、维护活跃的插件是启用功能的前提。

1、打开VSCode，点击左侧活动栏的扩展图标（或按快捷键Ctrl+Shift+X）。

2、在扩展搜索框中输入AsciiDoc，找到由asciidoctor官方推荐的AsciiDoc by AsciiDoc VSCode Extension，点击安装。

3、再次搜索reStructuredText，选择由lextm发布的reStructuredText by LeXtudio并安装。

4、安装完成后，重启VSCode以确保语言服务器完全加载。

二、配置AsciiDoc预览行为

AsciiDoc插件默认启用侧边预览面板，但需确认是否启用实时刷新及是否绑定正确的Asciidoctor处理器路径。本地未安装Asciidoctor时，插件将回退至内置轻量解析器，部分宏与自定义属性可能不生效。

1、按下Cmd+,（macOS）打开设置界面，切换至“工作区”标签页。

2、在搜索框中输入asciidoc.preview.refreshDelay，将其值设为500（毫秒），以平衡响应速度与资源占用。

3、检查asciidoc.use_asciidoctor_js是否为true；若需完整特性支持，应设为false，并确保系统已通过gem安装asciidoctor：gem install asciidoctor。

4、保存设置后，在任意.adoc文件中右键，选择“Open Preview to the Side”，即可启动双向同步预览。

三、启用reStructuredText实时HTML预览

reStructuredText插件依赖Python环境中的docutils库完成解析。预览功能基于本地生成临时HTML并调用VSCode内置Webview展示，不依赖外部浏览器进程。

1、确认系统已安装Python 3.8及以上版本，并在终端执行pip install docutils。

Icons8 Background Remover

Icons8出品的免费图片背景移除工具

31

查看详情

2、在VSCode中打开命令面板（Cmd+Shift+P），输入并选择reStructuredText: Preview。

3、预览窗口首次加载较慢，因需初始化docutils解析器；后续编辑将触发自动刷新，延迟约1–2秒。

4、如需调整样式，可创建.rst同目录下的conf.py文件，配置html_theme = 'sphinx_rtd_theme'等选项（需额外安装sphinx）。

四、统一文件关联与默认格式识别

VSCode需明确将.adoc与.rst后缀关联至对应语言模式，否则无法触发语法高亮、代码片段及预览指令。手动设置可避免因文件名不规范导致的功能失效。

1、打开任意一个未识别的.adoc文件，点击右下角显示为“Plain Text”的语言模式按钮。

2、在弹出菜单中选择Configure File Association for '.adoc'，然后选择AsciiDoc。

3、对.rst文件重复相同操作，选择reStructuredText作为默认语言模式。

4、该设置将写入当前工作区的.vscode/settings.json，确保团队协作时格式一致性。

五、使用多光标与片段提升编写效率

两种标记语言均支持VSCode内置代码片段功能，配合多光标编辑可批量插入常用结构，减少重复输入。插件自带基础片段，亦支持用户自定义。

1、在AsciiDoc文件中输入sect2后按Tab，自动展开为二级章节模板，标题处进入可编辑状态。

2、在reStructuredText文件中输入section后按Tab，生成带下划线的章节标题行。

3、按住Option键（macOS）并点击多个位置，创建多个光标；输入相同内容（如角色引用:code:`xxx`）可一次性填充所有选中区域。

4、如需添加自定义片段，打开命令面板，输入并选择Preferences: Configure User Snippets，选择对应语言，按格式添加JSON条目。

以上就是使用VSCode编写和预览AsciiDoc与reStructuredText的详细内容，更多请关注php中文网其它相关文章！