ククログ

株式会社クリアコード > ククログ > Markdownで書いたテキストをPDFに変換して納品用ドキュメントを作成する方法

Markdownで書いたテキストをPDFに変換して納品用ドキュメントを作成する方法

色々なテキストを色々なフォーマットに変換できるPandocというツールがあります。 今回は、これを使ってMarkdownで書いたテキストをPDFに変換する方法を説明します1

環境はDebian GNU/Linuxのsidを想定しています2

必要なパッケージをインストールします。非常に多くのパッケージをインストールするので時間がかかります。

$ sudo apt-get install -y texlive-full pandoc ruby rake

次のコマンドを実行して動作確認します。

$ pandoc -o test.pdf --latex-engine=lualatex test.md

そのままでは日本語を含むテキストをPDFに変換できないのでtest.mdには日本語を含まないようにします。 これで日本語を含まないテキストをPDFに変換できることが確認できました。

日本語を含むテキストをPDFに変換するためにPandoc - TeX Wikiで紹介されている対策をします。

$ pandoc -o test-ja.pdf --latex-engine=lualatex test-ja.md

これで日本語を含むテキストをPDFに変換することができました。

(本記事執筆時点では、日本語を含むテキストの変換のためにはltjsarticle.clsに改変を加える対応が必要でしたが、2023年7月19日現在使用可能な新しめのLuaTeXでは、以上の手順で特に支障なく日本語を含むテキストをPDFに変換できます。)

これで任意のテキストをPDFに変換することができました。

Pandocで使えるMarkdownの記法についてはpandoc_markdown(5)やPandoc ユーザーズガイド 日本語版を参照してください。

箇条書きや表組み等、一通り必要なものは揃っています。

体裁を整える

生成したPDFを納品用ドキュメントとするためには目次を付けたり、日付を入れたりして、体裁を整える必要があります。 体裁を整えるためにはpandocコマンドにいくつかオプションを付ける必要があります。

以前、この方法でレポートを提出したプロジェクトでは以下のようなRakefileを使用しました。

require "rake/clean"

MD_FILES = FileList["*.md"]
PDF_FILES = MD_FILES.map{|file| file.ext(".pdf") }

task :default => :pdf

task :pdf => PDF_FILES

rule ".pdf" => ".md" do |t|
  sh "pandoc", "-f", "markdown+ignore_line_breaks", "-o", t.name,
     "--table-of-contents", "--toc-depth=3",
     "-V", "documentclass=myltjsarticle",
     "-V", "classoption=titlepage",
     "--latex-engine=lualatex", t.source
end

このRakefileでpandocコマンドに指定しているオプションは以下の通りです。

-f markdown+ignore_line_breaks

読み込むファイルのフォーマットを指定します。 ここでは入力がmarkdownであることと改行を無視するオプションを指定しています。

-o

出力するファイル名を指定します。 出力するファイルのフォーマットはファイル名から自動判別されます。 なお、出力するファイルのフォーマットを明示的に指定したいときは-tオプションなどを使います。

--table-of-contents

見出しから目次を生成します。

--toc-depth=3

目次に出力する見出しのレベルを指定します。

-V documentclass=myltjsarticle

LaTeX用のオプションを指定します。 このオプションでdocumentclassを明示します。

-V classoption=titlepage

LaTeX用のオプションを指定します。 このオプションを指定すると表紙を生成します。

--latex-engine=lualatex

PDF生成のために使用するLaTeXエンジンを指定します。

オプションに指定可能な値を調べる方法

-Vオプションに指定可能な値を調べるには次のコマンドを使用します。

$ pandoc -D latex | lv

このコマンドで出力されるソースを読んで、利用可能なオプションを見つけて使います。 利用可能なオプションを見つけるにはLaTexの知識が必要ですが、$if(...)$が使われているあたりを見ると、使われている値の名前がわかります。

メタ情報の書き方

以下のように、タイトル、著者、日付を表紙に入れることができます。

% Pandoc 調査報告書
% Taro Yamada <yamada@example.com>
% \today

# 概要

Pandocとは。。。

## 使い方

Pandocは以下のようにして使う。

# まとめ

以上よりPandocは。。。

YAMLフォーマットでメタデータを書く方法もあるようですが、手元では上手く動作させることができていません。

まとめ

Pandocを使ってMarkdownで書いたテキストをPDFに変換して納品用ドキュメントを生成する方法を紹介しました。

PDFの生成には少し時間がかかりますが、綺麗に出力できるので納品用のドキュメントをテキストエディタで書きたい人は検討してみてはいかがでしょうか。

  1. ククログはRD形式で書いているのですが、社内のテキストは少しずつにMarkdownに統一しています。

  2. Ubuntuでも同様の手順です。