Zenn
🐕

AsciiDocの良さを知る

に公開
HTML
Markdown
AsciiDoc
tech

AsciiDocというのを聞いたことはあるか？

AsciiDocとは、軽量マークアップ言語のひとつである。例を挙げるならMarkdownがそのうちのひとつである。Markdownは、シンプルで読み書きが容易であるため、多くの人に利用されている。そのため、AsciiDocの影は薄い。しかし、AsciiDocにはMarkdownにはない機能があり、それが非常に便利であるので紹介する。

AsciiDocとは

繰り返しになるが、AsciiDocは軽量マークアップ言語のひとつであり、2002年に開発された。構想としては、「平文、つまり対人可読なファイルを通常の出版に用いられる形式に変換」ということから始まり、現在ではPython, Ruby, JavaScriptでの翻訳機が存在する。

他の軽量マークアップ言語との違い

Markdown

2004年に開発された言語であり、現在はGitHubなどで広く利用されている。

# Markdown

This is a paragraph.

- List item 1
- List item 2

reStructuredText

2002年に開発された言語であり、Pythonのドキュメントに利用されている。特にSphinxというツールで利用されており、技術ドキュメントを書くのに適している。

===============
reStructuredText
===============

これは段落です。

- リストアイテム 1
- リストアイテム 2

.. note::

   これはノートです。

**強調**

*斜体*

.. code-block:: python

   def hello_world():
       print("Hello, world!")

AsciiDocの特徴

実際に使った感想として、AsciiDocはMarkdownで表現できることがほぼすべてでき、さらにそれ以外の機能が多くある。
詳しくは、AsciiDocの公式サイトを参照してほしいが、以下にいくつかの機能を紹介する。

機能 コード例 説明
アンダーライン [.underline]#アンダーライン# アンダーラインを引く
上付き文字 ^上付き文字^ 上付き文字を表示
下付き文字 ~下付き文字~ 下付き文字を表示
他のファイルをインクルード include::path/to/file.c[] 他のファイルをインクルードする
キーボード入力 kbd:[Ctrl+T] キーボード入力を表示する

そのほかにも、表が楽に書ける、参考文献を書ける、脚注を書ける、などの機能がある。

AsciiDocの利用例

、、、ここまで読んだら、こう思うはず。

とても便利なのでは！！

ということで、実際にAsciiDocが使えるツールについて紹介する。

また、AsciiDocで書いたファイルはいろんな形式に変換することができる。HTMLやPDF、EPUB、DOCXなどに変換することができる。

まとめ

AsciiDocは、Markdownに比べて多くの機能があるため、技術ドキュメントを書くのに適している。また、AsciiDocで書いたファイルはHTMLに変換することができるため、Webページとして公開することも可能である。ぜひ、AsciiDocを使ってみてほしい。

GitHubで編集を提案

Discussion