Linuxでは、pandocを使って40以上のファイルフォーマット間で変換することができます。また、Markdownを使ってドキュメントを書き、gitを使って保存し、サポートしている任意のフォーマットで公開することで、コードシステムとしての簡単なドキュメントを作成することができます。

ドキュメント変換、ドキュメントアズコード

Pandocがサポートしている様々なファイル形式のファイルがあれば、簡単に他のファイル形式に変換することができます。便利なツールです

しかし、pandocの本当の実力は、シンプルなdocs-as-codeシステムの基盤として使用したときに明らかになります。コードとしてのドキュメンテーションは、ソフトウェア開発の技術や原則のいくつかを採用し、特にソフトウェア開発プロジェクトのドキュメンテーションの記述に適用することを前提としています。しかし、あらゆる種類のドキュメントの開発に応用することができます。

ソフトウェア開発者は、自分の好きなエディタや統合開発環境（IDE）を使ってプログラムを書いています。入力したコードは、テキストファイルに保存される。これらは、プログラムのソースコードを含んでいます。

バージョン管理システム（VCS）（Gitが最も一般的）を使って、開発や改良に伴うソースコードの変更を記録する。つまり、プログラマーはソースコード・ファイルの全バージョンの履歴を完全に把握することができるのです。Gitは、ファイルをリポジトリに保存します。各開発者は、自分のコンピュータにローカルリポジトリを持ち、通常はクラウドでホストされている中央の共有リモートリポジトリを持つ。

プログラムの実用版を生成する準備ができたら、コンパイラを使ってソースコードを読み、バイナリの実行ファイルを生成する。

軽量でテキストベースのマークアップ言語を使ってドキュメントを書くことで、VCSを利用してオーサリングをコントロールすることができます。文書を配布したり出版する準備ができたら、pandocを使って、ウェブベース（HTML）、ワープロやタイプセット（LibreOffice、Microsoft word、TeX）、ポータブルドキュメントフォーマット（PDF）、電子ブック（ePub）など、必要なだけ異なるバージョンの文書を生成してください。

これらの操作は、バージョン管理された軽量なテキストファイルのセットから行うことができます。

pandocのインストール

Ubuntuにpandocをインストールするには、次のコマンドを使用します。

sudo apt-get install pandoc

Fedoraの場合、必要なコマンドは以下の通りです。

sudo dnf install pandoc

Manjaroの場合、入力する必要があります。

sudo pacman -Syu pandoc

の --version オプションでインストールされているバージョンを確認することができます。

pandoc --version

ファイルなしでpandocを使う

コマンドラインオプションなしでpandocを使うと、タイプされた入力も受け付けます。Ctrl+Dで入力が終わったことを示すだけで、pandocはドロッププライスフォーマットを入力することを想定し、HTML出力を生成します。

一例を見てみましょう。

pandoc

値下げを数行キー入力し、Ctrl+Dを押そうとしているところです。

このようにすると、pandocは同等のHTML出力を生成してくれます。

しかし、pandocを使って何か便利なことをするためには、ファイルを使う必要があります。

値下げ基準

Markdownは、特定の文字に特別な意味を持たせ、プレーンテキストエディターを使ってマークアップファイルを作成することができる軽量なマークアップ言語である。

マークアップは、視覚的に邪魔なタグがないため、簡単に読むことができます。割引価格文書のフォーマットは、それが表すフォーマットと同様です。基本的なことは以下の通りです。

• 斜体のテキストを強調する場合は、アスタリスクで囲んでください *We will emphasize this point*.
• テキストを太字にするには、アスタリスクを2つ使用します。** これは太字で表示されます**。
• タイトルは数字記号/ハッシュマーク(#)で表示されます。テキストとハッシュ値はスペースで区切られる。1つのハッシュをトップレベルの見出しに、2つのハッシュをセカンドレベルの見出しに、といった具合に使い分けます。
• 箇条書きにするには、リストの各行の先頭にアスタリスクを付け、テキストの前に**スペースを付けます。
• 番号付きリストを作成するには、各行を数字とピリオドで開始し、テキストの前に**スペースを入れます。
• ハイパーリンクを作成するには、[Link To How To Geek](https://www.tl80.cn/)のように、サイト名を角括弧([])で、URLを括弧(()で囲んでください。）
• 画像には、（！）をつけてください。[]).画像のオプションテキストを括弧内に入力します。次に、画像のパスを大括弧 [()"] で囲みます。例として、![ギーク] (HTG.png形式)。

次章では、より多くの例を紹介します。

関連記事：プライスダウンとは何か、どう使うのか？

ファイルを変換する

ファイル変換は非常に簡単で、pandocは通常、ファイル名からどのファイル形式を使用しているかを判断することができます。ここでは、ドロップファイルからHTMLファイルを生成します。o（出力）オプションは、pandocに作成したいファイルの名前を伝えます。

pandoc -o sample.html sample.md

サンプルのドロップファイルexample.mdには、以下のようなマークアップの短いセクションが含まれています。

example.htmlというファイルが作成され、それをダブルクリックすると、デフォルトのブラウザが開くようになっています。

では、LibreOffice Writer:で開くことのできる文書形式のテキスト文書を生成してみましょう。

pandoc -o sample.odt sample.md

ODT ファイルの内容は、HTML ファイルと同じです。

画像の代替テキストとなり、グラフィックのタイトルを自動生成するのにも使われるなど、粋な計らいがなされています。

ファイル形式を指定する

f (from) と -t (to) オプションは、pandoc にどのファイルフォーマットから変換するかを指示するために使用されます。関連する他のフォーマットとファイル拡張子を共有するファイル形式を使用している場合に便利です。例えば、TeXとLaTeXは共に拡張子が".TeX "である。

また、-s（スタンドアローン）オプションを使用すると、pandocは、完全で自己完結した、整形されたLaTeX文書に必要なすべてのLaTeXプリアンブルを生成するようになります。s (standalone)オプションがない場合、出力は他のLaTeX文書に **追加できる整形済みのLaTeXであり、したがって独立したLaTeX文書として適切にパースされない可能性があります。

以下のように入力します。

pandoc -f markdown -t latex -s -o sample.tex sample.md

例の.tex'をテキストエディタで開くと、生成されたlatexが表示されます。LaTeXエディタをお持ちの方は、TEXファイルを開くと、LaTeXの組版コマンドがどのように解釈されるかのプレビューを見ることができます。下の画像に合わせてウィンドウを縮小すると、モニターが窮屈に見えますが、実際には問題なく動作します。

TexmakerというLatexエディタを使います。Ubuntuでインストールするには、次のように入力します。

sudo apt-get install texmaker

Fedoraの場合、コマンドは

sudo dnf install texmaker

Manjaroでは、使用します。

sudo pacman -Syu texmaker

テンプレートを使ってファイルを変換する

Pandocの柔軟性については、すでにご理解いただけたかと思います。一度書けば、ほとんどどんなフォーマットでも出版できる。これは素晴らしい成果ですが、ファイルは少しバニラ色に見えますね。

テンプレートを使うと、pandocがドキュメントを生成するときに使うスタイルを指定することができます。例えば、CSS（Cascading Style Sheets）ファイルで定義されたスタイルを使用するように、--CSSオプションでpandocに指示することができます。

以下のテキストを含む小さなCSSファイルを作成しました。レベル見出しの上下の間隔を1つのスタイルで変更することになります。また、文字色が白に、背景色が青に変更されます。

h1 { color: #FFFFFF; background-color: #3C33FF; margin-top: 0px; margin-bottom: 1px; }

コマンドの全容は以下の通りです。なお、スタンドアロンオプション（-s）も使用しています。

pandoc -o sample.html -s --css sample.css sample.md

pandocは最小限のCSSファイルから1つのスタイルを使用し、それをレベル1のヘッダーファイルに適用します。

また、HTMLファイルを扱う際に、マークアップファイルの中にHTMLタグを含めることで、細かい設定を行うことも可能です。これは標準的なHTMLマークアップとして、生成されたHTMLファイルに渡されます。

ただし、この手法は、HTML出力のみを生成する場合に留めておく必要があります。複数のファイル形式を使用している場合、pandocはHTML以外のファイルのHTMLタグを無視し、それらのファイルにはテキストとして渡されます。

また、ODT文書生成時に使用するスタイルを指定することも可能です。白紙の libreofficewriter 文書を開き、ヘッダーとフォントスタイルを調整します。この例では、ヘッダーとフッターも追加しています。ドキュメントを "odt"-template.odtとして保存する。"

これで、--reference docオプションを使って、テンプレートとして使うことができる。

pandoc -o sample.odt --reference-doc=odt-template.odt sample.md

先ほどのODTの例と比較してみてください。この文書では、異なるフォントを使用し、見出しに色を付け、ヘッダーとフッターを含んでいます。ただし、全く同じ例の.md'ドロップファイルで構成されています。

参考資料のテンプレートは、文書作成の様々な段階を示すために使用することができます。例えば、「下書き」または「レビュー用」の透かしが入ったテンプレートがあるかもしれません。透かしのないテンプレートは、確定した文書に使用されます。

PDFの生成

デフォルトでは、pandocはLaTeXのPDFエンジンを使ってPDFファイルを生成しています。適切なLatexの依存関係を満たすための最も簡単な方法は、TexmakerのようなLatexエディタをインストールすることです。

テキサスもラテックスもそうですが、これはかなり大規模な設備です。ハードディスクの容量が限られている場合や、TeXやLaTeXを使うことがないことがわかっている場合は、ODTファイルを生成する方がよいでしょう。その後、libreofficewriterで開き、PDFとして保存することができます。

コードとしてのドキュメンテーション

Markdownを文章作成言語として使用することには、いくつかの利点があります。

• プレーンテキストファイルでの作業は高速です。同じサイズのワープロファイルよりも読み込みが速く、文書内の移動も高速です。gedit、Vim、Emacsなど多くのエディタでは、シンタックスハイライトやマークアップテキストが使用されています。
• VCS（Gitなど）に保存すれば、同じファイルの2つのバージョン間の違いを簡単に確認することができます。しかし、VCSはプレーンテキストを想定しているので、これはファイルがプレーンテキストの場合のみ実際に機能します。
• ベンチャーは、いつ、だれが、どのような変更を加えたかを記録することができます。また、ドキュメントそのものを一元的に管理することも可能です。GitHub、GitLab、BitBucketなど、多くのクラウドホスティング型Gitサービスは、その価格モデルに無料層を設けています。
• 様々な形式のドキュメントを生成することができます。簡単なシェルスクリプトをいくつか作成するだけで、CSSや参照ドキュメントからスタイルを抽出することができます。継続的インテグレーションおよび継続的デプロイメント（CI/CD）プラットフォームと統合されたVCSリポジトリにドキュメントを保存すれば、ソフトウェアをビルドするたびにこれらのドキュメントを自動的に生成することができます。

関連：GitHubとは何か、何に使うのか？

最終的な感想

Pandocには、ここで取り上げた以外にも様々なオプションや機能があります。ほとんどのファイル形式に対して、変換処理を調整し、微調整することが可能です。もっと詳しく知りたい方は、pandocの公式ウェブページにある素晴らしい例を見てください（とても詳しいです）。