シナプスの技術部 システム開発課の蔵坪と申します。
昨年書いた下記の記事の続きになります。
今回は、Windows上のVisual Studio Codeで、AsciiDocからPDFを生成する手順を紹介したいと思います。
AsciiDocとは
- AsciiDocとは、メモ、ドキュメンテーション、記事、本、電子ブック、スライドショー、Webページ、マニュアルページ、ブログを書くためのテキスト文書フォーマットです。
試した環境
| 項目 | バージョン | 備考 |
|---|---|---|
| OS | Windows 10 Professional (1909) | |
| Visual Studio Code | 1.43.1 | |
| asciidoctor | 2.0.10 | gem list asciidoctorで確認 |
| asciidoctor-pdf | 1.5.3 | gem list asciidoctorで確認 |
AsciiDocからPDFの生成に必要なツール
- asciidoctor-pdf
- Asciidoctor PDFは、rubyのモジュールでAsciiDocのネイティブPDFコンバーターです。
環境構築
Windows上のVisual Studio Codeで、AsciiDocのプレビュー環境の構築の手順で環境構築していたら、追加の作業は不要です。
バージョンが古い場合は、gem updateでアップデートしてください。
Visual Studio Codeの設定
「ファイル > 基本設定 > 設定」をクリックし、検索ボックスに「asciidoctorpdf」を入力し、Asciidoctor_commandに下記を設定し、Use_asciidoctorpdfにチェックします。
asciidoctor-pdf -a scripts=cjk -a pdf-theme=default-with-fallback-font -r asciidoctor-diagram
PDFの生成
Visual Studio Codeで適当なフォルダを開き、Sample.adocファイルを新規作成します。
= AsciiDocサンプル
これはAsciiDocで記載されたドキュメントです。
== 見出し1
* aaaaaaaa
* bbbbbbbb
== ソースコード
[source, javascript]
----
Alert("AsciiDocサンプル");
----
== ユースケース
[plantuml]
----
@startuml
:user: --> (ユースケース1)
:user: -> (ユースケース2)
@enduml
----
表示 > コマンドパレット（もしくはCtrl+Shift+P）をクリックします。
「AsciiDoc」と入力し「AsciidocDoc: Export document as PDF」をクリックします。
PDFが正常に保存されたら、画面の右下にポップアップウィンドが表示されますので、Openをクリックして、PDFの内容を確認します。
上手く保存されれば、下記のPDFと同じ内容になるはずです。
PDFに表紙と目次をつける
AsciiDocの先頭に、下記を入れます。
:toc: :sectnums: :toclevels: 5 :toc-title: 目次 :author: 株式会社シナプス :revdate: 2019/08/23 :revnumber: 0.1 :lang: ja :doctype: book :chapter-label:
表示 > コマンドパレット（CTRL+SHIFT+P）から、「AsciidocDoc: Export document as PDF」をクリックしPDFを生成します。
上手く保存されれば、下記のPDFと同じ内容になるはずです。
パラメータは色々あります。上記で設定したパラメータの意味を知りたい場合は、下記の2つのサイトをご確認ください。AsciidoctorとAsciidoctor-PDFの属性のマニュアルになります。
独自テーマを作る
出力されるPDFのレイアウトは、テーマファイルで変更が可能です。
独自のテーマファイルを作成してみます。テーマの保存フォルダを開き、下記の内容でoriginal-theme.ymlを新規に作成します。
extends: default-with-fallback-font title_page: align: center
テーマファイルの保存ファイルは、rubyとasciidoctor-pdfのバージョンで場所が変更になりますのでご注意ください。2020/3/22にゼロから環境構築した場合は下記のパスになりました。
C:\tools\ruby27\lib\ruby\gems\2.7.0\gems\asciidoctor-pdf-1.5.3\data\themes
Asciidoctor_commandを下記に変更します。
asciidoctor-pdf -a scripts=cjk -a pdf-theme=original -r asciidoctor-diagram
表示 > コマンドパレット（Ctrl+Shift+P）から、「AsciidocDoc: Export document as PDF」をクリックしPDFを生成します。
生成されたPDFの内容を確認すると、前回はタイトルは、右寄せになっておりしたが、独自テーマにより真ん中寄せに変更されております。
今回は、タイトルの文字位置の変更だけでしたが、テーマを変更することでフォントを変更したり、背景画像を設定したりと様々な拡張が可能です。default-theme.ymlファイルを参考に、オリジナルのデザインを作成できます。
PDFのページサイズをA4横向きにする
デフォルトで生成されるPDFはA4縦向きになりますが、こちらを横向きにします。
AsciiDocの先頭に、下記を入れます。新規にpdf-page-sizeの属性を追加してあります。こちらを変更することで自由に用紙サイズを変更することができます。
:toc: :sectnums: :toclevels: 5 :toc-title: 目次 :author: 株式会社シナプス :revdate: 2019/08/23 :revnumber: 0.1 :lang: ja :doctype: book :chapter-label: :pdf-page-size: [11.69in, 8.25in]
生成されたPDFの内容を確認すると、ページサイズがA4横向きになったことを確認です。
さいごに
AsciiDocは、主にシステム向けの仕様書等で利用しておりましたが、最近、ちょっとした社内向けの打ち合わせ資料もAsciiDocで作って、PDFをプロジェクタで確認する機会も多くなりました。この記事を見た方で興味があれば、是非使ってみてください。
