2015/03/08

HTMLを効率良く書くのに便利なMarkdown記法をLinuxで扱う

カテゴリ: , , , ,

この度のウェブログ移行の際に重宝しており、変換せずにメモの書き方として使うのもおすすめ。

  1. Markdownについて
    1. 一部の記法例
      1. 見出し
      2. 段落
      3. リスト
      4. 強調
      5. リンク
      6. Smartypants
    2. HTMLのコード
  2. プログラム内でHTMLに変換するためのライブラリ等
    1. C言語による実装
    2. スクリプト言語向けの言語バインディング
    3. スクリプト言語による実装のライブラリ
  3. 変換コマンド
  4. テキストエディタによる支援
  5. 静的サイトの作成支援系ツール

Markdownについて

MarkdownはHTML文書を効率良く記述するのに役立つ “記法” [1]で、それ自体も(書式情報を持たない)テキストとして意味を理解しやすい形をとっている。そのため、ツールを用いてHTMLに変換する以外にもメモ用途のテキストファイルとして記述する(変換はしない)使い方もある。

記法には同じ出力結果を得るのに幾つかの書き方があるため、以下で紹介している例には他の書き方で書くことができるものもある。

記法の一覧はDaring Fireball: Markdown Syntax Documentation(英語)にある。

Markdownには幾つかのツール依存の拡張や変換処理のフラグが存在し、ツール/ライブラリによってはHTMLへの変換の際に個別に有効/無効を指定してその挙動を変えることができる。また、ツール/Webサービスによっては独自の “拡張記法” も存在し、これを処理するかどうかも指定できる場合がある。

Markdown記法で記述された文書は “Markdown文書” と呼ばれることがあり、 “.md” もしくは “.markdown” という拡張子が付けられる場合がある。

一部の記法例

以下、Markdown記法と変換後のHTMLを並べて例を紹介するが、これらは “Sundown” と呼ばれる実装を用いた出力結果となる。

見出し

行頭に見出しレベルの数だけ “#” を付ける。HTMLと同様、6段階まである。下は3段階目までの例。

Markdown変換後のHTML
# h1の見出し

## h2の見出し

### h3の見出し

<h1>h1の見出し</h1>

<h2>h2の見出し</h2>

<h3>h3の見出し</h3>

段落

空行を段落の区切りとして自動的に段落が区切られる。

複数行で記述した段落は、Webブラウザでは改行部分がスペースになって続けて表示される。

Markdown変換後のHTML
テスト

これは
テストです。

これも
また
テストです。

<p>テスト</p>

<p>これは
テストです。</p>

<p>これも
また
テストです。</p>

リスト

順序無し(箇条書き)リストは “*” “+” “-” のいずれかと半角スペースの後ろに項目を1行1つずつ記述する。

順序付きリストは任意の数字[2]に “.” を付けたものと半角スペースの後ろに同様に記述する。

Markdown変換後のHTML
* ご飯
* 味噌汁
* 納豆

1. ふたを 1/4 程度はがす
2. スープの袋を取り出す
3. お湯を入れて3分33秒待つ
4. スープを入れて混ぜる

<ul>
<li>ご飯</li>
<li>味噌汁</li>
<li>納豆</li>
</ul>

<ol>
<li>ふたを 1/4 程度はがす</li>
<li>スープの袋を取り出す</li>
<li>お湯を入れて3分33秒待つ</li>
<li>スープを入れて混ぜる</li>
</ol>

複数のスペース(4つ単位)で字下げされた項目は入れ子になったリストの項目になる。

Markdown変換後のHTML
* ご飯
    * ふりかけご飯
    * 卵かけご飯
    * お茶漬け
* 餅
    * おしるこ
    * きなこ餅

1. 準備
    1. 玉ねぎをみじん切りにする
    2. パン粉を牛乳に浸す
    3. 油をひいたフライパンで玉ねぎを炒める
2. 固めるまで
    1. 挽肉,卵,玉ねぎ,パン粉をボウルに入れる
    2. 塩,こしょう,ナツメッグを混ぜて味を付ける
    3. よくこねて、空気も抜く
    4. 形を整え、真ん中をへこませてフライパンに並べる

<ul>
<li>ご飯

<ul>
<li>ふりかけご飯</li>
<li>卵かけご飯</li>
<li>お茶漬け</li>
</ul></li>
<li>餅

<ul>
<li>おしるこ</li>
<li>きなこ餅</li>
</ul></li>
</ul>

<ol>
<li>準備

<ol>
<li>玉ねぎをみじん切りにする</li>
<li>パン粉を牛乳に浸す</li>
<li>油をひいたフライパンで玉ねぎを炒める</li>
</ol></li>
<li>固めるまで

<ol>
<li>挽肉,卵,玉ねぎ,パン粉をボウルに入れる</li>
<li>塩,こしょう,ナツメッグを混ぜて味を付ける</li>
<li>よくこねて、空気も抜く</li>
<li>形を整え、真ん中をへこませてフライパンに並べる</li>
</ol></li>
</ol>

強調

強調したい部分の前後に1つもしくは2つの “*” もしくは “_” を付けると、その部分が強調される。

強調される部分は、記号を付けた数が1つの場合はem要素に、2つの場合はstrong要素になる。

Markdown変換後のHTML(p要素のタグは省略)
ここは*強調部分*です。

**もっと強調**します。

ここは<em>強調部分</em>です。

<strong>もっと強調</strong>します。

リンク

リンクは角括弧で囲まれたリンク文字列と丸括弧で囲まれたリンク先URLを続けて記述して表現する。

リンク先部分にはa要素のtitle属性となる文字列を付けることもできる。

Markdown変換後のHTML(p要素のタグは省略)
[W3C](http://www.w3.org/)

[X.org](http://x.org/ "エックスオルグ")

<a href="http://www.w3.org/">W3C</a>

<a href="http://x.org/" title="エックスオルグ">X.org</a>

Smartypants

一部の文字を特殊な文字に変換する拡張記法とこれを扱う拡張機能で、HTMLに変換してWebブラウザで見る場合に役立つ。

クォート文字の見た目を変えたり、 “.” “-” といった文字を連続で記述したときに別のひとまとめの形をした文字に変換したりする。前後に半角スペースを入れないとうまく動かない文字もある。

実装によってはこれ以外の “½” などの文字を変換することもできる(例:Sundownとその言語バインディング)。

下はSundownでの例。

Markdown変換後のHTML(p要素のタグは省略)
"クォート文字" に注目せよ！

(C) 2015 foobar(tm) Sundown用

うわっ...このサンプル、短すぎ...？

-- 終 --

--- 完 ---

&ldquo;クォート文字&rdquo; に注目せよ！

&copy; 2015 foobar&trade; Sundown用

うわっ&hellip;このサンプル、短すぎ&hellip;？

&ndash; 終 &ndash;

&mdash; 完 &mdash;

HTMLのコード

Markdown文書にはHTMLのコードをそのままの形で含めることができ、Markdownでの書き方よりもHTMLのコードを直接書くほうが書きやすい部分があればそのまま記述すればよい。

プログラム内でHTMLに変換するためのライブラリ等

Markdownを扱うためのソフトウェア(実装)は多数存在し、基本的な部分の処理についてはどれを選択しても同じように動作するが、拡張機能はそれぞれの実装によって異なる。

処理速度については、基本的に速いほうから

  1. C言語による実装 (最も高速)
  2. C言語によるライブラリの言語バインディング
  3. スクリプト言語による実装 (最も低速)

となる。

実装の一覧表はMarkdownImplementations - Markdown Community Group(英語)などにある。

(2015/3/10)以下の一覧表の項目を一部整理, 一部の名前を修正

C言語による実装

  • Discount
  • libsoldout(旧libupskirt)
    • Sundown(派生バージョン)
  • peg-markdown[3]

いずれもライブラリ(共有オブジェクトとヘッダファイル)としての形と変換コマンドとの組み合わせで提供されているが、Debian/Ubuntuの “libmarkdown2” パッケージは “Discount” のライブラリ部分を用いている。

スクリプト言語向けの言語バインディング

名前 (括弧内は Debian/Ubuntu のパッケージ)対象言語対象ライブラリ
Misaka (python-misaka, python3-misaka)PythonSundown
lua-discount (lua-discount, lua-discount-dev)LuaDiscount
Redcarpet (ruby-redcarpet)RubySundown
RDiscount (ruby-rdiscount)RubyDiscount
DR-SunDown (libdr-sundown-perl)PerlSundown

スクリプト言語による実装のライブラリ

名前 (括弧内は Debian/Ubuntu のパッケージ)対象/実装言語
Python-Markdown (python-markdown, python3-markdown)Python
markdown.lua (lua-markdown)Lua

変換コマンド

個別のコマンドの使い方については扱わない。

名前 (括弧内は Debian/Ubuntu のパッケージ)コマンド名実装言語
Discount (discount)markdown, mkd2html, makepage, themeC
Sundown (なし)sundown, smartypantsC
libsoldout (なし)mkd2html, mkd2latex, mkd2manC
peg-markdown (なし)markdownC
Misaka (python3-misaka)misakaC(バインディング), Python(コマンド)
Redcarpet (ruby-redcarpet)redcarpetC(バインディング), Ruby(コマンド)
RDiscount (ruby-rdiscount)rdiscountC(バインディング), Ruby(コマンド)
Markdown / Markdown.pl (markdown)markdownPerl

markdownやmkd2htmlといったコマンド名は複数の実装によって用いられており、使い方や動作はその実装によって異なる。

テキストエディタによる支援

  • Geanyの “Markdown” プラグイン(Debian/Ubuntuの “geany-plugin-markdown” パッケージ)をインストールして有効化すると、エディタ内でHTMLとしてのプレビューがMarkdown文書と同時に表示できたり、見出しが一覧表示されてその行へジャンプできたりする
  • ReText(Debian/Ubuntuの “retext” パッケージ)というテキストエディタでもHTMLとしてのプレビューが行える(“ライブプレビュー” と呼ばれる機能で同時表示ができる)
  • StackEditと呼ばれるサービスをWebブラウザで利用することでMarkdown文書の編集が行え、MarkdownとHTMLのスクロールが同期される点も便利
  • Mac OSやWindowsなどではエンジニアならトコトンこだわりたい！Markdownエディタ20選【Mac, iPhone他】という記事が参考になるかもしれない(対象読者はエンジニアなので注意)

個人的には、Bloggerへの投稿で使う上では既存のエディタやサービスを使うとやりにくい部分[4]があるため、 Python/Misaka/PyGI/GTK+ 3/WebKitを利用した自作のプレビュー/編集ツールを用いて記事の作成を行っている。[5]

静的サイトの作成支援系ツール

  • Blogofile
  • Jekyll
  • Nikola

といったツールは静的なサイトを効率良く構築する上で有用なものだが、これらはMarkdownがサポートされており、HTMLコンテンツの記述の生産性向上に役立っている。

[1]: 別の書き方をすれば “構造を持った文字情報を記述するための書き方の決まり” となる
[2]: HTMLに変換するだけの目的で記述する場合は全て “1” でも可
[3]: GLib 2に依存するため、Windowsでは同OS向けにビルドされたGLib 2が必要
[4]: 目次や脚注に関する追加処理など
[5]: ただし大部分の文字入力は以前と同様GNU Emacsで行っている