開発者目線では，いちいちドキュメントをPDFやHTMLで記述するのは面倒なため，簡易的にMarkdownを用いることが多いです．
一方で，正式ドキュメントとしてはPDFやHTMLで公開するが一般的です．正式なドキュメントとしてMarkdownを公開するのはさすがに手抜きに思えてしまします．
そのような背景から，Markdownで記述したものをPDFやHTMLに自動的に変換するツールの需要が高まってきます．
この記事では，Pandocを用いてMarkdownからHTMLに変換する手順を記載します．
Pandocのインストール
Debian系
apt install pandoc
使い方
基本コマンド
pandoc <input.md> -o <output.html>
例題
サンプル(pandoc.1.md)をHTMLファイルに変換します．
pandoc pandoc.1.md -o output.html
output.html
<h1 id="name">NAME</h1>
<p>pandoc - general markup converter</p>
<h1 id="synopsis">SYNOPSIS</h1>
<p>pandoc [<em>options</em>] [<em>input-file</em>]…</p>
<h1 id="description">DESCRIPTION</h1>
<p>Pandoc converts files from one markup format to another. It can read markdown and (subsets of) reStructuredText, HTML, and LaTeX, and it can write plain text, markdown, reStructuredText, HTML, LaTeX, ConTeXt, Texinfo, groff man, MediaWiki markup, RTF, OpenDocument XML, ODT, DocBook XML, EPUB, and Slidy or S5 HTML slide shows.</p>
<p>If no <em>input-file</em> is specified, input is read from <em>stdin</em>. Otherwise, the <em>input-files</em> are concatenated (with a blank line between each) and used as input. Output goes to <em>stdout</em> by default (though output to <em>stdout</em> is disabled for the <code>odt</code> and <code>epub</code> output formats). For output to a file, use the <code>-o</code> option:</p>
<pre><code>pandoc -o output.html input.txt</code></pre>
<p>Instead of a file, an absolute URI may be given. In this case pandoc will fetch the content using HTTP:</p>
<pre><code>pandoc -f html -t markdown http://www.fsf.org</code></pre>
<p>The input and output formats may be specified using command-line options (see <strong>OPTIONS</strong>, below, for details). If these formats are not specified explicitly, Pandoc will attempt to determine them from the extensions of the input and output filenames. If input comes from <em>stdin</em> or from a file with an unknown extension, the input is assumed to be markdown. If no output filename is specified using the <code>-o</code> option, or if a filename is specified but its extension is unknown, the output will default to HTML. Thus, for example,</p>
<pre><code>pandoc -o chap1.tex chap1.txt</code></pre>
...
ブラウザで確認すると下記のような表示になります．
これで，マークダウン形式からHTML形式に変換できました．
ただ，このままでは不格好です．．．pandocはテンプレート機能を有しており，HTMLやCSSによって自分好みにカスタマイズすることができます．
自分好みのテンプレートを作成してもよいですが，この記事ではすでに作成されているテンプレートを利用させていただくことにします．
おすすめのテンプレート
easy pandoc templates
https://github.com/ryangrose/easy-pandoc-templates
使い方
使い方は，作者のGitHubに記載されていますが，念のためここでも記載しておきます．
・インストール
下記コマンドを実行することで，自動的にインストールされます．インストール先は~/.pandoc/templatesです．
curl 'https://raw.githubusercontent.com/ryangrose/easy-pandoc-templates/master/copy_templates.sh' | bash
・使い方
使い方は下記の通りです．--template=...でテンプレートファイルを指定するだけです．
pandoc <input.md> -o <output.html> --template=easy_template.html
テンプレートは次の5種類用意されています．（2023/02/27現在）
- bootstrap_menu.html
- clean_menu.html
- easy_template.html
- elegant_bootstrap_menu.html
- uikit.html
用意されているテンプレートを使用して，先ほどのMarkdownファイル（pandoc.1.md）をHTMLに変換してみます．
下記がそれぞれの結果になります．デフォルトと比較するとドキュメントらしくなったと思います．
bootstrap_menu.html
clean_menu.html
easy_template.html
elegant_bootstrap_menu.html
uikit.html
HTMLやCSSを作るのは結構面倒ですので，テンプレートとして公開して頂いている作者様には感謝申し上げます．
メタデータの付与
Pandocでは，タイトルや著者，日付などのメタデータを記述することができます．
以下のように.mdファイル冒頭に記述することで，メタデータが反映されます．
---
title: title
author: you
data: 20XX/XX/XX
---
日付に関しては，作成日をいちいち編集するのは面倒です．
コマンドラインオプションとして--metadata data="`date "+%Y/%m/%d"`"を与えることで自動的に日付を作成することが可能です．
pandoc <input.md> -o <output.html> --metadata data="`date "+%Y/%m/%d"`"
たまに忘れるコマンドライン
LaTeX対応
ドキュメント内にLaTeXによる数式がある場合は，--mathjaxを付けるとうまくいきます．
pandoc --mathjax -o
まとめ
この記事では，Pandocを用いてMarkdownからHTMLに変換する方法を示しました．
HTML形式はテンプレート機能を用いることでカスタマイズすることができます．今回は，こちらを利用させていただきましたが，自分好みのカスタマイズをするのもよいでしょう．
また，Pandocは「Markdown → HTML」以外にもさまざまなファイルフォーマットをサポートしていますの興味があれば公式サイトを眺めてみてください．
