AsciiDocで書く
ソースコードを含んだ文書を書く必要が会ったので、AsciiDocを導入しました。
MacへのAsciiDocの導入
AsciiDocの処理系としておAsciiDoctorを使用します。
ランタイムにRubyを使用するので、Rubyのインストールから行っています。 前提として、 asdf で言語のバージョン管理を行っています。
AsciiDocのサンプル
似たようなマークアップ言語にMarkdownがありますが、 以下のような点でAsciiDocが優れているので作る文書の特性で 使い分けています。
目次や表紙の生成が可能
細かいテーブルの表現が可能
ソースコードにシンタックスハイライトや吹き出しが使える
始めからHTMLやPDFへの変換を意識して作られているのも大きいですね。
いかがサンプルです。
= サンプル :toc: left :toc-title: 目次 :toclevel: 4 :imagesdir: images :figure-caption: 図 :chapter-signifier: :scripts: cjk :pdf-theme: default-with-font-fallbacks :doctype: book :sectnumlevels: 4 :sectnums: :source-highlighter: rouge :rouge-style: gruvbox == Hello World .hello.py [source,python] ---- print("Hello World!") <1> i = 3 if i == 1: <2> print("i = 1") elif i == 2: print("i = 2") elif i == 3: print("i = 3") else: print("i = 4") ---- <1> やっぱりサンプルといえばコレな <2> IF文です！
AsciiDocを変換する
作成したAsciiDocのソースは以下のコマンドでHTMLやPDFに変換します。
$ # HTMLの生成 $ asciidoctor --backend html5 sample.adoc -o sample.html $ # PDFの生成 $ asciidoctor-pdf sample.adoc -o sample.pdf
以下が生成したサンプルです。
AsciiDoc生成結果
まとめ
AsciiDocは Markdownと似ているので混乱する部分もありますが、 Markdownよりやりたいことをストレートに書けると思います。
サンプルのようにAsciiDocのメタデータにいろいろ記載すると生成するスタイルも 変更できるのでいろんな文章に柔軟に対応できると思います。