シナプス技術者ブログ

シナプスの技術者公式ブログ。インターネットで、鹿児島の毎日を笑顔にします。

Windows上のVisual Studio Codeで、AsciiDocからPDF出力

シナプスの技術部 システム開発課の蔵坪と申します。

昨年書いた下記の記事の続きになります。

tech.synapse.jp

今回は、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にチェックします。 f:id:mkuratsubo:20200324154918p:plain

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)をクリックします。

f:id:mkuratsubo:20200324160142p:plain

「AsciiDoc」と入力し「AsciidocDoc: Export document as PDF」をクリックします。

f:id:mkuratsubo:20200324160244p:plain

PDFが正常に保存されたら、画面の右下にポップアップウィンドが表示されますので、Openをクリックして、PDFの内容を確認します。

f:id:mkuratsubo:20200324160404p:plain

上手く保存されれば、下記のPDFと同じ内容になるはずです。

f:id:mkuratsubo:20200324160603p:plain

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と同じ内容になるはずです。

f:id:mkuratsubo:20200324161955p:plain

パラメータは色々あります。上記で設定したパラメータの意味を知りたい場合は、下記の2つのサイトをご確認ください。AsciidoctorとAsciidoctor-PDFの属性のマニュアルになります。

www.seinan-gu.ac.jp

github.com

独自テーマを作る

出力されるPDFのレイアウトは、テーマファイルで変更が可能です。

独自のテーマファイルを作成してみます。テーマの保存フォルダを開き、下記の内容でoriginal-theme.ymlを新規に作成します。

extends: default-with-fallback-font
title_page:
    align: center

f:id:mkuratsubo:20200324170456p:plain

テーマファイルの保存ファイルは、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 

f:id:mkuratsubo:20200324174749p:plain

表示 > コマンドパレット(Ctrl+Shift+P)から、「AsciidocDoc: Export document as PDF」をクリックしPDFを生成します。

生成されたPDFの内容を確認すると、前回はタイトルは、右寄せになっておりしたが、独自テーマにより真ん中寄せに変更されております。

f:id:mkuratsubo:20200324175035p:plain

今回は、タイトルの文字位置の変更だけでしたが、テーマを変更することでフォントを変更したり、背景画像を設定したりと様々な拡張が可能です。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横向きになったことを確認です。

f:id:mkuratsubo:20200325132144p:plain

さいごに

AsciiDocは、主にシステム向けの仕様書等で利用しておりましたが、最近、ちょっとした社内向けの打ち合わせ資料もAsciiDocで作って、PDFをプロジェクタで確認する機会も多くなりました。この記事を見た方で興味があれば、是非使ってみてください。