Linuxコマンドラインでpandocを使用してファイルを変換する方法

Linuxでpandocを使用して、40を超えるファイル形式間で変換できます。 また、Markdownで記述し、 gitに保存し、サポートされている任意の形式で公開することにより、単純なdocs-as-codeシステムを作成するために使用することもできます。

ドキュメント変換とDocs-as-Code

pandoc'sファイル形式のいずれかのドキュメントがある場合、それを他の形式に変換するのは簡単です。 これは便利なツールです。

しかし、 pandocの真の力は、単純なdocs-as-codeシステムの基礎として使用すると明らかになります。 docs-as-codeの前提は、ソフトウェア開発の手法と原則のいくつかを採用し、特にソフトウェア開発プロジェクトのドキュメントの作成にそれらを適用することです。 ただし、あらゆる種類のドキュメントの開発に適用できます。

ソフトウェア開発者は、お気に入りのエディターまたは統合開発環境（IDE）を使用してプログラムを作成します。 入力したコードはテキストファイルに保存されます。 これらには、プログラムのソースコードが含まれています。

彼らはバージョン管理システム、またはVCS（Gitが最も人気があります）を使用して、開発および拡張されたソースコードへの変更をキャプチャします。 これは、プログラマーがソースコードファイルのすべてのバージョンの完全な履歴を持っていることを意味します。 彼または彼女は、ファイルの以前のバージョンにすばやくアクセスできます。 Gitはファイルをリポジトリに保存します。 各開発者のコ​​ンピューターにはローカルリポジトリがあり、中央の共有リモートリポジトリは、多くの場合クラウドでホストされています。

プログラムの動作バージョンを作成する準備ができたら、コンパイラを使用してソースコードを読み取り、バイナリ実行可能ファイルを生成します。

軽量のテキストベースのマークアップ言語でドキュメントを作成することにより、VCSを使用して書き込みのバージョン管理を行うことができます。 ドキュメントを配布または公開する準備ができたら、 pandocを使用して、Webベース（HTML）、ワード処理、またはタイプセット（LibreOffice、Microsoft Word、TeX）など、必要な数の異なるバージョンのドキュメントを生成できます。 、ポータブルドキュメント形式（PDF）、電子書籍（ePub）など。

これらすべてを、バージョン管理された軽量のテキストファイルの1つのセットから実行できます。

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は、Markdown形式で入力することを想定しており、HTML出力を生成します。

例を見てみましょう：

 pandoc 

Markdownを数行入力し、Ctrl + Dを押しようとしています。

すぐに、 pandocは同等のHTML出力を生成します。

ただし、 pandocで役立つことを行うには、実際にファイルを使用する必要があります。

マークダウンの基本

マークダウンは軽量のマークアップ言語であり、特定の文字に特別な意味が与えられます。 プレーンテキストエディタを使用して、マークダウンファイルを作成できます。

テキストの邪魔になる視覚的に面倒なタグがないため、マークダウンは簡単に読み取ることができます。 Markdownドキュメントでのフォーマットは、それが表すフォーマットに似ています。 以下はいくつかの基本です：

• 斜体でテキストを強調するには、アスタリスクで囲みます。 *This will be emphasized*
• テキストを太字にするには、2つのアスタリスクを使用します。 **This will be in bold**
• 見出しは、番号記号/ハッシュマーク（ # ）で表されます。 テキストはスペースでハッシュから区切られます。 トップレベルの見出しに1つのハッシュを使用し、セカンドレベルに2つのハッシュを使用します。
• 箇条書きを作成するには、リストの各行をアスタリスクで開始し、テキストの前にスペースを挿入します。
• 番号付きリストを作成するには、各行を数字の後にピリオドで開始し、テキストの前にスペースを挿入します。
• ハイパーリンクを作成するには、サイト名を角かっこ（ [] ）で囲み、URLをかっこ[ () ]で囲みます。 [Link to How to Geek](https://www.howtogeek.com/) 。
• 画像を挿入するには、角かっこ（ ![] ）の直前に感嘆符を入力します。 画像の代替テキストを角かっこで囲んで入力します。 次に、画像へのパスを括弧[ () "]で囲みます。 次に例を示します： ![The Geek](HTG.png) 。

次のセクションでは、これらすべての例について詳しく説明します。

関連：マークダウンとは何ですか、そしてそれをどのように使用しますか？

ファイルの変換

ファイル変換は簡単です。 pandocは通常、ファイル名から使用しているファイル形式を特定できます。 ここでは、MarkdownファイルからHTMLファイルを生成します。 -o （出力）オプションは、作成するファイルの名前をpandocに通知します。

 pandoc -o sample.html sample.md 

サンプルのMarkdownファイルsample.mdには、下の画像に示すMarkdownの短いセクションが含まれています。

sample.htmlというファイルが作成されます。 ファイルをダブルクリックすると、デフォルトのブラウザでファイルが開きます。

それでは、LibreOfficeWriterで開くことができるOpenDocumentFormatテキストドキュメントを生成しましょう。

 pandoc -o sample.odt sample.md 

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

きちんとしたタッチは、画像の代替テキストであり、図のキャプションを自動的に生成するためにも使用されます。

ファイル形式の指定

-f （from）および-t （to）オプションは、変換元および変換先のファイル形式をpandocに指示するために使用されます。 これは、ファイル拡張子を他の関連する形式と共有するファイル形式で作業している場合に役立ちます。 たとえば、TeXとLaTeXはどちらも「.tex」拡張子を使用します。

また、 -s （スタンドアロン）オプションを使用しているため、 pandocは、ドキュメントが完全で自己完結型の整形式のLaTeXドキュメントであるために必要なすべてのLaTeXプリアンブルを生成します。 -s （スタンドアロン）オプションがない場合でも、出力は整形式のLaTeXであり、別のLaTeXドキュメントに挿入でき、スタンドアロンのLaTeXドキュメントとして適切に解析されません。

次のように入力します。

 pandoc-fマークダウン-tラテックス-s-o sample.tex sample.md 

「sample.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）ファイルで定義されたスタイルを--cssオプションで使用するようにpandocに指示できます。

以下のテキストを含む小さなCSSファイルを作成しました。 レベルヘッダーの上下の間隔を1スタイル変更します。 また、テキストの色を白に変更し、背景色を青の色合いに変更します。

 h1 {
  色：#FFFFFF;
  背景色：＃3C33FF;
  margin-top：0px;
  margin-bottom：1px;
}

完全なコマンドは以下のとおりです。スタンドアロンオプション（ -s ）も使用したことに注意してください。

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

pandocは、ミニマリストのCSSファイルの単一のスタイルを使用して、レベル1のヘッダーに適用します。

HTMLファイルを操作するときに利用できるもう1つの微調整オプションは、マークダウンファイルに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の例と比較してください。 このドキュメントは別のフォントを使用し、見出しに色が付いており、ヘッダーとフッターが含まれています。 ただし、まったく同じ「sample.md」マークダウンファイルから生成されました。

参照ドキュメントテンプレートを使用して、ドキュメントの作成のさまざまな段階を示すことができます。 たとえば、「ドラフト」または「レビュー用」の透かしが入ったテンプレートがあるとします。 透かしのないテンプレートは、完成したドキュメントに使用されます。

PDFの生成

デフォルトでは、 pandocはLaTeXPDFエンジンを使用してPDFファイルを生成します。 適切なLaTeX依存関係が満たされていることを確認する最も簡単な方法は、TexmakerなどのLaTeXエディターをインストールすることです。

ただし、これは非常に大きなインストールです。TexとLaTeXはどちらもかなり重いです。 ハードドライブの容量が限られている場合、またはTeXまたはLaTeXを使用しないことがわかっている場合は、ODTファイルを生成することをお勧めします。 次に、LibreOffice Writerで開いて、PDFとして保存できます。

Docs-as-Code

書き込み言語としてMarkdownを使用することには、次のようないくつかの利点があります。

• プレーンテキストファイルでの作業は高速です。同じサイズのワードプロセッサフ​​ァイルよりも読み込みが速く、ドキュメント内を移動する傾向もあります。 gedit 、 Vim 、 Emacsを含む多くのエディターは、マークダウンテキストで構文の強調表示を使用します。
• ドキュメントのすべてのバージョンのタイムラインがあります。ドキュメントをGitなどのVCSに保存すると、同じファイルの2つのバージョンの違いを簡単に確認できます。 ただし、これはファイルがプレーンテキストの場合にのみ実際に機能します。これは、VCSが機能することを期待しているためです。
• VCSは、誰がいつ変更を加えたかを記録できます。これは、大規模なプロジェクトで他のユーザーと頻繁に共同作業を行う場合に特に役立ちます。 また、ドキュメント自体の中央リポジトリも提供します。 GitHub、GitLab、BitBucketなどの多くのクラウドホスト型Gitサービスでは、料金モデルに無料枠があります。
• ドキュメントは複数の形式で生成できます。いくつかの簡単なシェルスクリプトを使用して、CSSおよび参照ドキュメントからスタイルを取り込むことができます。 継続的インテグレーションおよび継続的デプロイメント（CI / CD）プラットフォームと統合するVCSリポジトリにドキュメントを保存すると、ソフトウェアがビルドされるたびにドキュメントを自動的に生成できます。

関連： GitHubとは何ですか、また何に使用されますか？

最終的な考え

pandocには、ここで説明したものよりも多くのオプションと機能があります。 ほとんどのファイルタイプの変換プロセスは、微調整および微調整できます。 詳細については、公式の（そして非常に詳細な）pandocWebページの優れた例を確認してください。