AsciiDoc文書作成入門
Asciidocによる文書作成環境の構築

農林水産技術会議事務局 筑波産学連携支援センター
Ver. 1.2, 2022-05-25

目次
1. はじめに . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1
2. AsciiDocとは . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1
2.1. AsciiDocでできること . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1
3. AsciiDoc文書作成環境構築 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2
3.1. Asciidoctorインストール . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2
3.1.1. Windowsでのインストール . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3
3.1.1.1. asciidoctor-pdfインストール . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4
4. AsciiDocの基本操作 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7
4.1. asciidoctor (HTML5出力) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7
4.2. asciidoctor-pdf (PDF出力) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8
4.2.1. アトリビュートオプション . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9
5. VSCodeを使った文書作成環境 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11
5.1. VSCodeのダウンロードとインストール . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11
5.1.1. 拡張機能 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12
5.1.2. AsciiDoc 拡張機能の設定. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14
5.1.3. ターミナルの規定のシェル設定 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15
5.2. AsciiDoc文書作成 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16
5.2.1. 文書の入力 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16
5.2.2. PDFファイルへのエクスポート. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17
5.2.2.1. ターミナルからのコマンド . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18
5.3. Gitの操作 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18
5.3.1. リポジトリを開く . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19
5.3.2. ファイルの編集 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19
5.3.3. ステージング(git add) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19
5.3.4. コミット(git commit). . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20
5.3.5. ログ(git log) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20
5.3.6. プシュ & プル. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21
6. AsciiDoc文書の記述方法 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23
6.1. 文書タイトル . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23
6.2. アトリビュート . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 24
6.3. 箇条書き . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 25
6.4. 表 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 26
6.5. 画像表示 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 27
6.6. 参考情報(リンク). . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 28
6.7. PDF出力イメージ(example-02.pdf) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 28
7. 実際の文書事例 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 29

7.1. 議事録 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 29
7.1.1. 議事録AsciiDoc文書 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 30
7.1.2. 議事録AsciiDoc文書の構成 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 31
8. 日本語フォントの利用 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 33
8.1. 日本語フォントの導入 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 33
8.1.1. MigMix (ミグミックス)フォント . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 33
8.2. フォントの配置 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 34
8.3. themeファイル作成(フォント設定) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 34
8.4. アトリビュートの指定 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 35
8.5. フォントを変更した出力例 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 35
8.5.1. フォールバックフォントにMigMix 1Pを指定 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 35
8.5.2. 基本フォントにMigMix 1Pを設定 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 36
8.5.3. 基本フォントに明朝系(ShipporiMinchoB1)を指定 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 37
8.5.4. 基本フォントにゴシック系(IBMPlexSansJP)を指定 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 38
8.5.5. サンプル文書 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 39
9. 長文(冊子)スタイルの文書作成. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 40
9.1. 冊子(book)スタイル . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 40
9.2. アトリビュートによる設定 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 42
9.3. themeファイルによる書式変更 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 45
9.3.1. サンプルテーマファイル(example-06-theme.yml). . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 45
9.3.2. アトリビュートの変更 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 50
9.3.2.1. 他のアトリビュート追加設定. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 50
9.3.2.2. サンプルで指定したアトリビュート. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 51
9.4. ファイルの分割 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 52
9.4.1. 文書作成 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 54
10. 仕様書作成等に向いたスタイル . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 55
10.1. 前項のスタイルファイル . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 55
10.2. スタイルファイル変更 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 56
10.2.1. 変更後の文書イメージ . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 59
10.2.2. 変更後のテーマファイル . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 61
10.2.3. 明朝系フォントに変更 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 62
11. テーマファイルのテンプレート化 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 65
11.1. サンプルファイルの内容 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 66
12. 作図ツール draw.io (VSCode拡張機能) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 75
12.1. draw.ioとは. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 75
12.2. 再編集可能な形式 *.drawio.png と *.drawio.svg . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 75
12.3. draw.ioの利用 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 76
13. その他. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 78
13.1. アップデート . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 78

13.2. 文章校正(検査)ツール textlint . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 78
13.2.1. textlintとは . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 78
13.2.2. VSCodeプラグイン . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 79
13.2.3. textlintに関する情報 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 80
付録 A: 参考情報 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 81

1. はじめに2.1. AsciiDocでできること

1. はじめにマニュアルや操作説明書など、改版を繰り返す文書や、共同で執筆する文書などは、バージョン管理システムにより、最新版や改版履歴の管理が必要です。 Wordなどで作成されることが多いと思いま
すが、バージョン管理システムとの親和性やテキストデータの流用性、検索性に優れた軽量マークア
ップ言語の AsciiDoc を紹介します。
ここで紹介する AsciiDoc は、PDF形式の出力を前提に、Asciidoctor, Asciidoctor-pdf について説明します。
この文書も、AsciiDocで記述し、Git(バージョン管理システム)で修正履歴を管理しています。

2. AsciiDocとはAsciiDocは、軽量マークアップ言語の一つです。 軽量マークアップ言語は、シンプルなテキストで文書構造を記述し、HTMLなどに変換して利用することができる言語で、 markdown, AsciiDoc,
ReStructuredText などがあります。 Wikiの記述構文も軽量マークアップ言語の一つと考えられます。
AsciiDocは、テキストエディタを使って容易に記述することができることから、プログラム開発での情報共有などに利用されていますが、HTML, PDF, ePubなどに変換することで、仕様書や報告書、マニュアルなど出版レベルの高度な文書構造の記述も可能です。

2.1. AsciiDocでできること
議事録、報告書(数ページ以内)
markdownと同様にテキストエディタでシンプルなテキストメモを作成し、見出しや箇条書きな
どの体裁を整えPlain Textのままメールで確認(Plain Textでも可読性が高い)、PDFなどに変換して提出する。
Wiki, HTMLドキュメント
GitHubのWikiなどでもAsciiDocがつかえます。また、AWSによるクラウド入門もAsciiDocで書
かれています(HTMLに変換)。
論文
図表などを含む論文形式の文書も作成できます。markdownよりも表などの表現や相互参照なども記述できます。
仕様書、要件定義書
数十ページに及ぶような文書も書くことができます。ファイルを分割しincludeすることも可能です。WordなどよりもGitでのバージョン管理に適しており、複数での共同執筆もできます。
技術文書、マニュアル
GitProなど、500ページを超えるマニュアルとその翻訳版、オライリーの電子書籍原稿にもAsciiDocが使われています。

1

AsciiDoc文書作成入門

3.1. Asciidoctorインストール

HTML文書、電子出版
HTML5, ePUB, DocBookなどのフォーマットに変換することで、電子出版やWebでの公開ができ
ます。
PDF文書
PDFファイルに変換することで、印刷物や納品物としての電子ファイル提供ができます。

図 1. AsciiDocテキストとプレビュー

3. AsciiDoc文書作成環境構築
ここでは、主に、Windowsでの環境構築について説明します。なお、WSL(Windows Subsystem
for Linux)でも環境構築ができます。 WSLインストールやLinux環境について詳しく説明をしませんが、WSLの方が処理速度も早いので、既にWSL環境がある方やLinuxに興味のある方は試してください。

3.1. Asciidoctorインストール
Asciidoctorは、AsciiDocで書かれた文書をHTML5, DocBook, PDFなどに変換するツールで、 Ruby
で書かれています。
Asciidoctorは、RubyGem (gem)パッケージとして配布されています。また、主要なLinuxディスト
リビューションやmacOS用のパッケージとしても配布されています。
Linuxのパッケージマネージャ
Linuxディストリビューションのパッケージマネージャで、asciidoctorをインストールすることができます。必要なRubyなどのパッケージもインストールされます。

2

3. AsciiDoc文書作成環境構築

3.1. Asciidoctorインストール

Ubuntu, Debiansudo apt install asciidoctor
WSL環境のUbuntuでも同じ
Fedora, CentOS, RHEL
sudo dnf install asciidoctor
macOS(Homebrew)
macOSでは、Homebrewを使用してAsciidoctorをインストールすることができます。
Homebrew
brew install asciidoctor

3.1.1. Windowsでのインストール
AsiiDoc(asciidoctor)を利用するには、Rubyの環境が必要です。
Rubyのインストール
Rubyinstaller
RubyInstaller for Windows (https://rubyinstaller.org/downloads/) から、使っているPC環
境に合ったインストーラーをダウンロードします。
お勧めは、 [we recommend that you use the Ruby+Devkit 2.7.X (x64) installer] となっています。
• ダンロードしたインストーラを実行(ダブルクリック)してインストールを開始します。
◦ ライセンスに同意して、インストールを進めます。(基本的に標準設定のまま進める)◦ インストールが終了し「Finish」ボタンをクリックすると、「MSYS2」のインストー
ル画面が開きます。

図 2. Rubyインストール終了

3

AsciiDoc文書作成入門

3.1. Asciidoctorインストール

図 3. MSYS2インストール◦ 上の画面で、[1,3]または、[1,2,3]と入力し、[Enter]キーを押します。

図 4. MSYS2インストール終了◦ 上の画面で、[Enter]キーを押して終了します。
3.1.1.1. asciidoctor-pdfインストール• Rubyのコマンドプロンプトを起動します。
◦ Windowsメニューから「Ruby 2.x.x-x64 with MSYS2」の「Start Command Prompt withRuby」を起動します。

図 5. Start Command Prompt with Ruby

4

3. AsciiDoc文書作成環境構築

3.1. Asciidoctorインストール◦ コマンドプロンプトから、以下のコマンドによりasciidoctorをインストールします。
ruby 2.7.2p137 (2020-10-01 revision 5445e04352) [x64-mingw32]
C:\Users\koshihikari> gem install asciidoctor①............................................................. ②
Successfully installed asciidoctor-2.0.12
Parsing documentation for asciidoctor-2.0.12
Done installing documentation for asciidoctor after 2 seconds
1 gem installed
C:\Users\koshihikari> gem install asciidoctor-pdf --pre③.............................................................
Successfully installed asciidoctor-pdf-1.5.4
Parsing documentation for asciidoctor-pdf-1.5.4
Done installing documentation for asciidoctor-pdf after 1 seconds
1 gem installed① gem install asciidoctor コマンドで asciidoctor をインストールします。
② インストール時のメッセージが大量に表示③ gem install asciidoctor-pdf --pre asciidoctor-pdf をインストールします。 --preは、先行リリース版(最新)をインストールするオプション。



Rubyのコマンドプロンプトを使って説明しましたが、RubyのPATHが設定されていれば、PowerShellやGitBashからでも実行可能です。

asciidoctor-pdfインストール(Windows以外)
LinuxやmacOSでも、gemコマンドでasciidoctor-pdfをインストールします。

$ gem install asciidoctor-pdf --pre①
Fetching asciidoctor-pdf-1.5.4.gem
ERROR: While executing gem ... (Gem::FilePermissionError)
You don't have write permissions for the /var/lib/gems/2.7.0 directory.
$ sudo gem install asciidoctor-pdf②[sudo] password for koshihikari:
Successfully installed asciidoctor-pdf-1.5.4
Parsing documentation for asciidoctor-pdf-1.5.4
Done installing documentation for asciidoctor-pdf after 0 seconds
1 gem installed① Linuxなど、Rubyのインストール環境によっては、管理者権限が必要な場合があります。
② sudo コマンドを使って、管理者権限で gem install を実行

macOSで、gem install を実行した際に、permissionエラーとなる場合があります。

% gem install asciidoctor

5AsciiDoc文書作成入門

3.1. Asciidoctorインストール

Fetching asciidoctor-2.0.12.gem
ERROR: While executing gem ... (Gem::FilePermissionError)
You don't have write permissions for the /Library/Ruby/Gems/2.6.0
directory.

システム標準のrubyを使用した場合、インストールできません。
この場合、rbenvを使ってRubyの管理を行い、ユーザ環境のrubyを使うようにします。 rbenvを使うことで、標準のruby 2.6.3よりも新しい、ruby 2.7.2などを使うことができます。

6

4. AsciiDocの基本操作

4.1. asciidoctor (HTML5出力)

4. AsciiDocの基本操作
asciidoctor, asciidoctor-pdf のインストールが完了すれば、AsciiDocで記述したテキストをHTMLやPDFに変換することができます。
メモ帳などで、AsciiDocテキストを作成(example-01.adoc)します。
= AsciiDocの使い方
この文書は、AsciiDocの使い方・・・・・== AsciiDocとは(見出し1)
AsciiDocは、*軽量マークアップ言語* の一つ・・・・・
テキストを作成する際は、見やすいように、適宜、改行しながら文書を作成します。
HTML等に変換すると、改行は無視されますので、段落を区切るには、1行以上、行を空けます。 +また、行末に `' +'` (スペースと `{plus}`)を入れると、改行されます。
https://asciidoctor.org/[Asciidoctor] リンク• AsciiDocテキストファイルを作成し、拡張子 .adoc を付けて保存

4.1. asciidoctor (HTML5出力)
PowerShellなどコマンド操作のできる環境を開き、asciidoctorを実行します。
> cd example①> asciidoctor example-01.adoc ②> dir
ディレクトリ: C:\Users\koshihikari\example
Mode
LastWriteTime Length Name---------------- ------ ----a---2021/03/12
14:30
570 example-01.adoc-a---2021/03/12
15:40
31948 example-01.html ③① 作成したAsciiDocテキストファイルを保存したフォルダに移動② asciidoctor コマンドを実行③ HTML5 に変換されたファイル(example-01.html)が作成される作成された html ファイルをブラウザで開くと、以下のように整形されます。

7

AsciiDoc文書作成入門

4.2. asciidoctor-pdf (PDF出力)

図 6. 生成されたHTMLドキュメントをプレビュー

4.2. asciidoctor-pdf (PDF出力)
PDFを生成するには、asciidoctor-pdf コマンドを使います。
> asciidoctor-pdf example-01.adoc①① asciidoctor-pdf コマンドを使います。
• 日本語の場合、PDFファイルが文字化けします。

図 7. 生成されたPDFドキュメント

日本語の場合、アトリビュートを指定するオプションが必要です。

8

4. AsciiDocの基本操作

4.2. asciidoctor-pdf (PDF出力)> asciidoctor-pdf -a pdf-theme=default-with-font-fallbacks -a scripts=cjk example-01.adoc-a pdf-theme=default-with-font-fallbacks
デフォルトのフォントには、日本語が含まれていないため、fallbak fontを追加した拡張テーマを指定します。
-a scripts=cjk
日本語と英語が混在した文書で、ワードラップ(改行位置)を修正するオプションです。
生成したPDFは、以下のようになります。

図 8. 生成されたPDFドキュメント

4.2.1. アトリビュートオプション
asciidoctor-pdfで指定したアトリビュートオプションについては、 AsciiDocテキストファイルに記述することが可能です。

= AsciiDocの使い方:scripts: cjk:pdf-theme: default-with-font-fallbacks①②

この文書は、AsciiDocの使い方・・・・・== AsciiDocとは(見出し1)
AsciiDocは、*軽量マークアップ言語* の一つ・・・・・
テキストを作成する際は、見やすいように、適宜、改行しながら文書を作成します。

① ワードラップ修正オプション② 日本語を含むフォント拡張テーマ

9AsciiDoc文書作成入門

4.2. asciidoctor-pdf (PDF出力)

AsciiDocテキストにアトリビュートオプションを入れると、毎回コマンドオプションを指定する必
要はありません。

> asciidoctor-pdf example-01.adoc①① アトリビュートオプションなしでも、文字化けしません。

10

5. VSCodeを使った文書作成環境

5.1. VSCodeのダウンロードとインストール

5. VSCodeを使った文書作成環境
Visual Studio Code (VSCode)は、マイクロソフトが無料で公開している軽量なコードエディタで、拡張機能を使用してAsciiDocの編集やプレビュー、ターミナル機能を利用したコマンドの実行など、AsciiDoc文書作成環境として利用することができます。
VSCodeは、Windows, macOS, Linuxなどに対応しており、どのOSでも同様の使い方が可能です。
また、プログラム開発だけではなく、拡張機能によりmarkdownやasciidoc,LaTeXなど文書作成環
境としても利用できます。

図 9. VSCodeによるAsciiDocプレビュー

5.1. VSCodeのダウンロードとインストール• Visual Studio Code 公式サイト ( https://code.visualstudio.com )図 10. VSCodeの公式サイト

11

AsciiDoc文書作成入門

5.1. VSCodeのダウンロードとインストール• 公式サイトから自分のPC環境に合ったインストーラーをダウンロードします。
◦ Windows 10であれば、User Installer 64 bit (Intel 64環境の場合)をダウンロードします。
(自分だけで使うのであればSystem Installerは不要)◦ macOSの場合、IntelかApple Siliconかを選択します。
◦ Linuxの場合は、OSのパッケージ管理ツールでインストール可能です。また、Snap版で最新版を利用できます。
• 一般ユーザ権限で、インストーラを実行してインストールします。(Windows)

5.1.1. 拡張機能
VSCodeは、拡張機能を追加することで、使い勝手が良くなります。 お勧めの拡張機能を紹介します。
• Japanese Language Pack for VS Code
◦ VSCodeのメニューや操作画面を日本語化します。

図 11. Japanese Language Pack for VS Codei. 拡張機能のメニューを表示
ii. japanese を検索
iii. Japanese Language Pack for VS Codeをインストール• AsciiDoc◦ AsciiDocの書式を見やすく表示(シンタックスハイライト)します。
◦ AsciiDocをプレビュー(HTMLと同様に表示)し、出力イメージを見ながら編集ができます。
◦ 拡張機能の設定により、AsciiDoc形式からPDFファイルを出力することができます。

12

5. VSCodeを使った文書作成環境

5.1. VSCodeのダウンロードとインストール

図 12. AsciiDoc

i. asciidoc を検索
ii. AsciiDoc をインストール
iii. 拡張機能の設定により、PDF出力などが可能• vscode-pdf◦ PDFファイルを表示します。

図 13. vscode-pdf

i. ext:pdf を検索
ii. vscode-pdfをインストール• Git Graph (Gitがインストールされている場合)◦ Gitログを見やすく表示します。
◦ ログの詳細や、変更されたファイルの表示、差分表示などをマウス操作で行うことができます。

13

AsciiDoc文書作成入門

5.1. VSCodeのダウンロードとインストール

図 14. Git Graphi. git を検索
ii. Git Graphをインストール

5.1.2. AsciiDoc 拡張機能の設定
AsciiDoc拡張機能の設定を行うことで、VSCodeの「コマンドパレット」機能を使ってPDFファイル
へのエクスポートを行うことができます。 asciidoctor, asciidoctor-pdfがインストールされていることが前提です。 (Wkhtmltopdfを使ってasciidoctor-pdf無しでもPDF出力することはできます
が、HTMLをPDFに変換するため、出力イメージが異なります。)• 拡張機能アイコンをクリックし、拡張機能一覧から「AsciiDoc」の  歯車アイコンをクリック
し、「拡張機能の設定」を選択します。

図 15. 拡張機能の設定• 拡張機能(26) asciidoc(26) の設定をスクロールし、下方にある次の項目の設定を変更します。

14

5. VSCodeを使った文書作成環境

5.1. VSCodeのダウンロードとインストール

図 16. 拡張機能の設定

Asciidoc: Use_asciidoctor_js☐ Use asciidoctor js instead of the 'asciidoctor_command'▪ チェックを外す JavaScript版のasciidoctorを使わない。(PCにインストールしたasciidoctor(Ruby版)を使う)
Asciidoc: Use_asciidoctorpdf☑ Use asciidoctor-pdf instead of the integreted renderer▪ チェックを入れる PCにインストールしたasciidoctor-pdf(Ruby版)を使う。
Asciidoc: Use Workspace Root
☑ When in a workspace, use the workspace root path as the base dir.
▪ チェックを入れる ワークスペースのrootパスをベースディレクトリとする。

5.1.3. ターミナルの規定のシェル設定
Git Bashがインストールされていれば、ターミナルを開いてコマンドでの操作ができます。 Gitがインストールされていない場合は、Command Promptを規定のシェルに設定します。
asciidoctor-pdfのオプション指定などを行う場合、ターミナルから実行します。
• ターミナルの規定のシェルを設定します。
◦ 上部の「ターミナル」メニューから「新しいターミナル」を開きます。
◦ ターミナルのプルダウンメニューから「規定のシェル設定」を開きます。

図 17. ターミナルのプルダウンメニュー◦ 優先するターミナルシェルの選択から「Git Bash」または「Command Prompt」を選択し

15

AsciiDoc文書作成入門

5.2. AsciiDoc文書作成ます。

図 18. 優先するターミナルシェルを選択します。

5.2. AsciiDoc文書作成
VSCodeを起動し、「ファイル」メニューから、「フォルダーを開く」(macOSの場合「開く」)を選択して、AsciiDoc文書を作成するフォルダーを開きます。

5.2.1. 文書の入力• 「新規ファイル」や既存のAsciiDocファイル(拡張子.adocなど)を開いて文書を入力します。

= AsciiDocの使い方
この文書は、AsciiDocの使い方・・・・・== AsciiDocとは(見出し1)
AsciiDocは、*軽量マークアップ言語* の一つ・・・・・
テキストを作成する際は、見やすいように、適宜、改行しながら文書を作成します。
HTML等に変換すると、改行は無視されますので、段落を区切るには、1行以上、行を空けます。 +また、行末に `' +'` (スペースと `{plus}`)を入れると、改行されます。
https://asciidoctor.org/[Asciidoctor] リンク•

右上のプレビューアイコン(Open Preview to the Side
(Ctrl+K V))をクリックすれば、プレビューが表示されます。

16

5. VSCodeを使った文書作成環境

5.2. AsciiDoc文書作成

図 19. 編集、プレビュー画面◦ プレビューは、文書の入力とほぼ同時に再表示されますので、プレビューイメージを見ながら文書を編集することができます。

5.2.2. PDFファイルへのエクスポート
拡張機能の設定により、コマンドパレット機能を使ってPDFファイルへの出力が可能です。
• VSCodeのエクスプローラー(左側のファイルリスト)から、PDFに出力するAdciiDocファイル(example-01-1.adoc)を選択しておきます。

= AsciiDocの使い方:scripts: cjk:pdf-theme: default-with-font-fallbacks①②

この文書は、AsciiDocの使い方・・・・・== AsciiDocとは(見出し1)
AsciiDocは、*軽量マークアップ言語* の一つ・・・・・
テキストを作成する際は、見やすいように、適宜、改行しながら文書を作成します。

① ワードラップ修正オプション② 日本語を含むフォント拡張テーマ◦ コマンドパレットでは、オプション指定ができませんので、日本語に関する属性オプショ
ンをAsciiDocファイルに記述しておく必要があります。
• 「表示」メニューから、「コマンドパレット」を選択します。

17

AsciiDoc文書作成入門

5.3. Gitの操作

図 20. コマンドパレットメニュー• 「AsciiDoc Export document as PDF」を実行します。

図 21. PDFエクスポート実行• ファイルの保存場所などを指定し、エクスポートを実行すると、右下にメッセージが表示されます。
◦ 「Open File」をクリックすれば、PDF表示ソフトに表示されます。
◦ Successfully以外のメッセージが表示される場合は、拡張機能の設定やasciidoctor-pdfのイ
ンストール、出力元のファイルに問題があると考えられます。
5.2.2.1. ターミナルからのコマンド
コマンドパレットからPDF出力を実行することはできますが、コマンドオプションを指定する場合など、ターミナルからのコマンド実行も必要となります。
• 「表示」メニューから、「ターミナル」を開く、または、「ターミナル」メニューから「新しいターミナル」を開くと、右下にターミナルが開きます。

図 22. ターミナル(Command Prompt)◦ コマンドプションを指定して、asciidoctor-pdfを実行

5.3. Gitの操作
Gitがインストールされている場合は、バージョン管理を行うことができます。

18

5. VSCodeを使った文書作成環境

5.3. Gitの操作

AsciiDocは、テキストファイルなので、プログラムソースコードのようにバージョン管理システム
を使うことで、変更箇所の差分を見やすく表示したり、共同で文書を作成することが容易になります。

5.3.1. リポジトリを開く

図 23. フォルダーを開く• 「ファイル」メニューから「フォルダーを開く」でリポジトリを開く(Macの場合「開く…」)

5.3.2. ファイルの編集
1. 新規ファイルや既存ファイルの編集を行います。
2. ファイルリストには、ファイル名の右側に M, Uなどが表示されます。
◦ M: Modified 変更のあったファイル◦ U: UnTracked 追跡されていない(Gitの管理下にない)ファイル

5.3.3. ステージング(git add)

図 24. ステージング

1. Gitの機能を選択
2. 変更済みファイル

M:変更 U:未追跡ファイル

ファイルを選択して、ファイル名右の  をクリックすると、ステージングエリアに追加され

19

AsciiDoc文書作成入門

5.3. Gitの操作る。
3. 変更されたファイルの差分(diff)が表示される。
4. ステージングエリアのファイル

5.3.4. コミット(git commit)

図 25. コミット

1. ステージングエリアのファイル名右の  をクリックすると、ステージング解除となる。
2. コミットメッセージを入力します。
3.  チェックをクリックすると、コミットを実行する。

5.3.5. ログ(git log)

図 26. ログ

• ログ表示(Git Graphアイコン)をクリックして、git logを表示します。
• 任意のログをクリックすると詳細が表示され、変更されたファイルの差分などもマウス操作で見ることができます。

20

5. VSCodeを使った文書作成環境

5.3. Gitの操作

図 27. ログ詳細

図 28. 差分表示

5.3.6. プシュ & プル
VSCodeのメニューにも「プッシュ」や「プル」がありますが、ssh認証に失敗するなど不具合があるため、ターミナルからコマンドにより操作します。 (ssh-agentなどを利用してVSCodeから操作する方法もありますが、SSHの設定やssh-agentなどが必要となることから、コマンドによる操作のほうが容易)
リスト 1. プッシュに失敗した際のメッセージ> git push origin master:master
Permission denied, please try again.
Permission denied, please try again.
git@gitlab.example.com: Permission denied (publickey,gssapi-keyex,gssapi-with-mic,password).
fatal: Could not read from remote repository.
Please make sure you have the correct access rights
and the repository exists.

リスト 2. ターミナルからgit logコマンドを実行$ git log
commit bedd7c3628d7317c2bd3cfa1f2d6eadde26d243b (HEAD -> master)
Author: Hikari KOSHINO <koshihikari@example.com>
Date: Wed Mar 3 20:01:05 2021 +0900
2021-03-03 Vimの使い方を追加した。
commit 927207f43755f641fcbb68f39bdd1bdface53d27 (origin/master, origin/HEAD)

21

AsciiDoc文書作成入門

5.3. Gitの操作

Author: Hikari KOSHINO <koshihikari@example.com>
Date: Wed Mar 3 18:11:20 2021 +0900
2021-03-03 PDFに改ページとコマンドラインを入れてみた。

リスト 3. ターミナルからgit pushコマンドを実行$ git pushEnter passphrase for key '/Users/koshihikari/.ssh/id_ed25519':
Enumerating objects: 12, done.
Counting objects: 100% (12/12), done.
Delta compression using up to 8 threads
Compressing objects: 100% (7/7), done.
Writing objects: 100% (7/7), 85.17 KiB | 3.41 MiB/s, done.
Total 7 (delta 4), reused 0 (delta 0)
To gitlab.example.com:koshihikari/gitlab-start.git
927207f..bedd7c3 master -> master22

6.1. 文書タイトル

6. AsciiDoc文書の記述方法

6. AsciiDoc文書の記述方法
6.1. 文書タイトル• この例では、以下の構成を示しています。
◦ 文書タイトル, 著者, バージョン◦ 文書属性(アトリビュート)指定◦ 本文◦ 項目見出し1◦ 本文, 強調文字, 段落, 改行◦ リンク◦ コメント• AsciiDocのテキスト
リスト 4. example-02.adoc= AsciiDocの使い方
著者 Hikari KOSHINO <koshihikari@example.com>
Ver.1.0, 2021-03-12:scripts: cjk:pdf-theme: default-with-font-fallbacks:sectnums:
この文書は、AsciiDocの使い方・・・・・== AsciiDocとは(見出し1)
AsciiDocは、*軽量マークアップ言語* の一つ・・・・・
テキストを作成する際は、見やすいように、適宜、改行しながら文書を作成します。
HTML等に変換すると、改行は無視されますので、段落を区切るには、1行以上、行を空けます。 +また、行末に `' +'` (スペースと `{plus}`)を入れると、改行されます。
https://asciidoctor.org/[Asciidoctor] リンク
行頭に `//` を書くとコメントとなります。
// コメント行は、HTMLなどに変換すると無視されます。

23

6.2. アトリビュート

AsciiDoc文書作成入門

図 29. プレビューで表示したイメージ

6.2. アトリビュート• example-02.adoc の文書属性(アトリビュート)説明と、ソースコードやプレーンテキストの書き方の例を示します。
リスト 5. example-02.adoc=== アトリビュート(文書属性指定)[source, plain].アトリビュート
---:scripts: cjk①:pdf-theme: default-with-font-fallbacks ②:sectnums:③---<1> 日本語のワードラップ(改行位置)を修正<2> PDF用標準フォントに含まれない日本語を表示する拡張テーマ<3> 項番をつけるオプション• 参照コメントを入れたい行末に、 // <1> のように番号を入れておき、ソースコードの後に、番号とコメントを書き込むことができます。
• ぞれぞれの属性については、コメントの通りです。

24

6.3. 箇条書き

6. AsciiDoc文書の記述方法

図 30. プレビューで表示したイメージ

6.3. 箇条書き• 箇条書きは、自動で番号が付与されるものと番号なしの書き方があります。
リスト 6. example-02.adoc=== 箇条書きの例(見出し2). AsciiDocを使うには.. Rubyインストール... asciidoctor... asciidoctor-pdf. 他にもなにか・・・// リストとリストを分割するには、コメント行を入れます。
* あると便利** VSCode (エディタ)*** AsciiDocの拡張機能*** プレビューもできる* Windows, Linux, Macでも同じ環境==== チェックリスト(見出し3).ToDo りすと
- [*] チェックリスト- [x] これもチェック済み- [ ] チェックなし

25

6.4. 表AsciiDoc文書作成入門

図 31. プレビューで表示したイメージ

6.4. 表• 表も作れます。
リスト 7. example-02.adoc=== 表も作れます[cols="<3,^2", options="header", width="60%"]
.表題
|====
|テキスト
| 表示
|`\*強調*`| *強調*|`\{plus}`| {plus}|`\#マーカー#`| #マーカー#|`[.underline]\#アンダーライン#` | [.underline]#アンダーライン#
|====

26

6.5. 画像表示

6. AsciiDoc文書の記述方法

図 32. プレビューで表示したイメージ

6.5. 画像表示• 画像ファイルを読み込んで表示します。
リスト 8. example-02.adoc=== 画像の表示
トケイソウ image:example-image-02.png[width=120] インライン表示.富士山
image::example-image-01.png[scaledwidth="50%", align="center"]

図 33. プレビューで表示したイメージ

27

6.6. 参考情報(リンク)AsciiDoc文書作成入門

6.6. 参考情報(リンク)リスト 9. example-02.adoc== 参考情報
https://takumon.github.io/asciidoc-syntax-quick-reference-japanese-translation/[Asciidoctor
文法クイックリファレンス(日本語訳)]
https://www.seinan-gu.ac.jp/~shito/asciidoctor/html_chunk/[Asciidoctor User Manual]

図 34. プレビューで表示したイメージ

6.7. PDF出力イメージ(example-02.pdf)

28

7. 実際の文書事例

7.1. 議事録

7. 実際の文書事例
7.1. 議事録
議事録の事例を紹介します。

図 35. 議事録のサンプルPDFイメージ

29

7.1. 議事録

AsciiDoc文書作成入門

7.1.1. 議事録AsciiDoc文書
リスト 10. 議事録AsciiDoc文書(example-03.adoc)// example-03.adoc 議事録サンプル:doctype: article:scripts: cjk:pdf-theme: default-with-font-fallbacks[cols="<,>",frame="none",grid="none"]|====| 取り扱い注意 | 社内限り +文書番号: 210035 +{docdate}|===='''=== 第3回 プロジェクト会議議事録[cols="1,8",frame="topbot",grid="none"]|====| 日時 | 令和3年3月25日 15:00-15:45| 場所 | 第6会議室| 出席者 | チームリーダー、スタッフ2名、開発室長、開発室3名|======== 議事内容[qanda]
提案概要説明::資料を配布し、提案概要を開発室から説明
チームリーダー質疑::
提案Aについて:::文書の間違いが、多くなっているが・・・・・。
開発室:::
Gitを使って、バージョン管理を行います。diffを使って差分をを確認しながら、作成することが可能です。
提案Bについて:::Ward文書は、差分の表示ができるのか、・・・・・・・・・・・・・・。
開発室:::
Word文書でも差分表示可能なツールはありますが、マージができませんので、AsciiDocを使って作成します。 +AsciiDocであれば、プログラムソースコードと同様にテキストデータですので、Gitでのバージョン管理、差分表示やマージを行うことが可能です。
参考意見::
このように、・・・・・・・・・してはどうか？
[.text-right]
以上30

7. 実際の文書事例

7.1. 議事録

7.1.2. 議事録AsciiDoc文書の構成
1. アトリビュート
日本語の文書に必要なアトリビュート(文書属性)を指定(可能な限りデフォルトを使う):doctype: article:scripts: cjk:pdf-theme: default-with-font-fallbacks①②③① 議事録など数ページの文書は、 :doctype: article を指定します。
② :scripts: cjk は、日本語の改行位置を修正する。
③ 標準フォントに日本語が含まれていないため、:pdf-theme: default-with-font-fallbacks を指定します。
2. 文書番号等
日付や文書番号などを枠線なしの「表」を使って表現[cols="<,>",frame="none",grid="none"]|====| 取り扱い注意 | 社内限り +文書番号: 210035 +{docdate}
|====
③
'''

①

②

① cols="<,>" 2列の表で、左寄せ(<)と右寄せ(>)を指定
frame="none" 外枠(frame)なし
grid="none" 表の罫線(grid)なし② {docdate} 文書の保存(更新)日が入る③ ''' シングルクオートを3個以上で横線を入れる
3. 文書タイトルと表を使った日時などの表現
文書タイトルは、レベル0やレベル1でPDFを作成すると、文字が大きすぎるので、 レベル2をタイトルとして使用しました。
また、AsciiDocでは、改行や連続するスペースを無効にするため、 文字を揃えることが難しい
ときに、表(罫線なし)を使うこともひとつの方法です。
(日時、場所などの情報を表を使って表現)=== 第3回 プロジェクト会議議事録①[cols="1,8",frame="topbot",grid="none"]
②
|====
| 日時
| 令和3年3月25日 15:00-15:45| 場所| 第6会議室| 出席者 | チームリーダー、スタッフ2名、開発室長、開発室3名

31

AsciiDoc文書作成入門

7.1. 議事録|====① = レベル0(文書タイトル), == レベル1(chapter(章)), === レベル2(section)② cols="1,8" は、2列の表で、列幅を1対8とする指定(左 <, 中央 ^, 右 > と組み合わせることも可能(cols="^1,<8"))frame="topbot" 外枠で、上(top)と下(bottom)のみ表示
grid="none" 表の罫線なし
4. ラベル付きリスト
ラベル付きリストで、議事内容を表現[qanda]①
提案概要説明::②
資料を配布し、提案概要を開発室から説明
チームリーダー質疑::③
提案Aについて:::文書の間違いが、多くなっているが・・・・・。

① [qanda] Q&A 形式のラベルリスト指定(通常のラベルリストに番号が付与される)② ラベルリストのラベル部分は、行末の :: コロンを2つ③ ラベルリストをネストするには、行末の ::: コロンを増やす
5. テキストの右寄せ
右寄せするには、段落のはじめに [.text-right] とする。(中央は [.text-center])[.text-right]
以上

レベル1が無いため、asciidoctor-pdf で WARNING メッセージが出ます。
標準のスタイルでは、レベル1の文字が大きすぎるので、レベル2を使用した。

32$ asciidoctor-pdf example-03.adoc
asciidoctor: WARNING: example-03.adoc: line 14: section title out of
sequence: expected level 1, got level 2

8. 日本語フォントの利用

8.1. 日本語フォントの導入

8. 日本語フォントの利用
asciidoctor-pdf で日本語の文書をPDFにする場合、デフォルトの日本語のフォント(M+ 1p ゴシック
系フォント、漢字 約5,200字)では、JIS第3、第4水準漢字など、表示できない文字があります。 このため、フリーの日本語フォントを導入し、スタイルファイルを設定することで、明朝体を含む各種フォントを用いて文書の作成を行うことができます。
フォントによって表示できない文字があります。
asciidoctor-pdf標準(M+ 1p Fallback)淺(浅),神(神),飛驒(飛騨),﨑(崎),℣圡,Ⅲⅲ③Ⅳⅳ④,℃※◉♤㌶㍻
MigMix1P
淺(浅),神(神),飛驒(飛騨),﨑(崎),℣圡,Ⅲⅲ③Ⅳⅳ④,℃※◉♤㌶㍻
ShipporiMincho
淺(浅),神(神),飛驒(飛騨),﨑(崎),℣圡,Ⅲⅲ③Ⅳⅳ④,℃※◉♤㌶㍻

8.1. 日本語フォントの導入
asciidoctor-pdfで利用できる日本語フォントは、TrueTypeに限られています。 (asciidoctor-pdfを構成するRubyのPrawnライブラリに依存し、OpenTypeには対応していない。) また、Regular,
Boldなど、複数のWeight(重さ、太さ)を持ち、PDF埋め込みフォントとして商用も含めてフリーのライセンスで配布されている必要があります。 なお、日本語のアウトラインフォント では、イタリック(斜体)をサポートしたフォントが無いため、イタリックの表示はできません。
フリーフォント配布サイトから、TrueTypeフォント(.ttf)をダウンロードします。(OpenTypeフォン
ト(.otf)は、利用できません。)• MigMix https://mix-mplus-ipa.osdn.jp/migmix/• 原真ゴシック http://jikasei.me/font/genshin/• しっぽり明朝 https://fontdasu.com/shippori-mincho/• 源様明朝 https://github.com/ButTaiwan/genyo-font/tree/bc2fa246196fefc1ef9e9843bc8cdba22523a39d• IBM Plex Sans JP https://github.com/IBM/plex/tree/master/IBM-Plex-Sans-JP/fonts/
complete/ttf/hinted• Google Fonts https://fonts.google.com/?subset=japanese

8.1.1. MigMix (ミグミックス)フォント
MigMixフォントは、asciidoctor-pdfの標準日本語フォント(M+フォント)に、IPAゴシックフォントを合成し、JIS第1水準漢字〜第4水準漢字をサポートしています。 また、Regular と Bold の2種類のWeightをサポートしたTrueTypeフォントです。(IPAフォントには、Bold がありません。)

33

AsciiDoc文書作成入門

8.2. フォントの配置• https://mix-mplus-ipa.osdn.jp/migmix/
MigMix 1P と MigMix 2P がありますので、好みのフォントをダウンロードして下さい。
• migmix-1p-20200307.zip (約4MB)• migmix-2p-20200307.zip (約4MB)

8.2. フォントの配置
ダウンロードしたフォントファイルを展開し、作業ディレクトリ配下の fonts ディレクトリに配置します。

.
├── example-04.adoc└── fonts├── migmix-1p-bold.ttf└── migmix-1p-regular.ttf

8.3. themeファイル作成(フォント設定)
asciidoctor-pdf で独自フォントを使うためには、新たにthemeファイルを作成し、設定します。 フォント以外にも出力書式を変更するには、themeファイル(YAML)で指定する必要があります。
リスト 11. 独自フォントを設定したthemeファイル(example-04-theme.yml)
1 extends: default-with-font-fallbacks
2 font:3 catalog:
4merge: true5
# MigMix 1p
MigMix 1P:
6
7
normal: migmix-1p-regular.ttf
8bold: migmix-1p-bold.ttf
9italic: migmix-1p-regular.ttf
10bold_italic: migmix-1p-bold.ttf
11 fallbacks: [MigMix 1P, M+ 1p Fallback, Noto Emoji]

1. extends: default-with-font-fallbacks デフォルトテーマを拡張するため、 extends: を指定
2. 「フォントカタログ」にフォントを追加する。 標準フォントも使う場合マージを有効に(marge:true)する
a. MigMix 1P フォントの設定 (italic, bold_italic は、日本語フォントが無いためRegular, Boldを指定)
3. 「フォールバックフォント」に、日本語フォント(MigMix 1P)を指定
a. fallbacks: [MigMix 1P, M+ 1p Fallback, Noto Emoji]b. M+ 1p Fallback, Noto Emoji は、 default-woth-fallback-font themeで指定されている

34

8. 日本語フォントの利用

8.4. アトリビュートの指定

c. M+ 1p Fallback は、 MigMix 1P に置き換え可能

8.4. アトリビュートの指定
設定したthemeファイルとフォントディレクトリを、アトリビュートで指定します。
リスト 12. AsciiDoc文書のアトリビュート設定:scripts: cjk:doctype: article:pdf-theme: example-04-theme.yml:pdf-fontsdir: ./fonts;GEM_FONTS_DIR①②① PDF出力のためのthemeファイルを指定② PDF用独自フォントのディレクトリを指定 (GEM_FONTS_DIR は、デフォルトフォントのPATH)

8.5. フォントを変更した出力例
8.5.1. フォールバックフォントにMigMix 1Pを指定

図 36. フォールバックフォントにMigMix 1Pを指定

35

8.5. フォントを変更した出力例

AsciiDoc文書作成入門

8.5.2. 基本フォントにMigMix 1Pを設定
リスト 13. 基本フォントを変更したthemeファイル(example-04-2-theme.yml)
1 extends: default-with-font-fallbacks
2 font:3 catalog:
4merge: true5
# MigMix 1p
6
MigMix 1P:
7normal: migmix-1p-regular.ttf
8bold: migmix-1p-bold.ttf
9italic: migmix-1p-regular.ttf
10bold_italic: migmix-1p-bold.ttf
11 fallbacks: [MigMix 1P, M+ 1p Fallback, Noto Emoji]
12 base:13 font_family: MigMix 1P
14 line_height: 1.4

1. base 基本書式で、 font_family に、日本語フォント(MigMix 1P)を指定する
2. Noto Serifと文字の高さ(line_height)が異なるため、 line_height: 1.4 を指定

図 37. 基本フォントにMigMix 1Pを指定

項番やタイトルが、ゴシックのボールド書体となり、かなり印象が変わります。
• 代替フォントが、デフォルトフォールバックフォント(M+ 1p)の場合、Boldな
どの書式指定(セクションタイトルなど)が無効となります。
(M+ 1p can only be styled as normal .)• 基本フォントファミリー(base_font_family)として日本語フォントを指定した場合、書式指定は有効ですが、英文も日本語フォントとなります。
• asciidoctor-pdfでは、英文フォントと日本語フォントを別々に指定する事がで
きません。

36

8. 日本語フォントの利用

8.5. フォントを変更した出力例

8.5.3. 基本フォントに明朝系(ShipporiMinchoB1)を指定
リスト 14. 明朝系フォントを設定したthemeファイル(example-04-3-theme.yml)
1 extends: default-with-font-fallbacks
2 font:3 catalog:
4merge: true5
# ShipporiMinchoB1
6
ShipporiMinchoB1:
7
normal: ShipporiMinchoB1-Regular.ttf
8bold: ShipporiMinchoB1-ExtraBold.ttf
9italic: ShipporiMinchoB1-Regular.ttf
10bold_italic: ShipporiMinchoB1-ExtraBold.ttf
11 fallbacks: [ShipporiMinchoB1, M+ 1p Fallback, Noto Emoji]
12 base:13 font_family: ShipporiMinchoB1
14 line_height: 1.4

1. base 基本書式で、 font_family に、日本語フォント(ShipporiMinchoB1)を指定する
2. Noto Serifと文字の高さ(line_height)が異なるため、 line_height: 1.4 を指定

図 38. 基本フォントにShipporiMinchoB1を指定

タイトルを含めて明朝体となり、文書全体の印象が変わります。

37

8.5. フォントを変更した出力例

AsciiDoc文書作成入門

8.5.4. 基本フォントにゴシック系(IBMPlexSansJP)を指定
リスト 15. ゴシック系フォントを設定したthemeファイル(example-04-4-theme.yml)
1 extends: default-with-font-fallbacks
2 font:3 catalog:
4merge: true5
# MigMix 1p
6
MigMix 1P:
7normal: migmix-1p-regular.ttf
8bold: migmix-1p-bold.ttf
9italic: migmix-1p-regular.ttf
10bold_italic: migmix-1p-bold.ttf
11# IBMPlexSansJP
12IBMPlexSansJP:
13normal: IBMPlexSansJP-Regular.ttf
14bold: IBMPlexSansJP-SemiBold.ttf
15
italic: IBMPlexSansJP-Regular.ttf
16bold_italic: IBMPlexSansJP-SemiBold.ttf
17 fallbacks: [MigMix 1P, M+ 1p Fallback, Noto Emoji]
18 base:19 align: left
20 font_family: IBMPlexSansJP

1. base 基本書式で、 font_family に、日本語フォント(IBMPlexSansJP)を指定する
2. ソースコードなどのフォント(codespan_font_family: M+ 1mn)の日本語代替フォントとして、
fallbacks: MigMix 1P を指定



M+ 1mn と比較して IBMPlexSansJP は、文字の高さが高い。

図 39. 基本フォントにIBMPlexSansJPを指定

38

8. 日本語フォントの利用

8.5. フォントを変更した出力例

8.5.5. サンプル文書「日本語フォントの利用」のAsciiDoc文書は、以下のとおりです。
リスト 16. 日本語フォントの利用(example-04.adoc)
1 = 日本語フォントの利用
2 :scripts: cjk
3 :doctype: article
4 :pdf-theme: example-04-theme.yml
5 //:pdf-theme: example-04-2-theme.yml
6 //:pdf-theme: example-04-3-theme.yml
7 //:pdf-theme: example-04-4-theme.yml
8 :pdf-fontsdir: ./fonts;GEM_FONTS_DIR
9 :sectnums:
10
11 == PDF出力フォントの変更
12
13 === デフォルトのフォント (default font)
14
15 asciidoctor-pdf のデフォルトフォントは、 `Noto Serif` (英文フォント)です。
16
17 === フォールバックフォント (fallbacks)
18
19 *Noto Serif* に入っていない文字(日本語)は、**フォールバックフォント**(`M+ 1p
Fallback`)が使われます。 +20 `:pdf-theme: default-with-font-fallbacks`を指定すると、フォールバックフォントとして、M+系フォント mplus1p-regular-fallback.ttf
が設定されます。
21
22 == フォントの導入
23
24 フリーの日本語TrueTypeフォントをダウンロードして、./fontsディレクトリに保存します。 +25 フォント用ディレクトリは任意ですが、相対PATHで指定し、環境に依存しない様にします。
26
27 === theme ファイル作成
28
29 フォントカタログ(フォント名とフォントファイルの設定)を作成し、asciidoctorpdfで使用するフォントの設定を行う。
30
31 === アトリビュート設定
32
33 asiidoc文書に、PDF出力に使用する theme ファイルと、フォントディレクトリの指定を行う。
34
35 == 難しい漢字も出力できる
36
37 淺(浅),神(神),飛驒(飛騨),﨑(崎),℣圡,Ⅲⅲ③Ⅳⅳ④,℃※◉♤㌶㍻
38
39 [cols="<2,^3", options="header", width="90%"]
40 .表題41 |====
42 |テキスト| 表示
43 |`\*強調(bold)*`| *強調(bold)*
44 |`\_斜体(italic)_`| _斜体(italic)_ 日本語フォントは、__italic__がない
45 |====

39

9.1. 冊子(book)スタイル

AsciiDoc文書作成入門

9. 長文(冊子)スタイルの文書作成
この文書「AsciiDoc文書作成入門」などの説明書やマニュアル、仕様書など、冊子(book)スタイル
での文書作成について説明します。
デフォルトのスタイルで日本語の文書を作成すると、目次や章タイトル、キャプションの表記が英語となります。 見栄えの良い文書を作成するには、アトリビュートによる設定変更や、themeファイルによる文書スタイルの変更が必要です。
長文の文書や共同で文書を作成する場合、章ごとにファイルを分割することで、修正などの作業が容易になります。 ファイルの分割やイメージ用サブフォルダの利用なども合わせて説明します。

9.1. 冊子(book)スタイル
文書のアトリビュートで、 :doctype: book を指定します。
リスト 17. 冊子(book)スタイルの指定(example-05.adoc)= AsciiDocの使い方: AsciiDocでマニュアルを作成する
著者 Hikari KOSHINO <koshihikari@example.com>
Ver.2.0, 2021-07-01:doctype: book:scripts: cjk:pdf-theme: default-with-font-fallbacks:sectnumlevels: 4:sectnums::toc: left

1. :doctype: book で、冊子スタイルを指定 (デフォルトは、 article)
a. 表紙には、文書タイトル(あればサブタイトル)、著者、バージョンが表示される
2. :toc: で、目次作成を指定
a. 項目名、ページを自動取得して目次を作成
b. :toc: left html出力時に、左(left)側に目次を作成
デフォルトスタイルで、 :doctype: book と :toc: を指定した場合、表紙は「右寄せ」、目次と章タイトルなどが、英語表記になります。

40

9. 長文(冊子)スタイルの文書作成

9.1. 冊子(book)スタイル

図 40. 表紙

図 41. 目次

図 42. Chapter 1

41

9.2. アトリビュートによる設定

AsciiDoc文書作成入門

9.2. アトリビュートによる設定
文書ファイルにアトリビュート設定することで、変更ができるスタイルを説明します。
以下のアトリビュート設定は、ほぼ共通の設定として、文書作成の際にコピーして(あるいはカスタ
マイズして)利用できます。
リスト 18. 冊子(book)スタイルの指定(example-05.adoc)
1 = AsciiDocの使い方: AsciiDocでマニュアルを作成する
2 著者 Hikari KOSHINO <koshihikari@example.com>
3 Ver.2.0, 2021-07-01
4 :doctype: book
5 :scripts: cjk
6 :pdf-theme: default-with-font-fallbacks
7 :sectnumlevels: 4
8 :sectnums:
9 :chapter-signifier:
10 :preface-title: まえがき
11 :appendix-caption: 付録
12 :toc: left
13 :toclevels: 4
14 :toc-title: 目次
15 :figure-caption: 図
16 :table-caption: 表
17 :listing-caption: リスト
18 :example-caption: 例
19 :note-caption: 注記
20 :tip-caption: ヒント
21 :coution-caption: 注意
22 :warning-caption: 警告
23 :important-caption: 重要
24 :version-label: Ver.
25 :last-update-label: 最終更新

1. タイトル: サブタイトル (表紙)
2. 著者 (表紙)
3. バージョン、日付 (表紙)
4. :doctype: book 文書スタイルを、冊子(book)とする
5. :scripts: cjk 日本語文書の改行位置(word wrap)などの修正を有効とする
6. :pdf-theme: default-with-font-fallbacks PDF書式を定義するthemeファイルを指定
7. :sectnumlevels: 4 セクション番号をレペル4(1.1.1.1)までに設定する
8. :sectnums: セクション番号を設定(自動採番)に設定する
9. :chapter-signifier: bookスタイルで、章レベルのタイトル"Chapter"を無効とする
10. :preface-title: まえがき 本文(第1章)の前の文章タイトルを"まえがき"とする
11. :appendix-caption: 付録 Appendixのタイトルを"付録"とする

42

9. 長文(冊子)スタイルの文書作成

9.2. アトリビュートによる設定

12. :toc: left 目次を作成する(HTML出力の場合、左側に目次を作成)
13. :toclevels: 4 セクションレベル4まで目次を作成する
14. :toc-title: 目次 目次のタイトルを"目次"とする(Table of Contents)
15. :figure-caption: 図 図(image)のキャプションを"図"とする(Figure)
16. :table-caption: 表 表のキャプションを"表"とする(Table)
17. :listing-caption: リスト リストのキャプションを"リスト"とする
18. :example-caption: 例 Exampleキャプションを"例"とする
19. :note-caption: 注記 NOTEのキャプションを"注記"とする
20. :tip-caption: ヒント TIPのキャプションを"ヒント"とする
21. :coution-caption: 注意 COUTIONのキャプションを"注意"とする
22. :warning-caption: 警告 WARNINGのキャプションを"警告"とする
23. :important-caption: 重要 IMPORTANTのキャプションを"重要"とする
24. :version-label: Ver. バージョンのラベルを"Ver."とする
25. :last-update-label: 最終更新 last-updateのラベルを"最終更新"とする
サブタイトルを入力するには、タイトルとサブタイトルを : (コロン) で区切ります。

図 43. 表紙(サブタイトル)

目次のタイトル(Table of Contents)が"目次"となっています。

図 44. 目次タイトルが"目次" ("まえがき"追加)

本文(第1章)の前に書かれた文章が、"まえがき"として独立しています。

43

9.2. アトリビュートによる設定

AsciiDoc文書作成入門

図 45. まえがき

章のラベル(Chapter)が無効となり、"1. AsciiDocとは(見出し1)"となっています。 また、リストのキャプションが"リスト 1."となっています。
asciidoctor-pdf Ver.2系から :chapter-label: が無効になった。(:chapter-signifier: に変更)

図 46. Chapter 1 (chapter-signifierなし, リストキャプション)

表のキャプションが"表 1."になっています。

図 47. 表キャプション

図のキャプションが"図 1."になっています。

図 48. 図キャプション

タイトルやキャプションを日本語にすることで、日本語の文書として見栄えも良くなりました。

44

9. 長文(冊子)スタイルの文書作成

9.3. themeファイルによる書式変更

9.3. themeファイルによる書式変更
アトリビュートの変更では対応できない書式変更は、日本語フォントで作成したthemeファイルにより設定します。
サンプルのthemeファイルを紹介し、設定の内容を説明します。

9.3.1. サンプルテーマファイル(example-06-theme.yml)
1. フォント設定は、前項「日本語フォントの利用」で紹介した設定を入れます。
リスト 19. フォントの設定(example-06-theme.yml)
1 extends: default-with-font-fallbacks
2 font:3 catalog:
4merge: true5
# MigMix 2p
6
MigMix 2P:
7normal: migmix-2p-regular.ttf
8bold: migmix-2p-bold.ttf
9italic: migmix-2p-regular.ttf
10bold_italic: migmix-2p-bold.ttf
11 fallbacks: [MigMix 2P, M+ 1p Fallback, Noto Emoji]a. fallbacks に日本語フォントを設定し、基本フォント($base_font_family) は、デフォルトを使用します。
b. ひらがな濁音などの違いから、MigMix 2Pを選択しています。(MigMix 1P(ごずぞ), MigMix
2P(ごずぞ))2. ページの余白を設定します。
リスト 20. ページ余白の設定(example-06-theme.yml)
1 page:2 margin: [0.9in, 0.9in, 0.9in, 0.9in]

a. 書式は、 margin: [上, 右, 下, 左] です。(デフォルトは、 margin: [0.5in, 0.67in,
0.67in, 0.67in])3. base 基本設定で、本文書式(align: left)を設定します。
リスト 21. 本文の基本設定(example-06-theme.yml)
1 base:2 align: left

a. デフォルトでは、 aligin: justify となっていますが、日本語では、単語区切りのスペースが広くなる場合があり、左寄せ(left)に設定したほうが見栄えが良くなります。

45

AsciiDoc文書作成入門

9.3. themeファイルによる書式変更

4. プログラムソースコードなどのフォントサイズを変更します。
リスト 22. ソースコードのフォントサイズ設定(example-06-theme.yml)
1 code:2 font-size: $base_font_size * 0.9

a. デフォルトでは、基本フォントサイズの小数点以下切り上げ(font_size:ceil($base_font_size))となっています。一行の文字数が少なく改行されることも多いため、若干フォントサイズを小さく(font-size: $base_font_size * 0.9)しています。
5. 表紙の書式を変更します。(センタリング、タイトル、著者、バージョンの位置を変更)
リスト 23. 表紙の設定(example-06-theme.yml)
1 title_page:2 align: center3 title:4
top: 45%
5 authors:
6
margin_top: $base_font_size * 25
7 revesion:
8
margin_top: $base_font_size * 1.5

a. 表紙(title_page)を修正し、センタリングとし、タイトル、著者、バージョンの位置を変更
しています。

図 49. 表紙の書式変更

46

9. 長文(冊子)スタイルの文書作成

9.3. themeファイルによる書式変更

6. キャプションの位置を変更(センタリング)します。
リスト 24. キャプションの位置を変更()センタリング)(example-06-theme.yml)
1 caption:
2 align: centera. デフォルトでは、左寄せ(align: left)となっています。 ここで設定することで、図、表、リストなどのキャプションがセンタリングされます。

7. heading: では、見出しの書式を設定します。
リスト 25. 見出しの設定(example-06-theme.yml)
1 heading:
2 chapter:3
break-before: autoa. ここでは、bookスタイルで、"章(Caption)"の前で改ページすることを抑制(auto)する設定にしています。 (デフォルトでは、改ページします。)
8. 表(Table)の書式設定を変更します。
リスト 26. 表の書式設定(example-06-theme.yml)
1 table:2 head:3
font_color: $base_font_color
4
background_color: [185,174,166]
5 foot:6
background_color: [185,174,166]
7 cell_padding: [3, 3, 3, 3]

a. 表のヘッダー(head:)とフッター(foot:)部分の書式(背景色)を変更しています。 (上記(キャプション)のイメージ参照)
b. 表のセルの余白(cell_padding:)を設定しています。
9. ページヘッダーを設定します。
リスト 27. ページヘッダーの設定(example-06-theme.yml)
1 header:47

AsciiDoc文書作成入門

2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17

9.3. themeファイルによる書式変更

border-color: #aaaaaa
border-style: double
border-width: 0.25
height: $base-line-height-length * 2.8
vertical-align: bottom
padding: [$base-line-height-length / 5, 3, 5, 3]
recto:
left:content: '{chapter-title}'right:
content: '{section-or-chapter-title}'
verso:
left:content: '{document-title}'right:
content: '{section-or-chapter-title}'# <-- 右見開きページ# <-- チャプタータイトル# <-- セクションタイトル# <-- 左見開きページ# <-- ドキュメントタイトル# <-- セクションタイトル

a. ヘッダーの表示位置の指定や線の書式を設定します。
b. 特定の固定文字(取り扱い情報など)の他に、(chapter-title)などの変数が使えます。
c. 見開きページの左右で違う情報を表示することも可能です。(1ページが見開き右ページとみなす)
d. ページヘッダーは、表紙、目次のページには表示されません。

図 50. ページヘッダー

e. フッターは、デフォルトで設定されており、ページ番号が表示されます。

図 51. フッター

10. サンプルテーマファイル(全体)
リスト 28. themeファイルによる書式指定(example-06-theme.yml)
1 extends: default-with-font-fallbacks
2 font:48

9. 長文(冊子)スタイルの文書作成

9.3. themeファイルによる書式変更

3 catalog:
4merge: true5
# MigMix 2p
MigMix 2P:
6
7
normal: migmix-2p-regular.ttf
8bold: migmix-2p-bold.ttf
9italic: migmix-2p-regular.ttf
10bold_italic: migmix-2p-bold.ttf
11 fallbacks: [MigMix 2P, M+ 1p Fallback, Noto Emoji]
12 page:
13 margin: [0.9in, 0.9in, 0.9in, 0.9in]
14 base:15 align: left
16 code:17 font-size: $base_font_size * 0.9
18 title_page:
19 align: center
20 title:
21
top: 45%
22 authors:23
margin_top: $base_font_size * 25
24 revesion:
25
margin_top: $base_font_size * 1.5
26 caption:
27 align: center
28 heading:
29 chapter:30
break-before: auto
31 table:
32 head:33
font_color: $base_font_color
34
background_color: [185,174,166]
35 foot:36
background_color: [185,174,166]
37 cell_padding: [3, 3, 3, 3]
38 header:
39 border-color: #aaaaaa
40 border-style: double
41 border-width: 0.25
42 height: $base-line-height-length * 2.8
43 vertical-align: bottom
44 padding: [$base-line-height-length / 5, 3, 5, 3]
45 recto:# <-- 右見開きページ
46
left:
47
content: '{chapter-title}'# <-- チャプタータイトル
right:
48
49
content: '{section-or-chapter-title}'# <-- セクションタイトル
50 verso:# <-- 左見開きページ
51
left:
52
content: '{document-title}'# <-- ドキュメントタイトル
53
right:
54
content: '{section-or-chapter-title}'# <-- セクションタイトル

49

AsciiDoc文書作成入門

9.3. themeファイルによる書式変更

9.3.2. アトリビュートの変更
作成したthemeファイルを参照するため、日本語フォントの利用で紹介したとおり、アトリビュートの設定が必要です。 作成する文書のアトリビュートに、以下の設定を追加(変更)して下さい。
リスト 29. アトリビュート(themeファイルとフォントディレクトリの指定)
1 :pdf-theme: example-06-theme.yml
2 :pdf-fontsdir: ./fonts;GEM_FONTS_DIR

9.3.2.1. 他のアトリビュート追加設定
これまで説明したアトリビュートの他に、追加設定したアトリビュートを紹介します。
1. 画像(イメージ)ファイル用のディレクトリを指定します。
リスト 30. アトリビュート(画像ディレクトリの指定)
1 :imagesdir: ./imagesa. ファイル数が多い場合、画像ファイルをimagesディレクトリにまとめることで、メンテナン
ス性がよくなります。 :imagesdir: ./images を設定することで、本文から参照する際に、ディレクトリ名を省略することができます。
2. 注記(NOTE)などのアイコンの設定
リスト 31. アトリビュート(注記のアイコンの指定)
1 :icons: fonta. NOTE: 注記などの表示がアイコンになります。

注記

デフォルトでは、 :note-caption: で設定した"注記"になります。



注記(NOTE)の表示がアイコンになります。

3. ソースコードのハイライト表示
リスト 32. アトリビュート(ソースコードのハイライト表示指定)
1 :source-highlighter: rougea. ソースコードをハイライト表示するには、rouge, coderayなどのハイライト用ツールをインストールする必要があります。

50

9. 長文(冊子)スタイルの文書作成

9.3. themeファイルによる書式変更

リスト 33. コードハイライト用ツール(rouge)のインストール$ gem install rougeb. AsciiDocの記述は、以下のようにします。
リスト 34. コードハイライトの使用例(AsciiDocの記述).コードハイライトの使用例(YAML)[source, yaml, linenum]①---extends: default-with-font-fallbacks
font:
catalog:
merge: true
# MigMix 2p
MigMix 2P:
normal: migmix-2p-regular.ttf
bold: migmix-2p-bold.ttf
italic: migmix-2p-regular.ttf
bold_italic: migmix-2p-bold.ttf
fallbacks: [MigMix 2P, M+ 1p Fallback, Noto Emoji]----① コードハイライトの指定は、 [source, 形式, 行番号付与] のように記述します。
c. コードハイライトにより、キーワードやコメント部分の色分けや行番号の付与などができます。
リスト 35. コードハイライトの使用例(YAML)
1 extends: default-with-font-fallbacks
2 font:3
catalog:4
merge: true5
# MigMix 2p
6
MigMix 2P:
7normal: migmix-2p-regular.ttf
8bold: migmix-2p-bold.ttf
9italic: migmix-2p-regular.ttf
10bold_italic: migmix-2p-bold.ttf
11
fallbacks: [MigMix 2P, M+ 1p Fallback, Noto Emoji]

9.3.2.2. サンプルで指定したアトリビュート
このサンプルで指定したアトリビュートは、以下のとおりです。
リスト 36. themeファイル設定を使用したサンプルのアトリビュート
1 = AsciiDocの使い方: AsciiDocでマニュアルを作成する
2 著者 Hikari KOSHINO <koshihikari@example.com>
3 Ver.2.0, 2021-07-01

51

9.4. ファイルの分割

AsciiDoc文書作成入門

4 :doctype: book
5 :scripts: cjk
6 :pdf-theme: example-06-theme.yml
7 :pdf-fontsdir: ./fonts;GEM_FONTS_DIR
8 :imagesdir: ./images
9 :icons: font
10 :source-highlighter: rouge
11 :sectnumlevels: 4
12 :sectnums:
13 :chapter-signifier:
14 :preface-title: まえがき
15 :appendix-caption: 付録
16 :toc: left
17 :toclevels: 4
18 :toc-title: 目次
19 :figure-caption: 図
20 :table-caption: 表
21 :listing-caption: リスト
22 :example-caption: 例
23 :note-caption: 注記
24 :tip-caption: ヒント
25 :coution-caption: 注意
26 :warning-caption: 警告
27 :important-caption: 重要
28 :version-label: Ver.
29 :last-update-label: 最終更新

9.4. ファイルの分割
共同で文書を作成する場合、同じファイルを複数で同時に編集すると修正部分が上書きされて戻ったり不整合が発生します。 各章ごとにファイルを分割して分担することで、競合が少なくなります。(gitなどバージョン管理ツールを使うことも有効です。) また、1,000行を超えるようなファイルを編集する場合、修正箇所を間違えたり、エディタでのカーソル移動も容易ではありません。
リスト 37. ファイルの分割例.
├── example-07.adoc├── example-07-01.adoc├── example-07-02.adoc├── example-07-theme.yml├── fonts│ ├── migmix-2p-bold.ttf│ └── migmix-2p-regular.ttf└── images├── example-image-01.png└── example-image-02.png

ボリュームのある文書を作成する場合や共同で編集する場合、ファイルを分割すると編集作業が効率的になります。
1. example-07.adoc は、メインのファイルで、文書タイトル、アトリビュート設定を記述し、分割

52

9. 長文(冊子)スタイルの文書作成

9.4. ファイルの分割した各章のファイルをインクルードします。
リスト 38. example-07.adoc
1 = AsciiDocの使い方: AsciiDocでマニュアルを作成する
2 著者 Hikari KOSHINO <koshihikari@example.com>
3 Ver.2.0, 2021-07-01
4 :doctype: book
5 :scripts: cjk
6 :pdf-theme: example-07-theme.yml
7 :pdf-fontsdir: ./fonts;GEM_FONTS_DIR
8 :imagesdir: ./images
9 :icons: font
10 :source-highlighter: rouge
11 :sectnumlevels: 4
12 :sectnums:
13 :chapter-signifier:
14 :preface-title: まえがき
15 :appendix-caption: 付録
16 :toc: left
17 :toclevels: 4
18 :toc-title: 目次
19 :figure-caption: 図
20 :table-caption: 表
21 :listing-caption: リスト
22 :example-caption: 例
23 :note-caption: 注記
24 :tip-caption: ヒント
25 :coution-caption: 注意
26 :warning-caption: 警告
27 :important-caption: 重要
28 :version-label: Ver.
29 :last-update-label: 最終更新
31
32 この文書は、AsciiDocの使い方・・・・・
33
34 include::example-07-01.adoc[]
35
36 include::example-07-02.adoc[]a. インクルード(include)で、各章のファイルを読み込みます。
b. 複数のファイルをインクルードする場合、一行目の記述が前章最後の段落とみなされる場合があるため、includeを記述する場合は、一行以上の空行を入れます。
2. example-07-01.adoc は、第1章を記述しています。
3. example-07-02.adoc は、第2章を記述しています。
4. example-07-theme.yml は、themeファイルによる書式設定で、 example-06-theme.yml と同じです。
5. fonts ディレクトリにフォントファイルを配置します。
6. images ディレクトリに画像ファイルを置きます。

53

AsciiDoc文書作成入門

9.4. ファイルの分割

9.4.1. 文書作成
メインの文書(example-07.adoc)を使って文書を作成します。 インクルード(include)した文書が読み込まれて、全体の文書が生成されます。

$ asciidoctor-pdf example-07.adoc

54

10. 仕様書作成等に向いたスタイル

10.1. 前項のスタイルファイル

10. 仕様書作成等に向いたスタイル
デフォルトのテーマで作成した文書は、章や項(セクション)のタイトル文字が大きく、マニュアル等の文書では、「見出し」として分かりやすい印象です。 しかし、仕様書などでは、見出しが目立ちすぎるため、表紙や見出しを変更したテーマファイルの設定例を紹介します。

10.1. 前項のスタイルファイル
まず、前項で作成したスタイルファイルとアトリビュートを使って、仕様書を作成してみます。

図 52. 表紙

図 53. 目次

55

10.2. スタイルファイル変更

AsciiDoc文書作成入門

図 54. 本文

このままでも悪くは無いと思いますが、文書の提出先によっては書式を変更する必要があります。
問題のありそうな箇所• 表紙のタイトルの色とフォントの大きさ• タイトル、サブタイトルの表示場所• 日付の場所• 項番、見出しのフォントの大きさ
これらの変更をスタイルファイルで設定します。

10.2. スタイルファイル変更
表紙のスタイルや項番、見出しの大きさなどを変更するには、テーマ(theme)ファイルを変更する必要があります。
全体のフォント(base_font_family)設定• 日本語フォントの項で紹介したMigMixフォントを設定します。
リスト 39. base_font_familyの設定
1 base:2 align: left
3 font_color: 000000
4 font_family: MigMix 2P
5 line_height_length: 15.5
6 line_height: $base_line_height_length / $base_font_size

1. base: 基本設定
2. align: left 日本語文書の場合、単語区切りスペースが広くなる場合があるため、左寄せ

56

10. 仕様書作成等に向いたスタイル

10.2. スタイルファイル変更に設定
3. font_color: 000000 フォントの色を"黒"に設定
4. font_family: MigMix 2P 文書全体の基本フォントを、 MigMix 2P に設定
5. line_height_length: 15.5 日本語フォントの高さを変更
6. line_height: $base_line_height_length / $base_font_size 行幅(行間)の設定
表紙(title_page)の設定
リスト 40. title_page(表紙)の設定
1 title_page:2 align: center3 title:4
top: 25%
5
font_size: 20
6font_style: bold7
font_color: 000000
8
line_heght: 2.0
9 subtitle:10
font_size: 18
11
font_style: bold
12
font_color: 000000
13
line_heght: 2.0
14
margin_top: 1.2cm
15 authors:16
font_color: 000000
17
margin_top: 12.5cm
18 revision:
19
font_color: 000000
20
margin_top: -2cm

1. title_page: 表紙の設定
2. align: center タイトルページを中央揃え(center)に設定
3. title: タイトル(文書の標題)の設定
4. top: 25% 印刷範囲の上から25%に、タイトルを表示
5. font_size: 20 タイトルの文字の大きさを20ポイントに設定
6. font_style: bold タイトルを太文字(bold)に設定
7. font_color: 000000 文字の色を"黒"に設定
8. line_heght: 2.0 行幅(行間)の設定
9. subtitle: サブタイトルの設定
10. font_size: 18 サブタイトルの文字の大きさを18ポイントに設定
11. font_style: bold タイトルを太文字(bold)に設定
12. font_color: 000000 文字の色を"黒"に設定
13. line_heght: 2.0 行幅(行間)の設定

57

10.2. スタイルファイル変更

AsciiDoc文書作成入門

14. margin_top: 1.2cm サブタイトルの表示位置を、タイトルから1.2cm下げる設定
15. authors: 著者(仕様書であれば組織名)の設定
16. font_color: 000000 文字の色を"黒"に設定
17. margin_top: 12.5cm 著者の表示位置を、サブタイトルから12.5cm下げる設定
18. revision: バージョン(日付)の設定
19. font_color: 000000 文字の色を"黒"に設定
20. margin_top: -2cm 日付の表示位置を、著者の表示位置から-2cmとする設定 (日付の表示位置
が著者の下になるため、-2cmとして上に表示するようにしている)
見出し(heading)の設定
リスト 41. title_page(表紙)の設定
1 heading:
2 chapter:3
break-before: auto
4 font_family: $base_font_family
5 font_style: bold
6 font_color: 000000
7 h1_font_size: floor($base_font_size * 1.4)
8 h2_font_size: floor($base_font_size * 1.2)
9 h3_font_size: round($base_font_size * 1.1)
10 h4_font_size: $base_font_size
11 h5_font_size: $base_font_size
12 h6_font_size: $base_font_size

1. heading: 見出しの設定
2. chapter: 章の設定(bookスタイル)
3. break-before: auto bookスタイルで、章の前で改ページすることを抑制する
4. font_family: $base_font_family 基本設定のフォントを使う設定
5. font_style: bold 見出し文字を太文字(bold)に設定
6. font_color: 000000 文字の色を"黒"に設定
7. h1_font_size: floor($base_font_size * 1.4) H1ヘッダーのフォントサイズ (基本フォントの1.4倍(端数切り捨て))8. h2_font_size: floor($base_font_size * 1.2) H2ヘッダーのフォントサイズ (基本フォントの1.2倍(端数切り捨て))9. h3_font_size: round($base_font_size * 1.1) H3ヘッダーのフォントサイズ (基本フォントの1.1倍(端数四捨五入))
10. h4_font_size: $base_font_size H4ヘッダーのフォントサイズ (基本フォントと同じ)
11. h5_font_size: $base_font_size H5ヘッダーのフォントサイズ (基本フォントと同じ)
12. h6_font_size: $base_font_size H6ヘッダーのフォントサイズ (基本フォントと同じ)

58

10. 仕様書作成等に向いたスタイル

10.2. スタイルファイル変更

その他の変更リスト 42. その他の設定変更
1 role:2 red:
3
font_color: ff0000
4 yellow:5
font_color: ffff00
6 green:7
font_color: 008000
8 aqua:9
font_color: 00ffff
10 blue:11
font_color: 0000ff
12 navy:13
font_color: 000080

1. role: ルール設定
2. red: 文字の書式設定(red)
3. font_color: ff0000 文字の色"赤"4. yellow: 文字の書式設定(yellow)
5. font_color: ffff00 文字の色"黄"6. green: 文字の書式設定(green)
7. font_color: 008000 文字の色"緑"
8. aqua: 文字の書式設定(aqua)
9. font_color: 00ffff 文字の色"水色"
10. blue: 文字の書式設定(blue)
11. font_color: 0000ff 文字の色"青"12. navy: 文字の書式設定(navy)
13. font_color: 000080 文字の色"紺"• [green]*文字の色を指定* のように、 文字の色を指定 できます。

10.2.1. 変更後の文書イメージ
表紙の文字サイズと配置、見出しの大きさを変更し、全体をゴシック系MigMixフォントに設定したことで、 硬い印象になります。 テーマファイル変更後の文書イメージは、以下のようになります。

59

10.2. スタイルファイル変更

AsciiDoc文書作成入門

図 55. 表紙

図 56. 目次

図 57. 本文60

10. 仕様書作成等に向いたスタイル

10.2. スタイルファイル変更

10.2.2. 変更後のテーマファイル
リスト 43. 変更後のテーマファイル(全体、example-08-theme.yml)
1 extends: default-with-font-fallbacks
2 font:3 catalog:
4merge: true5
# MigMix 2P
6MigMix 2P:
7normal: migmix-2p-regular.ttf
8bold: migmix-2p-bold.ttf
9italic: migmix-2p-regular.ttf
10bold_italic: migmix-2p-bold.ttf
11 fallbacks: [MigMix 2P, M+ 1p Fallback, Noto Emoji]
12 page:
13 margin: [0.9in, 0.9in, 0.9in, 0.9in]
14 base:15 align: left
16 font_color: 000000
17 font_family: MigMix 2P
18 line_height_length: 15.5
19 line_height: $base_line_height_length / $base_font_size
20 role:21 red:22
font_color: ff0000
23 yellow:
24
font_color: ffff00
25 green:26
font_color: 008000
27 aqua:28
font_color: 00ffff
29 blue:30
font_color: 0000ff
31 navy:32
font_color: 000080
33 code:34 font-size: $base_font_size * 0.9
35 title_page:36 align: center
37 title:
38
top: 25%39
font_size: 20
40
font_style: bold
41
font_color: 000000
42
line_heght: 2.0
43 subtitle:44
font_size: 18
45
font_style: bold
46
font_color: 000000
47
line_heght: 2.0
48
margin_top: 1.2cm
49 authors:50
font_color: 000000
51
margin_top: 12.5cm
52 revision:

61

AsciiDoc文書作成入門

53
font_color: 000000
54
margin_top: -2cm
55 caption:
56 align: center
57 heading:
58 chapter:59
break-before: auto
60 font_family: $base_font_family
61 font_style: bold
62 font_color: 000000
63 h1_font_size: floor($base_font_size * 1.4)
64 h2_font_size: floor($base_font_size * 1.2)
65 h3_font_size: round($base_font_size * 1.1)
66 h4_font_size: $base_font_size
67 h5_font_size: $base_font_size
68 h6_font_size: $base_font_size
69 table:
70 head:71
font_color: $base_font_color
72
background_color: [185,174,166]
73 foot:74
background_color: [185,174,166]
75 cell_padding: [3, 3, 3, 3]
76 header:
77 border-color: #aaaaaa
78 border-style: double
79 border-width: 0.25
80 height: $base-line-height-length * 2.8
81 vertical-align: bottom
82 padding: [$base-line-height-length / 5, 3, 5, 3]
83 recto:
left:
84
85
content: '{chapter-title}'
86
right:
87
content: '{section-or-chapter-title}'
88 verso:
89
left:
90
content: '{document-title}'right:
91
92
content: '{section-or-chapter-title}'

10.2. スタイルファイル変更# <-- 右見開きページ# <-- チャプタータイトル# <-- セクションタイトル# <-- 左見開きページ# <-- ドキュメントタイトル# <-- セクションタイトル

8.5.4, “基本フォントにゴシック系(IBMPlexSansJP)を指定”で紹介したフォントを

使うことも可能です。
IBM Plex Sans JP フォントであれば、文字の高さがデフォルト(Noto Serif)と同じなので、 line_height の指定が不要です。

10.2.3. 明朝系フォントに変更
他の文書とフォントを合わせたい場合など、明朝系フォントを使うこともできます。
フォントと、テーマファイルの一部を変更するだけで、本文を変更することなく文書全体のフォントを変更することができます。

62

10. 仕様書作成等に向いたスタイル

10.2. スタイルファイル変更• テーマファイルの変更(フォントカタログと基本フォント)◦ テーマファイルの差分(diff)は、以下のとおりです。
リスト 44. テーマファイルの変更箇所% diff -u example-08-theme.yml example-08-02-theme.yml--- example-08-theme.yml
2021-07-09 16:48:37.000000000 +0900+++ example-08-02-theme.yml 2021-07-09 16:48:46.000000000 +0900@@ -2,19 +2,19 @@font:
catalog:
merge: true
# MigMix 2P
MigMix 2P:
normal: migmix-2p-regular.ttf
bold: migmix-2p-bold.ttf
italic: migmix-2p-regular.ttf
bold_italic: migmix-2p-bold.ttf- fallbacks: [MigMix 2P, M+ 1p Fallback, Noto Emoji]+# ShipporiMinchoB1+
ShipporiMinchoB1:+
normal: ShipporiMinchoB1-Regular.ttf+
bold: ShipporiMinchoB1-ExtraBold.ttf+
italic: ShipporiMinchoB1-Regular.ttf+
bold_italic: ShipporiMinchoB1-ExtraBold.ttf+ fallbacks: [ShipporiMinchoB1, M+ 1p Fallback, Noto Emoji]
page:
margin: [0.9in, 0.9in, 0.9in, 0.9in]
base:align: left
font_color: 000000- font_family: MigMix 2P+ font_family: ShipporiMinchoB1
line_height_length: 15.5
line_height: $base_line_height_length / $base_font_sizerole:

1. フォントカタログ(font_catalog)を変更します。
2. 基本フォント(base_font_family)を変更します。
明朝系フォントを使うと、印象が変わります。文書の使い方、好みにより使い分けてください。

63

10.2. スタイルファイル変更

AsciiDoc文書作成入門

図 58. 表紙

図 59. 目次

図 60. 本文

64

11. テーマファイルのテンプレート化

11. テーマファイルのテンプレート化

11. テーマファイルのテンプレート化
テーマファイルを目的別に作成し、テンプレートとして利用することで、書式が揃った文書を作成することができます。
これまでに作成したテーマファイルを整理し、共通のアトリビュートをメインとなる文書に記述してテンプレートとします。
1. ディレクトリ構成
リスト 45. ファイル、ディレクトリ構成.
├── doc-main.adoc├── doc-section01.adoc├── doc-section02.adoc├── fonts│ ├── IBMPlexSansJP-Bold.ttf│ ├── IBMPlexSansJP-Light.ttf│ ├── IBMPlexSansJP-Medium.ttf│ ├── IBMPlexSansJP-Regular.ttf│ ├── IBMPlexSansJP-SemiBold.ttf│ ├── ShipporiMinchoB1-Bold.ttf│ ├── ShipporiMinchoB1-ExtraBold.ttf│ ├── ShipporiMinchoB1-Medium.ttf│ ├── ShipporiMinchoB1-Regular.ttf│ ├── ShipporiMinchoB1-SemiBold.ttf│ ├── migmix-2p-bold.ttf│ └── migmix-2p-regular.ttf├── images│ ├── image-01.png│ └── image-02.png└── themes├── manuals-theme.yml├── manuals-IBMPlexSansJP-theme.yml├── specs-gothic-theme.yml└── specs-mincho-theme.yml

a. doc-main.adoc は、共通アトリビュートを設定したメイン文書
b. doc-section01.adoc は、第1章 本文
c. doc-section02.adoc は、第2章 本文
d. manuals-theme.yml は、マニュアル、説明書向けテーマ
e. manuals-IBMPlexSansJP-theme.yml は、マニュアル、説明書向けテーマ(IBM Plex Sans フォント使用)
f. specs-gothic-theme.yml は、仕様書向けゴシック系フォントのテーマ
g. specs-mincho-theme.yml は、仕様書向け明朝系フォントのテーマ
2. 必要なテーマとフォントを、文書作成ディレクトリにコピーして文書を作成します。

6511.1. サンプルファイルの内容

AsciiDoc文書作成入門

11.1. サンプルファイルの内容• 共通アトリビュートを設定した文書ファイル
リスト 46. メイン文書(doc-main.adoc)= ドキュメントタイトル: サブタイトル
著者, 組織名
Version {docdate}:doctype: book:scripts: cjk:pdf-theme: ./themes/manuals-theme.yml//:pdf-theme: ./themes/manuals-IBMPlexSansJP-theme.yml//:pdf-theme: ./themes/specs-gothic-theme.yml//:pdf-theme: ./themes/specs-mincho-theme.yml:pdf-fontsdir: ./fonts;GEM_FONTS_DIR:imagesdir: ./images:icons: font:source-highlighter: rouge:sectnumlevels: 4:sectnums::chapter-signifier::preface-title: まえがき
:appendix-caption: 付録:toc: left
:toclevels: 4:toc-title: 目次:figure-caption: 図:table-caption: 表:listing-caption: リスト:example-caption: 例:note-caption: 注記:tip-caption: ヒント:coution-caption: 注意:warning-caption: 警告:important-caption: 重要:version-label: Ver.
:last-update-label: 最終更新
include::doc-section01.adoc[]
include::doc-section02.adoc[]

リスト 47. 第1章本文(doc-section01.adoc)== セクション01=== サブセクション
本文・・・・・

66

11. テーマファイルのテンプレート化

11.1. サンプルファイルの内容

リスト 48. 第2章本文(doc-section02.adoc)== セクション02=== サブセクション
本文・・・・・• マニュアル、説明書向けテーマファイル
リスト 49. マニュアル向けテーマ(manuals-theme.yml)
extends: default-with-font-fallbacks
font:
catalog:
merge: true
# MigMix 2P
MigMix 2P:
normal: migmix-2p-regular.ttf
bold: migmix-2p-bold.ttf
italic: migmix-2p-regular.ttf
bold_italic: migmix-2p-bold.ttf
fallbacks: [MigMix 2P, M+ 1p Fallback, Noto Emoji]
page:
margin: [0.9in, 0.9in, 0.9in, 0.9in]
base:align: left
role:
red:
font_color: ff0000
yellow:
font_color: ffff00
green:
font_color: 008000
aqua:
font_color: 00ffff
blue:
font_color: 0000ff
navy:
font_color: 000080
code:
font-size: $base_font_size * 0.9
title_page:align: center
title:
top: 45%
authors:
margin_top: $base_font_size * 25
revesion:
margin_top: $base_font_size * 1.5
caption:align: center
heading:
chapter:break-before: auto

67

AsciiDoc文書作成入門

table:
head:
font_color: $base_font_color
background_color: [185,174,166]
foot:background_color: [185,174,166]
cell_padding: [3, 3, 3, 3]
header:border-color: #aaaaaa
border-style: double
border-width: 0.25
height: $base-line-height-length * 2.8
vertical-align: bottom
padding: [$base-line-height-length / 5, 3, 5, 3]
recto:
left:content: '{chapter-title}'right:
content: '{section-or-chapter-title}'
verso:
left:content: '{document-title}'right:
content: '{section-or-chapter-title}'

68

11.1. サンプルファイルの内容# <-- 右見開きページ# <-- チャプタータイトル# <-- セクションタイトル# <-- 左見開きページ# <-- ドキュメントタイトル# <-- セクションタイトル

11. テーマファイルのテンプレート化

11.1. サンプルファイルの内容• マニュアル、説明書向けテーマファイル(IBM Plex Sans フォント使用)
リスト 50. マニュアル向けテーマ(manuals-IBMPlexSansJP-theme.yml)
extends: default-with-font-fallbacks
font:
catalog:
merge: true
# MigMix 2P
MigMix 2P:
normal: migmix-2p-regular.ttf
bold: migmix-2p-bold.ttf
italic: migmix-2p-regular.ttf
bold_italic: migmix-2p-bold.ttf# IBMPlexSansJP
IBMPlexSansJP:
normal: IBMPlexSansJP-Regular.ttf
bold: IBMPlexSansJP-SemiBold.ttf
italic: IBMPlexSansJP-Regular.ttf
bold_italic: IBMPlexSansJP-SemiBold.ttf
fallbacks: [MigMix 2P, M+ 1p Fallback, Noto Emoji]
page:
margin: [0.9in, 0.9in, 0.9in, 0.9in]
base:align: left
font_family: IBMPlexSansJP
role:
red:
font_color: ff0000
yellow:
font_color: ffff00
green:
font_color: 008000
aqua:
font_color: 00ffff
blue:
font_color: 0000ff
navy:
font_color: 000080
code:
font-size: $base_font_size * 0.9
title_page:align: center
title:
top: 45%
authors:
margin_top: $base_font_size * 25
revesion:
margin_top: $base_font_size * 1.5
caption:align: center
heading:
chapter:break-before: auto
table:
head:

69

AsciiDoc文書作成入門

font_color: $base_font_color
background_color: [185,174,166]
foot:background_color: [185,174,166]
cell_padding: [3, 3, 3, 3]
header:border-color: #aaaaaa
border-style: double
border-width: 0.25
height: $base-line-height-length * 2.8
vertical-align: bottom
padding: [$base-line-height-length / 5, 3, 5, 3]
recto:
left:content: '{chapter-title}'right:
content: '{section-or-chapter-title}'
verso:
left:content: '{document-title}'right:
content: '{section-or-chapter-title}'

70

11.1. サンプルファイルの内容# <-- 右見開きページ# <-- チャプタータイトル# <-- セクションタイトル# <-- 左見開きページ# <-- ドキュメントタイトル# <-- セクションタイトル

11. テーマファイルのテンプレート化

11.1. サンプルファイルの内容• 仕様書向け、ゴシック系フォントを使ったテーマファイル
リスト 51. 仕様書向けゴシックテーマ(specs-gothic-theme.yml)
extends: default-with-font-fallbacks
font:
catalog:
merge: true
# MigMix 2P
MigMix 2P:
normal: migmix-2p-regular.ttf
bold: migmix-2p-bold.ttf
italic: migmix-2p-regular.ttf
bold_italic: migmix-2p-bold.ttf
fallbacks: [MigMix 2P, M+ 1p Fallback, Noto Emoji]
page:
margin: [0.9in, 0.9in, 0.9in, 0.9in]
base:align: left
font_color: 000000
font_family: MigMix 2P
line_height_length: 15.5
line_height: $base_line_height_length / $base_font_size
role:
red:
font_color: ff0000
yellow:
font_color: ffff00
green:
font_color: 008000
aqua:
font_color: 00ffff
blue:
font_color: 0000ff
navy:
font_color: 000080
code:
font-size: $base_font_size * 0.9
title_page:align: center
title:
top: 25%
font_size: 20
font_style: bold
font_color: 000000
line_heght: 2.0
subtitle:
font_size: 18
font_style: bold
font_color: 000000
line_heght: 2.0
margin_top: 1.2cm
authors:
font_color: 000000
margin_top: 12.5cm
revision:

71

AsciiDoc文書作成入門

font_color: 000000
margin_top: -2cm
caption:align: center
heading:
chapter:break-before: auto
font_family: $base_font_family
font_style: bold
font_color: 000000
h1_font_size: floor($base_font_size * 1.4)
h2_font_size: floor($base_font_size * 1.2)
h3_font_size: round($base_font_size * 1.1)
h4_font_size: $base_font_size
h5_font_size: $base_font_size
h6_font_size: $base_font_sizetable:
head:
font_color: $base_font_color
background_color: [185,174,166]
foot:background_color: [185,174,166]
cell_padding: [3, 3, 3, 3]
header:border-color: #aaaaaa
border-style: double
border-width: 0.25
height: $base-line-height-length * 2.8
vertical-align: bottom
padding: [$base-line-height-length / 5, 3, 5, 3]
recto:
left:content: '{chapter-title}'right:
content: '{section-or-chapter-title}'
verso:
left:content: '{document-title}'right:
content: '{section-or-chapter-title}'

72

11.1. サンプルファイルの内容# <-- 右見開きページ# <-- チャプタータイトル# <-- セクションタイトル# <-- 左見開きページ# <-- ドキュメントタイトル# <-- セクションタイトル

11. テーマファイルのテンプレート化

11.1. サンプルファイルの内容• 仕様書向け、明朝系フォントを使ったテーマファイル
リスト 52. 仕様書向け明朝テーマ(specs-mincho-theme.yml)
extends: default-with-font-fallbacks
font:
catalog:
merge: true
# ShipporiMinchoB1
ShipporiMinchoB1:
normal: ShipporiMinchoB1-Regular.ttf
bold: ShipporiMinchoB1-ExtraBold.ttf
italic: ShipporiMinchoB1-Regular.ttf
bold_italic: ShipporiMinchoB1-ExtraBold.ttf
fallbacks: [ShipporiMinchoB1, M+ 1p Fallback, Noto Emoji]
page:
margin: [0.9in, 0.9in, 0.9in, 0.9in]
base:align: left
font_color: 000000
font_family: ShipporiMinchoB1
line_height_length: 15.5
line_height: $base_line_height_length / $base_font_size
role:
red:
font_color: ff0000
yellow:
font_color: ffff00
green:
font_color: 008000
aqua:
font_color: 00ffff
blue:
font_color: 0000ff
navy:
font_color: 000080
code:
font-size: $base_font_size * 0.9
title_page:align: center
title:
top: 25%
font_size: 20
font_style: bold
font_color: 000000
line_heght: 2.0
subtitle:
font_size: 18
font_style: bold
font_color: 000000
line_heght: 2.0
margin_top: 1.2cm
authors:
font_color: 000000
margin_top: 12.5cm
revision:

73

AsciiDoc文書作成入門

font_color: 000000
margin_top: -2cm
caption:align: center
heading:
chapter:break-before: auto
font_family: $base_font_family
font_style: bold
font_color: 000000
h1_font_size: floor($base_font_size * 1.4)
h2_font_size: floor($base_font_size * 1.2)
h3_font_size: round($base_font_size * 1.1)
h4_font_size: $base_font_size
h5_font_size: $base_font_size
h6_font_size: $base_font_sizetable:
head:
font_color: $base_font_color
background_color: [185,174,166]
foot:background_color: [185,174,166]
cell_padding: [3, 3, 3, 3]
header:border-color: #aaaaaa
border-style: double
border-width: 0.25
height: $base-line-height-length * 2.8
vertical-align: bottom
padding: [$base-line-height-length / 5, 3, 5, 3]
recto:
left:content: '{chapter-title}'right:
content: '{section-or-chapter-title}'
verso:
left:content: '{document-title}'right:
content: '{section-or-chapter-title}'

74

11.1. サンプルファイルの内容# <-- 右見開きページ# <-- チャプタータイトル# <-- セクションタイトル# <-- 左見開きページ# <-- ドキュメントタイトル# <-- セクションタイトル

12. 作図ツール draw.io (VSCode拡張機能)

12.1. draw.ioとは

12. 作図ツール draw.io (VSCode拡張機能)
12.1. draw.ioとはdraw.ioは、フローチャート、システム構成図、UMLなどを作図するツールです。
VSCode(Visual Studio Code)の拡張機能としても提供されており、AsciiDocの文書作成中に作図も可能で、効率的に文書作成ができます。 さらに、PNG画像でありながら再編集可能な形式で保存できるため、図の修正が容易です。

draw.io は、Webアプリケーション(https://app.diagrams.net) として提供されており、Chrome拡張機能版やスタンドアローンで動作するアプリも提供されています。

VSSCodeの拡張機能をインストールするには、VSCodeのメニュー「表示」「拡張機能」で、draw.io を検索して 「Draw.io Integration」をインストールします。

図 61. Draw.io拡張機能のインストール

12.2. 再編集可能な形式 *.drawio.png と *.drawio.svg
ファイルの拡張子を .drawio.png とすると、draw.ioで編集可能でありながら、外部アプリケーショ
ンからはPNG画像として利用できます。 .drawio.svg とすることも可能です。(通常のPNG画像は、線や文字の修正はできない)

75

AsciiDoc文書作成入門

12.3. draw.ioの利用

PNG
Portable Network Ggraphics ビットマップ画像ファイルフォーマット



ビットマップ画像なので、線や文字などの修正はできない
SVG
Scalable Vector Graphics XMLベースの2次元ベクターイメージ画像形式
ベクターイメージなので、線や文字の修正が可能

作成したファイルは、PNG画像として取り扱うことができるので、作画してPNG画像としてエクスポートする必要はありません。 ただし、複数ページのページには対応しませんので、1ページごとにファイルを作成する必要があります。

図 62. Draw.io拡張機能の利用例

12.3. draw.ioの利用
1. VSCodeで、「新しいファイル」(空のファイル)を作成し、拡張子 .drawio.png(image01.drawio.png) のようにファイル名を指定して保存します。

図 63. drawioファイル作成76

12. 作図ツール draw.io (VSCode拡張機能)

12.3. draw.ioの利用

2. 保存したdrawioファイルを選択すると、VSCodeにdrawioの編集画面が表示されます。

図 64. drawio編集画面

3. 作画部品は、「一般」「その他」「高度な設定」の他、「 + その他の図形… 」から、クリップ
アートやネットワーク機器など目的に合わせた図形ライブラリをダウンロードすることができます。

図 65. drawio図形ライブラリ7713.1. アップデート

AsciiDoc文書作成入門

13. その他
13.1. アップデート
1. asciidoctorを含むインストールされているGemパッケージを更新するには、 gem update を使います。合わせて古いパッケージを削除するには、 gem cleanup を使います。

$ gem update$ gem cleanup①②① gem update で新しいバージョンがあればアップデートされる② gem cleanup で古いバージョンを削除する
2. RubyGems(gemコマンド)自体のアップデートは、 gem update --system とします。
(RubyGemsに脆弱性が発見された場合には、アップデートが必要です。)
3. Asciidoc関連のgemパッケージは、以下のようなものがあります。

# Asciidoctor本体とPDF作成
asciidoctor (2.0.15)
asciidoctor-pdf (1.6.0)# コードシンタックスハイライター
coderay (1.1.3)
rouge (3.26.0)

13.2. 文章校正(検査)ツール textlint
詳しい紹介はできませんが、文章を機械的にチェックすることができます。

13.2.1. textlintとはtextlintは、markdownなどテキスト形式で書かれた文章を、ルールにしたがってチェックするツールです。 「ですます調」と「である調」の混在や二重否定、冗長な表現、用語の不一致などを解析し、文章の問題点を検出します。
日本語に対応した多くのルールが公開されており、プラグインによりAsciiDocにも対応しています。
インストール
1. Node.jsが必要です。
a. Windowsの場合、https://nodejs.org/[公式サイト(https://nodejs.org/)]から、インストー
ラーをダウンロードします。
i. 14.16.1 LTS(長期サポート版)を推奨します。

78

13. その他

13.2. 文章校正(検査)ツール textlint

ii. コマンドプロンプトから、以下のコマンドでバージョンを確認(npmも同時にインストールされる)Your environment has been set up for using Node.js 14.16.1 (x64) and npm.
C:\Users\koshihikari>node -v
v14.16.1
C:\Users\koshihikari>npm --version
6.14.12b. Linux(Ubuntu)の場合、パッケージマネージャでNode.jsとnpmをインストール(バージョンはチョット古い)$ sudo apt install nodejs$ sudo apt install npm$ node -v
v10.19.0$ npm --version
6.14.4c. macOSの場合は、Homebrewでインストールする$ brew install nodebrew$ mkdir -p ~/.nodebrew/src$ nodebrew install-binary stable$ nodebrew ls
v14.16.1
current: none
$ nodebrew use v14.16.1
use v14.16.1$ echo 'export PATH=$HOME/.nodebrew/current/bin:$PATH' >> ~/.zshrc$ node -v
v14.16.1

13.2.2. VSCodeプラグイン
1. VSCode拡張機能でtextlintを検索して vscode-textlint をインストールします。

図 66. vscode-textlintをインストール

7913.2. 文章校正(検査)ツール textlint

AsciiDoc文書作成入門

2. textlintで文章をチェックすると、問題箇所がレポートされます。

図 67. textlint校正レポート

a. 文末が"。"で終わっていません。
b. ruby ⇒ Ruby (spellcheck-teck-word) テクニカルワードのスペルチェック。
c. 原則として、全文文字と半角文字の間にスペースを入れません。
d. 他にも、「〇〇を行うことができる」は、「〇〇できる」のような簡潔な表現や 一文の長さ、句読点の数、二重否定などがレポートされます。

13.2.3. textlintに関する情報
実際のインストールや使い方などは、こちらを参照してください。
• https://qiita.com/takasp/items/22f7f72b691fda30aea2• https://github.com/seikichi/textlint-plugin-asciidoctor• https://7ka.org/calibrate-use-textlint-and-vscode/• https://maku.blog/p/3veuap5/• https://dev.classmethod.jp/articles/textlint-chrome-addon/• https://www.npmjs.com/package/textlint-plugin-asciidoctor• https://textlint.github.io/blog/2021/05/24/textlint-12.html• https://efcl.info/2021/05/27/textlint-12-editor/• https://gigazine.net/news/20210625-textlint-12/80

付録 A: 参考情報

付録 A: 参考情報

付録 A: 参考情報
参考文献
▪ [1] Asciidoctor 文法クイックリファレンス(日本語訳), https://takumon.github.io/asciidocsyntax-quick-reference-japanese-translation/▪ [2] Asciidoctor User Manual, https://www.seinan-gu.ac.jp/~shito/asciidoctor/html_chunk/▪ [3] ドキュメント作成システム構築ガイド, 伊藤敬彦, 吉村孝広 著, 2016-03-25, ISBN 978-4-77418036-6, 株式会社技術評論社▪ [4] AsciiDoc + VSCodeでかっこいい文書作る, https://ai-gaminglife.hatenablog.com/entry/
2018/11/13/232608 (参照 2021-07-12)▪ [5] JavaScript Promiseの本 (AaciiDocで書かれた本), https://azu.github.io/promises-book/ (参照 2021-07-12)▪ [6] テクニカルライティングの将来 ー GitHub上のAsciidocで技術書Pro Gitを協働執筆, 2014
年12月15日, https://postd.cc/living-the-future-of-technical-writing/ (参照 2021-07-12)▪ [7] Pro Git, Scott Shacon, Ben Straub, 高木正弘(訳), Yusuke Sato(訳), 2nd Edition (2014),
https://git-scm.com/book/ja/v2 (参照 2021-03-15), https://progit-ja.github.io (Pro Git 日本語版
電子書籍公開サイト 参照 2021-03-15), License CC BY-NC-SA 3.0

改版履歴
Ver.

改版日

改版内容

1.0

2021-07-12

初版 (1st Edition)

1.1

2021-07-26

日本語フォントの利用 追記, ライセンス変更(CC-BY)

1.2

2022-05-25

chapter-signifier, codespan に変更 (chapter-label, literal 無効)

この文書について
AsciiDoc文書作成入門 (Asciidocによる文書作成環境の構築)
発行

農林水産研究情報総合センター
農林水産省 農林水産技術会議事務局 筑波産学連携支援センター 情報システム課

問い合わせ総合窓口
E-Mailrequest  affrc.go.jp

農林水産研究情報総合センター URL
URL

https://itcweb.cc.affrc.go.jp/
この文書は、 クリエイティブ・コモンズ 表示 4.0 国際 ライセンス の下に提供されています。

81