前回の記事では、はてなブログでのマークダウン記法の書き方について説明しました。
今回はPandocというソフトウェアをWindows10にインストールします。
更にPandocのオプション設定によりマークダウン記法を自分好みに変換する方法について説明します。
Pandocのインストール方法(windows10)
Chocolateyを使うと簡単にPandocをインストールすることが可能です。
Chocolateyのインストール方法はこちらをご参照ください。
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には非常にたくさんのオプションがあります。
順次解説していきます。
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
目次
目次(TOC: Table Of Contents)を自動作成します。
まず--toc
指定が必要です。
+auto_identifiers
これで見出しを元に自動的にTOCを作成してくれるようになります。
-ascii_identifiers
更にこの指定をします。我々は日本語で見出しを書きますのでidがアスキー文字だけに制限されないようにします。これによりTOCのidに日本語が使用できSEO効果が上がります。
改行
マークダウン記法で改行を行う時は行末に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を組み込んでおくと簡単に変換を行うことができます。説明は少し長くなるのでまた別の記事でご紹介したいと思います。
お楽しみに!