はじめに

Markdown は手軽に文書を書くことができる言語である。しかし、目次やセクション番号、クロスリファレンス(例えば、詳細は Section 3.4.5参照。のような書き方)をしたいと思っても、Markdownの標準の記法ではサポートされておらず、Markdown拡張とPandocで頑張ればある程度はできるが、標準ではないので、VSCodeのプレビューやGitHubでのプレビューだと期待通り表示されない。
そこで、Markdownよりも表現能力の高いAsciiDocを使う。

asciidoc 自体の書き方は、参考文献を参照してもらうとして、作成に必要な次のことがらについて述べる。

AsciiDoctorのインストール。
VSCodeでプレビューする。
PDFに変換する。
Docker image で PDFに変換する。

作成する文章

以下の特徴を持つ sample.adoc 文章を対象とする。

表紙
目次
セクション番号
mermaid記載したUMLを図として埋め込む
PNG画像を埋め込む
図番号
クロスリファレンス

sample.adoc

= サンプルドキュメント
: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 を作成する。

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 に次の設定をする。

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 を作成する。

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は、以下においておく。

参考文献