はじめに
Markdown は手軽に文書を書くことができる言語である。しかし、目次やセクション番号、クロスリファレンス(例えば、詳細は Section 3.4.5参照。のような書き方)をしたいと思っても、Markdownの標準の記法ではサポートされておらず、Markdown拡張とPandocで頑張ればある程度はできるが、標準ではないので、VSCodeのプレビューやGitHubでのプレビューだと期待通り表示されない。
そこで、Markdownよりも表現能力の高いAsciiDocを使う。
asciidoc 自体の書き方は、参考文献を参照してもらうとして、作成に必要な次のことがらについて述べる。
-
AsciiDoctorのインストール。 -
VSCodeでプレビューする。 - PDFに変換する。
- Docker image で PDFに変換する。
作成する文章
以下の特徴を持つ sample.adoc 文章を対象とする。
- 表紙
- 目次
- セクション番号
-
mermaid記載したUMLを図として埋め込む -
PNG画像を埋め込む - 図番号
- クロスリファレンス
= サンプルドキュメント
:doctype: book # 表紙
:toc: # 目次
:toclevels: 5
:sectnums: # セクション番号
:author: Ken
:revdate: 2022/07/05
:revnumber: 1.0.0
:lang: ja
:imagesdir: images # 画像を置くフォルダ
:xrefstyle: short # クロスリファレンスの表記
== 最初のセクション
hello
**bold hello**
こんにちは
**太字のこんにちは**
== mermaid画像セクション
mermaidでUML図を書く。
[#img-mermaid]
.mermaid画像
[mermaid]
....
graph TD;
A-->B;
A-->C;
B-->D;
C-->D;
....
== PNG画像セクション
[#img-png]
.PNG画像
image::onepiece01_luffy.png[, 400]
== クロスリファレンスセクション
mermaid で記述した画像は、<<img-mermaid>> 参照。
PNG画像は、 <<img-png>> 参照。
フォルダ構造
.
├── images
│ └── notification_to_capp.md
└── sample.adoc
AsciiDoctorのインストール
AsciiDoctorをローカルPCにインストールする。
-
rubyのインストール
-
asciidoctorのインストール
gem install asciidoctor asciidoctor-diagram asciidoctor-pdf -
node のインストール
-
mermaidを画像に変換するツールであるmermaid-cliのインストール。npm install -g @mermaid-js/mermaid-cli
今回インストールしたバージョン
- asciidoctor (2.0.17)
- asciidoctor-diagram (2.2.3)
- asciidoctor-pdf (2.1.4)
- @mermaid-js/mermaid-cli (9.1.3)
mermaid-cli の 動作確認
インストール後、mermaid-cli（コマンド名 mmdc）が動作するか確認する。
test.mmd を作成する。
graph TD;
A-->B;
A-->C;
B-->D;
C-->D;
svgに変換する。
mmdc -i test.mmd -o test.svg
test.svgが次のように出力されることを確認する。
VSCodeでプレビュー
VSCodeのAsciiDoc拡張を使うと、プレビューしながら編集することができる。
インストール＆設定方法
- VSCode拡張 AsciiDoc をインストール。
-
VSCode拡張 AsciiDocの設定。
AsciiDoc中のmermaidで記載したUML図を プレビューに表示するために、VSCodeのsettings.jsonに次の設定をする。
"asciidoc.asciidoctor_command": "asciidoctor -r asciidoctor-diagram",
"asciidoc.use_asciidoctorpdf": true,
"asciidoc.use_asciidoctor_js": false,
PDFに変換
VSCodeプレビューでは、太字に設定した日本語が、期待通りに太字で表示されるが、
asciidoctor-pdfでPDF化すると、日本語が太字にならない。
太字のある日本語フォントを用意し、それを使うように設定をする。
フォントの取得
TrueType (TTF) or OpenType (OTF) が利用できる。
ここに、 利用可能なフォントリストがある。その中から、懐源ゴシックを利用する。リンク先から日本語フォント KaiGenGothicJP-*.ttf をダウンロードし、resources/fonts以下に置く。
テーマファイルの作成
ダウンロードしたフォントを利用するためにはテーマファイルを作成する必要がある。
テーマファイルはymlフォーマットで記述する。
resources/theme/basic-theme.yml を作成する。
extends: default-with-font-fallbacks # asciidoctor-pdfの標準テーマ "default-with-font-fallbacks-theme.yml" を継承する。
font:
catalog:
merge: true
# ダウンロードしたフォントをKaiGenGothicJPとして登録する。
KaiGenGothicJP:
normal: KaiGenGothicJP-Regular.ttf
bold: KaiGenGothicJP-Bold.ttf
italic: KaiGenGothicJP-Regular-Italic.ttf
bold_italic: KaiGenGothicJP-Bold-Italic.ttf
base:
font_family: KaiGenGothicJP # KaiGenGothicJPを基本フォントとして利用する。
asciidoctor-pdfの標準テーマファイル(default-with-font-fallbacks-theme.ymlなど)は、asciidoctor-pdf のインストールフォルダ下の data/themes にある。
フォルダ構造
この段階でのフォルダ構造は次のようになる。
.
├── images
│ └── notification_to_capp.md
├── resources
│ ├── fonts
│ │ ├── KaiGenGothicJP-Bold-Italic.ttf
│ │ ├── KaiGenGothicJP-Bold.ttf
│ │ ├── KaiGenGothicJP-Regular-Italic.ttf
│ │ └── KaiGenGothicJP-Regular.ttf
│ └── themes
│ └── basic-theme.yml
└── sample.adoc
PDFに変換
asciidoctor-pdfコマンドでPDFに変換する。
asciidoctor-pdf \
-a scripts=cjk \
-a pdf-theme=resources/themes/basic-theme.yml \
-a pdf-fontsdir=resources/fonts \
-r asciidoctor-diagram \
sample.adoc
このコマンドで、 sample.pdf が作成sれる。
docker image で、PDF化
誰でも簡単にPDF化できるように、docker imageを用意する。
TODO
さいごに
利用したファイル、及び、作成したPDFは、以下においておく。