asciidoctor-pdfによるPDF出力(導入)

 19th July 2022 at 3:32pm

AsciiDoc形式の文書ファイルは、Rubyの「asciidoctor」を利用してHTMLに変換することができます。

Asciidoctorは 高速な テキストプロセッサで AsciiDoc をHTML 5, DocBook 5や他のフォーマットに変換するツールチェインを配布しています. AsciidoctorはRubyで書かれており, RubyGemとしてパッケージされ, RubyGems.org で配布されています. gemはいくつかのLinuxディストリビューション, Fedora, Debian, Ubuntuにも含まれています. Asciidoctorはオープンソース hosted on GitHub で the MIT licenceのもとに配布されます.
asciidoctor/README-jp.adoc より

また、「asciidoctor-pdf」を利用してPDFに変換することができます。「asciidoctor-pdf」は、前述の「asciidoctor」とPDFを生成する「prawn」を使ってPDFに変換します。

「asciidoctor-pdf」の導入方法を以下に説明します。

Rubyとライブラリのインストール

ここでは、Windows10 64bit のOSで説明します。以下は2022年7月にうまくいった方法です。Rubyをインストールしますが、Ruby自体を使うことはあまりありませんので、Ruby初心者でも大丈夫です。

こちらからインストーラをダウンロードします。ここでは最新の「Ruby 3.1.2-1(x64)」をダウンロードし、インストールしました。(+Devkitじゃない方)

インストールの最後に「MSYS2 and MINGW development toolchain」は入れませんでした。

スタート ⇒ Ruby 3.1.2-1-x64-msvcrt ⇒ Start Command Prompt with Ruby を起動します。

まず、RubyGemsを最新にします。

Rubyにおけるライブラリは、gemという形式で公開されています。RubyGemsは、ライブラリの作成や公開、インストールを助けるシステムです。

Proxyを通して実行したい場合は、以下のようにset http_proxy・・・を行ってから実行してください。必要の無い場合は省略してください。

set http_proxy=http://プロキシのアドレス:ポート番号
set https_proxy=http://プロキシのアドレス:ポート番号
gem update --system
gem -v

次に、gem専用のパッケージ管理システム Bundlerを更新します。

Bundlerは、依存関係のあるライブラリもまとめてインストールしてくれるライブラリです。最近のバージョンでは標準で入っているようです。

gem update bundler
bundle -v

Bundlerで使用する「Gemfile」を生成します。

bundle init

C:/Users/ユーザー名/ に「Gemfile」ファイルが作成されたはずです。以下のように編集します。

# frozen_string_literal: true

source "https://rubygems.org"

git_source(:github) {|repo_name| "https://github.com/#{repo_name}" }

gem 'asciidoctor'
gem 'asciidoctor-pdf'
gem 'concurrent-ruby'
gem 'asciidoctor-rouge'

インストールを実行します。

bundle install

これでOKです。

PDFの出力方法

「Start Command Prompt with Ruby」を再起動します。「Untitled-1.adoc」というAsciiDoc形式のファイルを用意します。

「Untitled-1.adoc」の内容。

= Introduction to AsciiDoc
Doc Writer <doc@example.com>

A preface about https://asciidoc.org[AsciiDoc].

== First Section

* item 1
* item 2

[source,ruby]
puts "Hello, World!"

DOSプロンプトを開き、以下のコマンドを実行するとPDFが作成されます。

cd /d [Untitled-1.adocのあるディレクトリ]
asciidoctor-pdf -a scripts=cjk Untitled-1.adoc

日本語を含む文章の場合、-a scripts=cjkというオプションを付けます。(asciidoctor-pdf v1.6以上)

日本語含む文書の場合、-r asciidoctor-pdf-cjkというオプションを付けるのが良いようです。

また、「asciidoctor-pdf-linewrap-ja」というライブラリもあります。こちらにその記事があります。使いたい場合は、「Gemfile」にgem "asciidoctor-pdf-linewrap-ja"を追加して、bundle installしてください。

出力されたPDFの内容。(ちなみに=の1個は、表紙となります。)

今回は、コマンドを多用しましたが、「Visual Studio CodeからPDFを出力する」のような工夫で、ほとんどRubyを意識せずに使うことができるようになります。

注意点

asciidoctor: WARNING: gem '★★★' is not installed. This gem is recommended when registering custom converters.

と表示された場合は、「Gemfile」にgem "★★★"を追記して再度、bundle install してください。


HomeへAsciiDocの記事Topへ