文档技术方案选型:AsciiDoc vs Markdown

文档技术方案选型:AsciiDoc vs Markdown

D瓜哥在前面的文章 使用 Hugo 搭建博客 中介绍了如何用 Hugo 搭建个人博客。部门准备系统地整理一下各个小组的文档。恰好 D瓜哥 对写文档非常感兴趣,正好写个材料分享一下血泪经验。

编辑进化之路

第一代:WordPress

wordpress

缺点:写作和排版割裂,排版耗时且繁琐

第二代:MarkDown

markdown

缺点:方言众多,工具链不够完整。

现在已经改观很多。

第三代:AsciiDoc

asciidoc

轻量级标记语言的优点

思路与格式融为一体

在整理文档时,随手加入格式管理,不需要为格式分心,也无须浪费时间调整排版。

代码高亮

AsciiDoc 与 MarkDown 都支持

/**
 * @author D瓜哥 · https://www.diguage.com/
 */
public class Main {
    public static void main(String[] args) {
        System.out.println("Hello, D瓜哥!");
    }
}

文本格式

  • 文本格式,天然跨平台,支持性好,方便编辑与管理。

  • 结合 Git,支持版本管理。

生态完善

Markdown

  1. Hugo: The world’s fastest framework for building websites — Hugo 使用 yuin/goldmark: A markdown parser written in Go. 来做转换工作。也支持 AsciiDoc,不过需要挑选比较合适的主题: Hugo Themes

AsciiDoc

  1. Antora — The multi-repository documentation site generator for tech writers who writing in AsciiDoc.

  2. Asciidoctor Diagram — 支持多种文本画图工具。

  3. Asciidoctor EPUB3 Documentation — 可以直接将 AsciiDoc 文档转化成 EPUB 电子书。

  4. Asciidoctor PDF — 可以直接将 AsciiDoc 文档转化成 PDF 文档。

  5. 常见插件的支持:Maven、IntelliJ IDEA、VS Code 等。

语法对比

Table 1. A selection of AsciiDoc language features compared to Markdown
Language FeatureMarkdownAsciiDoc

Bold (constrained)

**bold**
*bold*

Bold (unconstrained)

**b**old
**b**old

Italic (constrained)

*italic*
_italic_

Italic (unconstrained)

n/a

__i__talic

Monospace (constrained)

`monospace`
`monospace`

Monospace (unconstrained)

`m`onospace
``m``onospace

Literal monospace

`http://localhost:8080`
`/issue/{id}`
`+http://localhost:8080+`
`+/issue/{id}+`

Link with label

[Asciidoctor](https://asciidoctor.org)
https://asciidoctor.org[Asciidoctor]

Relative link

[user guide](user-guide.html)
link:user-guide.html[user guide]
xref:user-guide.adoc[user guide]

File link

[get the PDF]({% raw %}{{ site.url }}{% endraw %}/assets/mydoc.pdf)
link:{site-url}/assets/mydoc.pdf[get the PDF]

Cross reference

See [Usage](#_usage).

<h2 id="_usage">Usage</h2>
See <<_usage>>.

== Usage

Block ID (aka anchor)

<h2 id="usage">Usage</h2>
[#usage]
== Usage

Inline anchor

n/a

. [[step-1]]Download the software

Inline image w/ alt text

![Logo](/images/logo.png)
image:logo.png[Logo]

Block image w/ alt text

n/a

image::/logo.png[Logo]

Section heading*

## Heading 2
== Heading 2

Blockquote*

> Quoted text.
>
> Another paragraph in quote.
____
Quoted text.

Another paragraph in quote.
____

Literal block

    $ gem install asciidoctor
Indented (by 1 or more spaces)
 $ gem install asciidoctor
Delimited
....
$ gem install asciidoctor
....

Code block*

```java
public class Person {
  private String name;
  public Person(String name) {
    this.name = name;
  }
}
```
[source,java]
----
public class Person {
  private String name;
  public Person(String name) {
    this.name = name;
  }
}
----

Unordered list

* apples
* orange
  * temple
  * navel
* bananas
* apples
* oranges
** temple
** navel
* bananas

Ordered list

1. first
2. second
3. third
. first
. second
. third

Thematic break (aka horizontal rule)*

***

* * *

---

- - -

___

_ _ _
'''

Typographic quotes (aka “smart quotes”)

Enabled through an extension switch, but offer little control in how they are applied.

The `'90s popularized a new form of music known as "`grunge`" rock.
It'll turn out to have an impact that extended well beyond music.

Document header

Slapped on as “front matter”
---
layout: docs
title: Writing posts
prev_section: defining-frontmatter
next_section: creating-pages
permalink: /docs/writing-posts/
---
Native support!
= Writing posts
:page-layout: base
:showtitle:
:prev_section: defining-frontmatter
:next_section: creating-pages

Admonitions

n/a

TIP: You can add line numbers to source listings by adding the word `numbered` in the attribute list after the language name.

Sidebars

n/a

.Lightweight Markup
****
Writing languages that let you type less and express more.
****

Block titles

n/a

.Grocery list
* Milk
* Eggs
* Bread

Includes

n/a

include::intro.adoc[]

URI reference

Go to the [home page][home].

[home]: https://example.org
:home: https://example.org

Go to the {home}[home page].

Custom CSS classes

n/a

[.path]_Gemfile_

AsciiDoc 的亮点

AsciiDoc 与 MarkDown 差别很小,AsciiDoc 几乎完全兼容 MarkDown 的语法。

更多图表

asciidoctor diagram kroki cheatsheet

其他图表支持见:

支持“文档分段”

= 如何一夜暴富?

include::chapter-01.adoc[leveloffset=+1]

include::chapter-02.adoc[leveloffset=+1]

include::chapter-03.adoc[leveloffset=+1]

优点:各个文档相互独立,方便协作。

支持自动生成目录

只需要添加几条设置就可以自动生成目录,而且可以控制目录层级以及目录的位置(页头,左侧或者右侧等)。

自动导入代码

可以自动带入代码以及代码段,方便后期维护(只需要修改代码,文档中的内容自动修改)。

总结

如果说 MarkDown 是排版的小学生,那么 AsciiDoc 则是排版的大学生。

markdown vs asciidoc catalog

产品文档解决方案

可选方案一共三种:

  1. Antora

  2. Hugo

  3. AsciiDoctor

Antora

简介

Antora: The multi-repository documentation site generator for tech writers who writing in AsciiDoc.

antora

优点:

  1. 专门的技术文档解决方案

  2. 支持多仓库

  3. 基于 AsciiDoc,功能强大

示例,docs.asciidoctor.org:

Quickstart: Playbook

antora-playbook.yml
site:
  title: Antora Docs
  start_page: component-b::index.adoc
content:
  sources:
  - url: https://gitlab.com/antora/demo/demo-component-a.git
    branches: HEAD
  - url: https://gitlab.com/antora/demo/demo-component-b.git
    branches: [v2.0, v1.0]
    start_path: docs
ui:
  bundle:
    url: https://gitlab.com/antora/antora-ui-default/-/jobs/artifacts/HEAD/raw/build/ui-bundle.zip?job=bundle-stable
    snapshot: true

Quickstart: Standard File and Directory Set

📒 repository
  📄 antora.yml ------ 配置
  📂 modules --------- 必选目录
    📂 ROOT ---------- 可选目录,
      📁 attachments - 附件
      📁 examples ---- 示例
      📁 images ------ 图片
      📁 pages ------- 文档
      📁 partials ---- 片段文档
      📄 nav.adoc  --- 菜单
    📂 named-module -- 其他模块目录
      📁 pages
      📄 nav.adoc
  📁 packages -------- 不处理(非 modules 子目录都不处理)

Hugo

简介

Hugo: The world’s fastest framework for building websites.

hugo logo

Kubernetes 的文档 就是基于 Hugo 来发布的。

Quickstart

$ tree diguage.com
diguage.com
├── archetypes
│   └── default.md
├── config.toml # 配置文件
├── content     # 以后的文章就放在这个目录下
├── data
├── layouts
├── static      # 这里存放静态资源文件,比如 CSS、JS 以及图片
└── themes      # 这里存放主题

主题推荐:Docsy

Docsy is a theme for the Hugo static site generator that’s specifically designed for technical documentation sets.

该注意由 Google 开发,Kubernetes 使用的主题。支持文档和博客。

AsciiDoctor

可以直接使用 AsciiDoctor 来编写,自己写命令行来处理。

优点:

  1. 上手容易;

  2. AsciiDoctor 生态支持最好;

  3. 可以一键导出 HTML、PDF 和 ePub 等格式。

示例:

发布方式

通过命令行将文档转化成 HTML,申请一台服务器,使用 Nginx 发布成网页即可。示例如下:

如果需要 PDF 文档,可以再将网页转化成 PDF: WK<html>TOpdf

如果使用 AsciiDoctor,则可以直接使用工具链生成 PDF 出来,示例: JDK 源码分析,配置好插件,支持一键导出成 PDF。

以终为始

你的选择

  • Antora

  • Hugo

  • AsciiDoctor

  • Confluence