Pandoc 用拡張 Markdown 記法の覚え書き

Pandoc って？

Pandoc はある形式で書かれた文書を、別の形式の文書に変換するツールです。
Pandoc User’s Guide では、Pandoc 用拡張 Markdown 記法が紹介されています。

各OS版のインストール方法は Pandoc の Installing ページで。

なぜ興味を持ったか

ファイルを Microsoft Word の docx 形式で送る必要が増えて来たんですが、なるべく Word を触りたくないので、うまいことテキストエディタで書いた文章を自動的に整形された docx ファイルに出力できないものか、と思って調べて Pandoc にたどり着きました。

その目的は達成できたか

できていません(2013.1.14現在)。
段組みを使った文書を作りたかったんですが、 Pandoc のテーブルの記法を使っての段組みは日本語と相性が悪めでした。
でも、まだ何か上手いやり方がある気がするので引き続き色々試してみます。

Pandoc 用拡張 Markdown 記法

Pandoc User’s Guide で解説されていた記法の一部を試して、覚え書きを下記に残したのでご参考まで。
ウェブ上で Pandoc を試せる Try Pandoc! で実際に触りながら読むと何を言ってるか判りやすいです。

見出しの書き方

見出しは # で始める。#が増えると見出しレベルが上がる。

#見出し１

##見出し２

###見出し３

改行の仕方

改行が１つだと、改行として処理されずに一続きの文章として処理されます。

行末に２つ以上のスペースを入れるか  
行末にバックスラッシュを入れる\

と改行できます。

リンク

URL をそのままリンクにする時は

<https://grkt.com>

のように書く。

インラインリンクは

[リンクのテキスト](リンク先 "リンクのタイトル")

と書く。

リンク先を参照する事もできる。

[リンクのテキスト][linkref]

[linkref]: https://grkt.com 'TAKASAKI Yusuke'

リンク字体とリンクの定義を別にしておく事で、複数の箇所から1つのリンクを参照する事ができる。一カ所更新すると全てに反映できるのでミスが減る。

識別子は大文字と小文字を区別しないので linkref と LINKREF は同義。
ページ内リンクは通常の a タグでの場合と同じ。

[トップに戻る](#top)

ページ内リンク先は自動的に生成される id 属性を指定する意外に方法はない？

強調

*斜体*

**強調**

~~打ち消し~~

でそれぞれ斜体強調 ~~打ち消し~~

コードを書く

チルダ（~）かバッククオート（`）を並べたもので挟む。終わりの線は開始線以上の長さが必要。

チルダ版

~~~~
console.log('Tilder!');
~~~~

バッククオート版

````
console.log('Backquote!');
````

言語の指定も出来る。対応してると色が付く？

````JavaScript
console.log('JavaScript!');
````

属性を追加する事もできる。前述の言語の指定で JavaScript と書く事と、属性で .javascript と指定するのは同義。

````{#mycode .javascript .numberLines startFrom="100"}
console.log('Attributes!');
````

引用文

引用文は > ではじめる。

>引用を  
>して  
>います

と書いても良いし

>引用を  
して  
います

という楽な書き方でも良い。

リストの書き方

ブレットリストは * で始める。* とテキストの間にスペースが必要。

* 子
* 丑
* 寅
* 項目が複数行に渡る場合は
    行頭でスペースを4つ連続させるかタブを1つ入れる。
* 入れ子にする時は
    + 4つスペースを入れて + で始める
        - さらにネストする時は - で始める

オーダードリストは

1. 数字とピリオドで
2. 連番を
3. 振って行く
#. デフォルトで
#. 良い時は
#. #とピリオド

結構クセのある動きをする。

(1) みたいな
(2) 書き方でも
(3) いいみたい

定義リスト

HTML で言う所の dl dt dd。

項目
:   定義

と書く。

Numbered example lists

出力されるのはオーダードリストなんだけど、ラベル付けして参照できるっぽい。あとから順序が大きく入れ替わる事があっても参照先が自動的に書き変わる。

> (@good)  良い子
> (@bad)  悪い子
> (@ordinary)  普通の子
> 
> そして、(@good) の名前は「よしお」

みたいな書き方をしておくと、後で順序を入れ替えても修正が一カ所で済む。

リストが繋がっちゃうときは <!– end of list –>

リストの後ろにあるテキストを、複数行のリストだと誤認識する場合がある。また、複数のリストを連続で書くと、繋がってしまう。その時はコメントを入れる。

#. りんご
#. みかん
#. なし

#. いぬ
#. さる
#. きじ

↑だと繋がってしまう。

↓間にコメントを入れると繋がらない。コメントの内容は何でもいい。

#. りんご
#. みかん
#. なし

<!-- end of list -->

#. いぬ
#. さる
#. きじ

横罫線

横罫線は * か - か _ を並べる。

---------------

間にスペースを入れても良い。

*  *  *  *

テーブル

ヘッダ行のしたにハイフン（-）で線を引く。

Table: キャプションも書ける。

ヘッダ１    ヘッダ２    ヘッダ３    ヘッダ４
------     ------     ------    -------
1              2        3           4
111          222       333        444

ハイフンとの位置関係で左揃え／中央揃え／右揃えが設定できる。
でも、アルファベットだと奇麗になるけど日本語だとなかなか難しい。

ヘッダ行が無い場合は上下をハイフンで挟む。

Table: ヘッダ行がない場合

------    ------      ------    ------
1              2        3           4
111          222       333        444
------    ------      ------    ------

複数行テーブルの書き方は以下の通り。

Table: 複数行テーブル

------------------------------------------------
通し番号     内容                    日付       
----------  ---------------------  -------------
         1  複数行に\                  2013.1.13
            渡るタイプのやつ

         2  ふたつめの\                2013.1.14
            やつ
------------------------------------------------

上手く使えると便利そうだけど、等幅の英字フォントじゃないとなかなか難しい。

Table: ヘッダなしの複数行テーブル

---------  ---------------------  -------------
    1      複数行に\                  2013.1.13
           渡るタイプのやつ

    2      ふたつめの\                2013.1.14
           やつ
-----------------------------------------------

他にもグリッドテーブルの書き方があるけど日本語だと厳しい。下記、そのまま転載。

: Sample grid table.

+---------------+---------------+--------------------+
| Fruit         | Price         | Advantages         |
+===============+===============+====================+
| Bananas       | $1.34         | - built-in wrapper |
|               |               | - bright color     |
+---------------+---------------+--------------------+
| Oranges       | $2.10         | - cures scurvy     |
|               |               | - tasty            |
+---------------+---------------+--------------------+

定義リストみたいな形で、列を改行で表す書き方があればいいのに。

タイトルブロック

ファイルの最初に、行頭が%ではじまるブロックを書くとタイトルとして扱われる。

% Pandoc用拡張Markdown記法の覚え書き
% 高崎悠介
% January 13, 2013

HTML 出力すると title タグやメタタグの author, date に反映される。

上付き数字と下付き数字

上付きは ^ で挟む。下付きは ~ で挟む。

2^10^

H~2~O

それぞれ
2¹⁰
H₂O
になる。HTML の <sup> と <sub> に対応。

^数字_{じゃなくても}大丈夫

画像

リンクの前に ! を付けると、ハイパーリンクではなく画像として扱われる。

![キャプション](ファイルパス "タイトル")

リンクと同様、ファイルパスを参照する事もできる。

![movie reel]

[movie reel]: movie.gif

ただし、上記の方法だと HTML 出力をした時に、画像が <div class=”figure”> でくくられる。

また、強制的にキャプションが表示される。
画像のみ表示する場合は、後ろにバックスラッシュでエスケープしたスペースを付けてインライン表示にする。

![キャプション](ファイルパス "タイトル")\

脚注

脚注へのリンクは

[^1]

と書く。

脚注の定義は

[^1]: 脚注

自動的にページ下部に配置される。脚注へのリンクの直後に定義できるので便利。
識別子は数字じゃなくてもいいが、スペースを含んではいけない。HTML出力した場合、識別子は自動的に連番に変換される。

触ってみた感想

テキストエディタで書いたものを、人に渡す時に Microsoft Word の docx に整形して渡せたらいいな、と常々思ってツールを探していて、見事にその欲求に合うツールでした。

実際に docx に出力してみたら、まだ一番使いたいテーブルでの段組みは上手く使えない感じ。普通の文章を書くには問題無し。テンプレートの機能もあるみたいなので今後いじってみる。最終的に原稿やら台本が出力できたら最高。そうすれば iPhone のメモで書いて docx 化できるので、移動中にできる作業が増えますね。

スライドショーや wiki の出力もできるみたいなので、そっちも色々楽しそう。