Pandocをインストールしてマークダウン記法を自分好みに変換しよう！

前回の記事では、はてなブログでのマークダウン記法の書き方について説明しました。

今回はPandocというソフトウェアをWindows10にインストールします。

更にPandocのオプション設定によりマークダウン記法を自分好みに変換する方法について説明します。

Pandocのインストール方法（windows10）
1. Chocolateyによるインストール
Pandocの使い方
1. 変換可能なファイルの種類
Pandocのオプション指定
1. Pandoc拡張マークダウン
2. Option例
まとめ

f:id:hal7pi:20181209083109j:plain

Pandocのインストール方法（windows10）

Chocolateyを使うと簡単にPandocをインストールすることが可能です。

Chocolateyのインストール方法はこちらをご参照ください。

ameblo.jp

Chocolateyによるインストール

それではさっそくPandocをインストールしていきましょう。

まずPandocを探します。

choco search pandoc

2018年12月現在バージョン2.4が見つかりました。これをインストールします。

choco install pandoc -y

簡単です。あっという間にpandocのインストールが完了しました。

Pandocの使い方

Pandocの基本的な使い方は次のようになります。

pandoc -f 変換前フォーマット -t 変換後フォーマット ファイル名

fromの-f、toの-tだと思えば分かりやすいですよね。マークダウンファイルをHTMLファイルに変換する場合は次のようになります。

pandoc -f markdown -t html filename.md

変換可能なファイルの種類

Pandocの特徴は入力ファイル、出力ファイルに指定できる種類が非常に豊富なことです。

ものすごく多くの種類のファイル形式の相互変換が可能です。

どのようなものが可能かというと…

Markdown, reStructuredText, textile, HTML, DocBook, LaTeX, MediaWiki markup, TWiki markup, TikiWiki markup, Creole 1.0, Vimwiki markup, roff man, OPML, Emacs Org-Mode, Emacs Muse, txt2tags, Microsoft Word docx, LibreOffice ODT, EPUB, or Haddock markup

入力可能なファイルの種類だけでこんなにたくさんあります。

XHTML, HTML5, and HTML slide shows using Slidy, reveal.js, Slideous, S5, DZSlides, Microsoft Word docx, OpenOffice/LibreOffice ODT, OpenDocument XML, Microsoft PowerPoint, EPUB version 2 or 3, FictionBook2,DocBook version 4 or 5, TEI Simple, GNU TexInfo, Groff man, Groff ms, Haddock markup,JATS,InDesign ICML, OPML, LaTeX, ConTeXt, LaTeX Beamer slides,pdflatex, xelatex, lualatex, pdfroff, wkhtml2pdf, prince, or weasyprint,Markdown, CommonMark, GitHub-flavored Markdown, reStructuredText, AsciiDoc, Emacs Org-Mode, Emacs Muse, Textile, txt2tags, MediaWiki markup, DokuWiki markup, TikiWiki markup, TWiki markup, Vimwiki markup, ZimWiki markup,lua

これを以上のファイルに変換して出力することが可能です。

詳しくはこちらの公式ドキュメント（英文）をご参照ください。

Pandoc - Pandoc User’s Guide

Pandocのオプション指定

Pandocには非常にたくさんのオプションがあります。

順次解説していきます。

Pandoc拡張マークダウン

Pandocで扱うデフォルトのマークダウンはJohn GruberのオリジナルMarkdown記法を大きく拡張したものになっています。

Pandocではこの他のMarkdown記法も扱うことができます。

markdown_phpextra (PHP Markdown Extra)
markdown_github (deprecated GitHub-Flavored Markdown)
markdown_mmd (MultiMarkdown)
markdown_strict (Markdown.pl)
gfm (GitHub-Flavored Markdown)

はるなぴはこの中でmarkdown_githubを使っています。

この場合Pandocのコマンドは

pandoc -f markdown_github -t html filename.md

となります。

Option例

Pandocのオプションは非常にたくさんあります。

なのでここでは、はるなぴが使っているOptionの例をもとに説明します。

pandoc --toc --data-dir=C:\\Users\\Username\\Documents\\Pandoc --template=default --no-highlight -f markdown_github-fenced_code_blocks-fenced_code_attributes+backtick_code_blocks-autolink_bare_uris+strikeout+auto_identifiers-ascii_identifiers-hard_line_breaks+raw_html+emoji+yaml_metadata_block+raw_tex+tex_math_single_backslash -t html -s -c C:\\Users\\Username\\Documents\\Pandoc\\style.css filename.md

ええ、随分とたくさん指定してますよね。

ではひとつずつ説明していきます。

Markdown Option

まずマークダウン記法のオプションからいきます。

markdown_github-fenced_code_blocks-fenced_code_attributes+backtick_code_blocks-autolink_bare_uris+strikeout+auto_identifiers-ascii_identifiers-hard_line_breaks+raw_html+emoji+yaml_metadata_block+raw_tex+tex_math_single_backslash

最初の

markdown_github

は先ほど説明しました。マークダウン記法にmarkdown_githubを使うという指定ですね。

次の-（ハイフン）以降がオプション指定になります。

コードブロック

-fenced_code_blocks

ハイフン（マイナス記号）で接続したオプションは、そのオプション指定を適用しないようにするものです。一方でプラス（＋）記号で接続したオプションは採用することを意味します。

なので、この指定はfenced_code_blocksを適用しないようにするオプション指定になります。

fenced_code_blocksは、～（チルダ）記号の連打（最低3連打）でコードを囲むことによりコードブロックとして表示するオプションです。

+backtick_code_blocks

こちらのオプション指定によりチルダ記号（～）ではなく、バックティック（`）の3連打にてコードブロックを表示させます。

はるなぴがこのように指定しているのは他のマークダウン記法との整合を取るためです。

シンタックスハイライト

-fenced_code_attributes

Pandocのシンタックスハイライトが気に入らないのでシンタックスハイライトを使用しません。なのでハイフン（-）で接続指定します。

この他に--no-highlightの指定も行う必要があります。

自動リンク

自動リンク機能は本当は便利なものです。

URLを書けば自動的にそこをリンクに変換してくれます。

しかし文章中に書いたURLが意図せずしてリンクになってしまうということを避けるためこれを抑制します。

リンクを張りたい場合は明示的に張ることにします。

-autolink_bare_uris

ハイフンで接続することにより自動リンクが抑制されます。

打消し

はてなブログのツールボックスで打消しを行うとsタグが使用されます。

delタグを使用したいのとマークダウン記法で打消しを行いたいのでstrikeout指定をオンにします。

+strikeout

改行

マークダウン記法で改行を行う時は行末に2つの半角スペースを挿入します。

これが面倒な場合にはハードラインブレークを導入して、改行がそのままbrタグ の挿入（強制改行）になるようにします。

-hard_line_breaks

ここではハードラインブレークは採用しません。brタグは使いたくないのです。

強制改行は行わず、段落で表示するベースでいきます。

生HTML

HTMLはそのまま何も加工せずに変換されるよう指定します。

+raw_html

絵文字

めったに使わないと思いますが念のため絵文字を使えるように指定します。

+emoji

YAMLメタデータ

YAMLメタデータブロックを使えるようにします。

+yaml_metadata_block

YAMLメタデータとは次のようなメタデータです。YAML形式で書かれています。

---
date: 2018-11-25
title: Pandocをインストールしてマークダウン記法を自分好みに変換しよう！
draft: false
---

通常は文書の冒頭に置きます。静的サイトジェネレータではフロントマターと呼んでいるものです。

templateの使い方

YAMLメタデータはtemplateと組み合わせて使います。上の例ですとdateやtitleに記述した内容をtemplateの中の変数として使用することができます。

-s

standaloneオプションでheaderやfooterを含むtemplateを扱えるようにします。

--template=default

この指定でdefault.htmlというファイルに記載されたtemplateに従います。

ファイルの場所は

--data-dir=C:\\Users\\Username\\Documents\\Pandoc

にて指定します。ここで指定したディレクトリのサブディレクトリ＝templateの中のdefault.htmlがtemplateになるという仕組みです。

template例を紹介します。

<!DOCTYPE html>
<html lang="ja">
<head>
<meta charset="utf-8" />
<meta name="generator" content="pandoc" />
<meta name="viewport" content="width=device-width, initial-scale=1.0, user-scalable=yes" />
<title>$if(title-prefix)$$title-prefix$ – $endif$$pagetitle$</title>
$if(highlighting-css)$
<style type="text/css">
$highlighting-css$
</style>
$endif$ $for(css)$
<link rel="stylesheet" href="$css$"> $endfor$ $if(math)$ $math$ $endif$
</head>
<body>
<h1 class="title">$title$</h1>
$if(toc)$
<div class="$idprefix$toc">
$table-of-contents$
</div>
$endif$ $body$
</body>
</html>

TeX

今のところTeXを書く予定はありませんが念のため指定しておきます。

+raw_tex+tex_math_single_backslash

数式を書く場合はMathjaxを導入することになるのではないかと考えています。

CSS指定

CSSファイルへのリンクを指定することも可能です。

-c C:\\Users\\Username\\Documents\\Pandoc\\style.css filename

これでHTMLにstyle.cssへのリンクを埋め込むことができます。プレビューするときに本番環境と同じように表示することが可能になります。

まとめ

Pandocをインストールして使用することで自分好みのマークダウン記法で記事を書くことが可能になります。

カスタマイズしたマークダウン記法で記事を書き、それをPandocでお好みのHTMLに変換し、それをブログの「記事を書く」欄に貼り付ければOKです。

HTMLに変換するにあたっては秀丸のマクロにPandocを組み込んでおくと簡単に変換を行うことができます。説明は少し長くなるのでまた別の記事でご紹介したいと思います。

お楽しみに！

はるなぴログ

ブログ・WEBサイト作成技術研究