使用 VScode+AsciiDoc 设计文档

作为一个强大的开发工具编辑器，支持所有语言开发，插件生态丰富到无法想象，直接作为前端开发的首选利器，不必详细介绍。

Markdown 语法简洁，即便阅读未经渲染的源文件也有不错的可读性。但它对于较为复杂的格式例如表格的支持始终遭人诟病，许多网站使用各自不同的扩展语法来实现，也从而导致了各种方言的滋生。这也是为何会出现 Standard Markdown 项目的原因，虽然因为种种原因又更名为 Common Markdown，然而整个 Markdown 社区依然缺乏创建者的支持，Common Markdown 也很可能沦为另一个方言。

在 Java 社区随处可见 AsciiDoc 文档，spring 家族许多文档都是 AsciiDoc 编写，语法与 Markdown 类似，但比后者支持更多技巧。

第一次接触到 AsciiDoc 是通过 O’Reilly 的图书，Atlas 的推荐语言就是 AsciiDoc。那么十多种标记语言中，为什么要选择 AsciiDoc 呢？其实在选择另一种标记语言时，我做过一些简单的研究:

• LaTex : 大名鼎鼎的 LaTex 是除了 Markdown 之外我第一个投入精力学习的标记语言。不得不说 LaTex 十分强大，但与这份强大伴随而来则是复杂的语法，导致了写作过程的枯燥，也让我失去了对 LaTex 的兴趣。

• reStructuredText : REST 也是一种松散的文本结构，功能也较为全面，但书写起来更像是在写 Python。

• Org mode : 我想基本上只有 Emacs 社区的人在使用了吧。

• Texy!，BBCode，Creole，Textile…​ : 事实上大部分轻量级的标记语言语法都较为类似，所以这场抉择很大程度上是使用范围、功能、兼容性、扩展性等多方面的比赛，这也是我为什么不选择这些语言的原因。

AsciiDoc 的语法与 Markdown 十分类似，在学会 Markdown 的前提下很容易转向 AsciiDoc 阵营。

在的功能方面，前面已经说过许多功能 Markdown 要通过扩展语法和 HTML 来实现，前者直接导致了通用性的缺失，后者提高了后期编撰的成本，而 AsciiDoc 的学习成本也远不及多学一门 HTML 甚至多种扩展语法。

AsciiDoc 原生支持的特性就足以应付大多数电子文档的编撰需求，你可以使用标准的 AsciiDoc 语法为你的文档添加作者信息、版本信息、表格等特性，它还支持文档引入、自定义块语法等功能。

基于 Draw.io VS Code Integration 插件，可以把 drawio 绘图插入到 `AsciiDoc`中，详见工程中示例

• 具体实现

  • 安装 Draw.io VS Code Integration 插件,基于此工程更顺利，已内置好配置

  • 在目录中建立 .drawio.svg 或 .drawio.png 文件，如：test.drawio.svg 双击打开便可以自由绘图, 与 `drawio`在线绘图或本地客户端绘图效果一样，无法这样是直接保存为图片模式

  • 在 AsciiDoc 中 使用引用图片语法即可，如：

Excalidraw 可以自由绘图，相比较 Draw.io 更自由一点，`Draw.io`更专业，都有自己的独特之处，选择适合自己的更重要

基于 Excalidraw 插件，可以自由绘图并插入到 `AsciiDoc`中，详见工程中示例

1. 具体实现

   • ** 安装`Excalidraw`插件,基于此工程更顺利，已内置好配置

     • 在目录中建立 .excalidraw.svg 或 .excalidraw.png 文件，如：test.excalidraw.svg 双击打开便可以自由绘图

     • 在 AsciiDoc 中 使用引用图片语法即可，如：

语法详见 [PlantUML](https://plantuml.com/zh/)

基于 PlantUML`插件进行编辑 `UML,如果离线操作需要安装`Java` 相关驱动,基于此工程更顺利，已内置好相关配置，在线服务

puml 或者 plantuml 代码块中的内容将会被 PlantUML 渲染。

完整 的 AsciiDoc PlantUML 示例 详见 index.adoc

官网[Mermaid](https://mermaid.js.org/) > Mermaid 是一个基于 JavaScript 的图表和图表工具，相比较`PlantUML`更友好，选择适合自己的即可，不满足需求可两者结合使用

安装`Markdown Preview Mermaid Support`和 Mermaid Markdown Syntax Highlighting 插件

mermaid 代码块中的内容将会渲染 mermaid 图像。

完整 的 Markdown Mermaid 示例 详见 index.adoc

官网 [WaveDrom](https://wavedrom.com/)

wavedrom 代码块中的内容将会被 WaveDrom 渲染。

完整 的 AsciiDoc WaveDrom 示例 详见 index.adoc

官网[GraphViz](https://viz-js.com/)

viz 或者 dot 代码块中的内容将会被 Viz.js 渲染。 你可以通过 {engine="…​"} 来选择不同的渲染引擎。 引擎 circo，dot，neato，osage，或者 twopi 是被支持的。默认下，使用 dot 引擎。

完整 的 AsciiDoc GraphViz 示例 详见 index.adoc

官网[Vega & Vega-Lite](https://vega.github.io/)

vega 代码块中的内容将会被 vega 渲染。 vega-lite 代码块中的内容将会被 vega-lite 渲染。 JSON 以及 YAML 的输入是支持的。

完整 的 AsciiDoc Vega 示例 详见 index.adoc

asciidoctor-vscode vscode插件

AsciidocFX 是一款开源 GUI 编辑器。

来自 Github 的 Atom, 需要额外安装插件。

AsciiDocor 是一个使用 Ruby 实现的 AsciiDoc 转换工具。你可以通过 gem install asciidoctor 进行安装。

AsciiDoctor.js Live Editor

AsciiDoc Live

Markdown to AsciiDoc