# Documentation Tools

## 工具評比文章

- [Markdown, Asciidoc, or reStructuredText - a tale of docs-as-code - Dewan’s Blog](https://www.dewanahmed.com/markdown-asciidoc-restructuredtext/)
- [Lightweight Markup: AsciiDoc, reStructuredText, and Markdown Compared | by Peter Conrad | Medium](https://stymied.medium.com/lightweight-markup-asciidoc-restructuredtext-and-markdown-compared-d5a33fedcac9)
- [Markdown, Asciidoc, or reStructuredText - a tale of docs-as-code - DEV Community](https://dev.to/dewanahmed/markdown-asciidoc-or-restructuredtext-a-tale-of-docs-as-code-3nj9)

## Markdown （md）

### 優點

- 簡單快速
- 很多人用
- 工具多 📈

### 缺點

- 沒有 table
- 不能嵌入 youtube 影片 (要用 HTML)，也許還有更多 HTML 或 JavaScript
- 好多 [Markdown Flavors](https://github.com/commonmark/commonmark-spec/wiki/markdown-flavors)

### 評論

- 專注在軟體文件的社群大大 Eric Holscher (co-founder of Read the Docs, Write the Docs, and EthicalAds) 說不要用 Markdown
[Why You Shouldn’t Use “Markdown” for Documentation — Eric Holscher](https://ericholscher.com/blog/2016/mar/15/dont-use-markdown-for-technical-docs/)
- GFM 變成主流 ? [GitHub Flavored Markdown](https://github.github.com/gfm/) 📈
- 支持 markdown 派的
[Markdown vs reStructuredText for teaching materials - GASERI](https://gaseri.org/en/blog/2021-08-16-markdown-vs-restructuredtext-for-teaching-materials/#markdown-as-the-obvious-choice-elsewhere)

### Frameworks
- Build Tools
- SSG (Static Site Generator)
- JekyII
- Hugo
- [MkDocs](https://www.mkdocs.org/) (Stripe) npm, react, python
- [Material for MkDocs](https://squidfunk.github.io/mkdocs-material/)
- MDX, [MDX](https://mdxjs.com/) 功能強大
- [Docusaurus](https://docusaurus.io/)
- notion 的話: [Notaku](https://notaku.so/)
- [PyMdown Documentation](https://facelessuser.github.io/PyMdown/)
- [Markdoc | A powerful, flexible, Markdown-based authoring framework](https://markdoc.dev/) Stripe 開發

TypeScript, RxJS and SASS,
- Author Tools
- 很多

## Asciidoc (adoc)

[AsciiDoc](https://asciidoc.org/)

### 優點

- single standard
- github 用 asciidoctor in safe mode to render files with the extension .doc, .ad, .asciidoc
- GBIF 用，有現成的參考
- [GBIF Asciidoctor](https://github.com/gbif/gbif-asciidoctor-toolkit)
- DwC terms
- break-all 隨意斷行 (方便 顯示 DNA sequence)
### 缺點

- 對一般人說語法還要熟悉
- 有一些工具可用，但是整合起來不是那麼方便

### Frameworks

- Build Tools
- docToolchain
- Asciidoctor, Ruby, to: HTML, PDF, EPUB3
- Antora
- Author Tools
- [AsciiDoc - Visual Studio Marketplace](https://marketplace.visualstudio.com/items?itemName=asciidoctor.asciidoctor-vscode)
- [EmacsWiki: Ascii Doc](https://www.emacswiki.org/emacs/AsciiDoc)

## reStructuredText (reST)
在Python 世界流通，用 docutils parser，來處理文件。
用 Sphinx 產生網頁 （markup language)

例子: Django, ReadTheDocs

### 優點

- 就用 Sphinx 不用傷腦筋
- 有 [Directives](https://docutils.sourceforge.io/docs/ref/rst/directives.html) 很方便

> "attention", "caution", "danger", "error", "hint", "important", "note", "tip", "warning"

### 缺點

- 只有 Sphinx 不好用不要用
- build tool 比較慢 (內容不多其實沒差)
- 語法有點醜的 (也不算缺點啦，風格問題)

### 綜合

### Frameworks

- Sphinx