使用 VScode+AsciiDoc 设计文档

我们平常写文档，最常见的便是 office 全套，技术人员则更倾向于 Markdown 编辑文档，当然这也是许多框架技术默认的文档编辑,今天则给大家推荐一套强大文档编辑组合 VScode+AsciiDoc

关于

轻量级的标记语言已经有很多，例如我用来写博客的 Markdown 就是目前十分流行的一种轻量级标记语言，包括 Github、StackOverflow 等很多网站以及个人都在使用。

VScode

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

Markdown 还不够吗

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

Figure 1. Markdown Standards

AsciiDoc

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

为什么选择 AsciiDoc

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

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

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

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

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

AsciiDoc 与 Markdown

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

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

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

默认配置的 VScode 插件

• Asciidoc 插件 asciidoctor.asciidoctor-vscode

• Draw.io`插件 `hediet.vscode-drawio

• Draw.io`插入`mermaid`的插件 `nopeslide.vscode-drawio-plugin-mermaid

• Excalidraw 插件 pomdtr.excalidraw-editor

• PlantUML`插件 `jebbs.plantuml

AsciiDoc 语法

完整 的 AsciiDoc 语法 详见 index.adoc

数学公式

完整 的 AsciiDoc 数学公式语法 详见 index.adoc

画图

Draw.io 绘图

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

• 具体实现

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

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

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

Excalidraw 白板

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

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

1. 具体实现

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

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

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

PlantUML `UML`绘图

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

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

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

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

Mermaid 绘图

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

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

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

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

WaveDrom 绘图

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

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

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

GraphViz 绘图

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

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

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

Vega 和 Vega-lite 图表

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

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

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

工具

VSCode

asciidoctor-vscode vscode插件

AsciidocFX

AsciidocFX 是一款开源 GUI 编辑器。

Figure 2. AsciidocFX

Atom

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

Figure 3. Atom

AsciiDoctor

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

asciidoctor MyDoc.adoc

asciidoctor -a stylesheet golo.css -o MyHTML.html MyDoc.adoc

Figure 4. AsciiDoctor

AsciiDoctor.js Live Editor

AsciiDoctor.js Live Editor

AsciiDoc Live

AsciiDoc Live

Kramdown AsciiDoc (Markdown to AsciiDoc)

Markdown to AsciiDoc

Stylesheets

• asciidoctor.css: (预览)

• colony.css: (预览)

• foundation-lime.css: (预览)

• foundation-potion.css: (预览)

• foundation.css: (预览)

• github.css: (预览)

• golo.css: (预览)

• iconic.css: (预览)

• maker.css: (预览)

• readthedocs.css: (预览)

• riak.css: (预览)

• rocket-panda.css: (预览)

• rubygems.css: (预览)

• boot-darkly.css: (预览)

如有建议或想法请大家 issues