Markdown + Pandoc でお手軽に電子書籍を書く

前回は [Markdown + でんでんコンバーターでお手軽に電子書籍を書いた](https://qiita.com/sta/items/ba5c5067e74fa01a7329) が、でんでんコンバーターはいちいちブラウザからアップロードする＆大きなサイズは扱えないといった不便があったので、今回は Pandoc に挑んでみた。

意外と簡単にできたので、まとめてみる。

# はじめに

## 本記事の内容
本記事では Pandoc が絡む部分のみをまとめる。それ以外の話題は [Markdown + でんでんコンバーターでお手軽に電子書籍を書く - Qiita](https://qiita.com/sta/items/ba5c5067e74fa01a7329) の方を参照。

## 書いた本
[ルーチンタスクの底力: やり忘れとストレスをなくす仕組みと実践 | Amazon](https://www.amazon.co.jp/dp/B07MJW8MVD)

178 ページくらいの仕事術の本（プログラミング無関係）。

## サンプルリポジトリ
[stakiran/eBook_sample_with_markdown_and_pandoc: Markdown + Pandoc で電子書籍をつくるサンプル](https://github.com/stakiran/eBook_sample_with_markdown_and_pandoc)

今回使った環境を簡単にまとめたリポジトリ。

## 前提環境
本記事が前提とする環境は以下のとおり。

- Windows 10
- Pandoc 2.5

# 全体手順
- (1) ファイルの準備
  - 原稿(*.md)
  - 書籍情報(title.txt)
  - 画像類(img/*.jpg)
  - 表紙(cover.jpg)
  - 書式整形(stylesheet.css)
- (2) Pandoc のインストール
- (3) Pandoc を実行して (1) から .ebook ファイルを生成

# 環境準備

## Pandoc のインストール
公式サイトからインストーラーでインストールする。

[Pandoc - About pandoc](https://pandoc.org/)

# 原稿ファイルなどのビルド

## Pandoc を実行する

### コマンドライン全体
まずはじめにコマンドラインを晒すと、たとえば以下のようになる。

```
pandoc -f markdown -t epub3 book.md title.txt -o book.epub --css stylesheet.css --toc --toc-depth=2 --epub-cover-image=cover.jpg
```

### コマンドラインの解説
以下個別に解説する。

```
-f markdown -t epub3
```

推奨。from markdown to epub3 変換を意味する指定。指定しなくてもそれっぽく動作するが、デフォルトの設定は意図しない変換を行うことがあるので、こうやって明示的に指定してしまうのが確実。

```
book.md title.txt
```

必須。変換対象となる markdown ファイルを指定し、その次に書籍情報を指定する。

ここでは **markdown ファイルは単一(つまり原稿を book.md 一つに全部書いている)を想定**。複数存在する場合は取り上げてません（たぶん n 個あれば n 個全部指定するだけで良いかとは思いますが）。

```
-o book.epub
```

必須。変換後のファイル名。XXXX.epub の形なら何でもよいが、半角英数字が良いと思う（ファイル名を日本語にするのはトラブルのもと）。

```
--css stylesheet.css
```

任意。本文の見た目は CSS でカスタマイズできる。ファイル名は何でもよい。

```
--toc --toc-depth=2
```

推奨。目次ページを挿入する指定。また、その際、中見出し(レベル2)まで表示するという指定も併せて行っている。小見出しまで表示したいなら =3 になる。

目次は全体構造を把握する意味でも挿入しておきたい。ただし、Pandoc がつくる文字は各見出しを箇条書きで並べただけの味気ないものなので、気に食わなければ挿入しなくていい。自力で目次ページを作ることになる（作り方は割愛）。

```
--epub-cover-image=cover.jpg
```

推奨。表紙画像を指定するオプション。

# 各ファイルについて

## 原稿(*.md)

### 章立て
（人次第だろうが）私は以下のようにしている。

```
# 部

# 章

## 節

### 項
```

最初は部を大見出しに、章を中見出しに……としていたが、節や項の見出しが深くなりすぎてしまい、扱いづらかったので、部と章は両方とも大見出しにすることにした。

### 押さえたい特殊文法1: 改ページ
Markdown ファイルに以下行を挿入する。

```
<div style="page-break-before:always"></div>
```

### 押さえたい特殊文法1: 画像キャプションの非表示化
画像挿入時に Alt Text を表示させたくないなら、以下のように末尾に \ をつけておく。( **Pandoc で変換すると画像のキャプションとして勝手に Alt Text が付与されてしまう** 仕様)

```
![phase2_howto_a4note](img/phase2_howto_a4note.jpg) \
```

### 意図せぬ番号付きリスト
Pandoc では行頭に `(1)` または `- (1)` または `* (1)` と書いた行を **番号付きリストとして解釈してしまう** ため、意図せず番号付きリストに変換されてしまっているケースがある。

そういう時は上記以外の書き方を使うこと。

これは特に手順などの箇条書きの番号を全部自分で書いている（もっと言うと `(1)` のような書き方で書いている）場合に遭遇する。私は以下のように修正した。

```
- (1) ...
- (2) ...

   ↓ 以下のように修正した

- [1] ...
- [2] ...

```

### 表紙画像は埋め込まない
`![cover](cover.jpg)` のように表紙画像を埋め込む必要はない。

## 書籍情報(title.txt)
詳しいフォーマットは [Pandoc - Creating an ebook with pandoc](https://pandoc.org/epub.html) あたりで網羅されているが、サンプルを挙げると以下のような感じ。

```
---
title: ルーチンタスクの底力 ～やり忘れとストレスをなくす仕組みと実践～
author: 吉良野すた
rights: © 2018 吉良野すた
language: ja-JP
...
```

## 画像類(img/*.jpg)
普通に配置して、Markdown ファイルから `![alttext](img/xxxx.jpg)` などでアクセスするだけ。

## 表紙(cover.jpg)
これも画像を用意するだけだが、今回は Amazon KDP での出版が前提なので、その推奨規格に合わせる。詳しくは [Markdown + でんでんコンバーターでお手軽に電子書籍を書く - Qiita](https://qiita.com/sta/items/ba5c5067e74fa01a7329) を。

## 書式整形(stylesheet.css)
サンプルだけ載せておく。

どんなセレクタを指定すればいいかがわからない場合は、

- (1) Pandoc で to html に変換するオプションを使って HTML ファイルで出力＆それを確認
- (2) [電書ちゃんのでんでんエディター](https://edit.denshochan.com/)

いずれかの方法になるかと思う。

(1) は試してないのでわからない。私は (2) を使っていたので、その名残で今回も CSS は簡単に書けた。（そもそも経緯として一作目はでんでんコンバーターを使っていたが、今回二作目は Pandoc を使った。で、前回のでんでんコンバーター時の CSS ノウハウがあるので、今回もそのまま活用できた）

以下書籍で使った CSS コードを載せとく。

```
/* -------
   Borders
   ------- */

/* 見出しを枠線で強調 */

h1 {
  border-left: 8px ridge #000000;
  border-bottom: 4px ridge #000000;
}

h2 {
  border-left: 6px solid #000000;
}

h3 {
  border-left: 6px double #000000;
}

/* テーブルに枠線を引く */

table {
  border-collapse: collapse;
  border: solid 2px black;
}
table th{
  border: solid 1px black;
}
table td {
  border: solid 1px black;
}

/* ----
   Misc
   ---- */

/* 見た目が不揃いなのを解消する
   - 半角英文字使うので等角じゃないと不均一になる
   - 全角半角入り交じる行が改行前に勝手にスペース調整されるのを防ぐ
*/
p, li, code, table {
  font-family: monospace;
  word-break: break-all;
}

/* 改行位置がほんの少しずれるのを回避する */
p {
  text-align: justify;
}

/* 段落ごとに自動でスペースを付与 */
p {
  text-indent: 1em;
}

/* 太字単体だと強調が乏しいので下線も付ける */
strong {
  text-decoration: underline;
}
```

# おわりに
これでローカルでバシバシビルドできるようになった。快適。