asciidoctorによる形式変換
こんにちは東です。
今回はASCiiDocを別形式へと変換できる、asciidoctorの使い方に関して書いていこうと思います。
まず、asciidocとはRubyで作られたテキストプロセッサで、
ASCiiDocをdocbook、HTML等の形式に変換することができます。
asciidoctorのインストール ～ コマンドの実行
- asciidoctorのインストール
C:\>gem install asciidoctor Fetching: asciidoctor-1.5.7.1.gem (100%) Successfully installed asciidoctor-1.5.7.1 Parsing documentation for asciidoctor-1.5.7.1 Installing ri documentation for asciidoctor-1.5.7.1 Done installing documentation for asciidoctor after 14 seconds 1 gem installed - adocファイルを以下のコマンドで変換する
. コマンドC:\work\asciidoc>asciidoctor sample.adoc -D html. 変換元ファイル
== asciidoctorの使い方 . 変換元のサンプルです .. 変換前と変換前の比較に使用します. 変換後ファイル
上記の出力結果をみるとわかると思いますが、-Dで出力先の指定をしています。
デフォルトでHTMLに変換されるので、出力されたファイルはsample.htmlとなります。
形式を指定して変換する場合は以下のように指定します。
- 形式を指定した場合
. コマンドC:\work\asciidoc>asciidoctor -b docbook sample.adoc. 変換後ファイル
今回は形式の指定はしましたが、出力先ディレクトリの指定は行っていないので、asciidoc直下に出力されました。
このように、asciidoctorを利用すればASCiiDocでドキュメントの管理をし、
用途に合わせて形式の変換を行い、提供するという形が取れます。
この他にもpdfへの変換を行えるasciidoctor-pdfがあります。
asciidoctor-pdfのインストール ～ コマンドの実行
. asciidoctor-pdfのインストール
C:\work\asciidoc>gem install --pre asciidoctor-pdf
C:\work\asciidoc>gem install asciidoctor-pdf-cjk
asciidoc-pdfのみだと日本語を含む文書の場合、改行がうまく処理されない為、
asciidoctor-pdf-cjkをインストールします。
先程のサンプルをPDFに変換してみます。
. コマンドの実行
C:\work\asciidoc>asciidoctor-pdf -r asciidoctor-pdf-cjk sample.adoc
. 実行結果
簡単な内容ですが、しっかりPDF出力されていますね。
ここで、以前GitBucketでincludeが処理されないと記事を書きましたが、
asciidoctor-pdfではどうでしょうか？
インクルードする内容は以下の通り
. sample.adoc
== asciidoctorの使い方
. 変換元のサンプルです
.. 変換前と変換後の比較に使用します
=== インクルードしてみる
include::details.adoc[]
. details.adoc
* adocファイルのインクルードを処理した場合は？
このように、インクルードを行っていたとしても、正常に処理され
PDFの出力が行われます。
. コマンドの実行
C:\work\asciidoc>asciidoctor-pdf -r asciidoctor-pdf-cjk sample.adoc
. 実行結果
includeも問題なくされていますね。
Styleの指定や、フォントの変更
asciidoctor-pdfでは、asciidoctor-pdf-1.5.0.alpha.16\data配下に、fonts、themesというフォルダが存在し、
themesにはスタイルのテンプレートが、fontsには各種フォントが用意されています。
asciidoctor-pdfでPDFに変換する際、テンプレートの内容を変更することで、見た目を変えることができます。
今回は、試しに背景色の変更を行います。
- themes、fontsの中身をコピーし、自身で用意したディレクトリに配置します。
今回は、asciidoc配下に「theme」「fonts」を用意しました。 -
default-theme.ymlの以下の個所を修正
page: background_color: e6e6fa #defaultはffffff
. コマンドの実行
pdf-styleは適用するyamlを指定
pdf-stylesdirはスタイルファイルの在処を指定
pdf-fontsdirはフォントの在処を指定
C:\work\asciidoc>asciidoctor-pdf -r asciidoctor-pdf-cjk -a pdf-style=default-theme.yml -a pdf-stylesdir=theme -a pdf-fontsdir=fonts sample.adoc
. 実行結果
無事、背景色が変更されました。
このように、見た目の変更も柔軟に設定でき、場合によっては重複するような記述を部品として作成し
変数とincludeを活用して記述量を少なくする等、活用の幅はとても多いと思います。
可読性などの兼ね合いでどこまでやるかにもよりますが。。。
次回は、
. スタイルをがっつりいじってみる
. Rakeタスクを作成して各種フォーマットへの変更を簡単にやる
この2点をやってみたいと思います。
元々Javaエンジニアからはじまり、気付けばJS(ES6)、AWS、Python3.6、OutsystemsPlatform、PHPと色々やってました。
得意技: Java、JS(ES6)、AWSの一部リソース
勉強中: AWSの各種リソースと、Python3.6
MarkDownからASCiiDocへ目覚めつつある今日この頃。
座右の銘は「一言芳恩」「華麗奔放」「不決断こそ最大の害悪である」です。
コメント