pandocの使い方覚書です。ePUBとHtmlの出力に主に利用しています。
pandocはmarkdown preview enhancedとあわせて使うと便利です。
目次
Re:VIEWとpandocとSphinxの比較
pandocを使う前にいろいろと検討しました。
markdown系のソフトもエクスポートにpandocを使っているため、より柔軟性があるpandocに。
pandocとよく比較されるものに次のものがあります。
ライセンス | 言語 | |
pandoc | GPL v2 | node.js |
Re:VIEW | LGPL が適用される Re:VIEW のプログラム MIT が適用される Re:VIEW のテンプレート | Ruby |
Sphinx | 修正BSDライセンス | Python |
言語とライセンスが違います。あと、使ってないため何とも言えませんがSphinxはドキュメンテーションジェネレータというカテゴリなのでしょうか。pandocやRe:VIEWは技術同人誌でよく使われています。
Re:VIEWのメリットデメリット
Re:VIEWのメリットデメリットです。Re:VIEWとPandocを使っている人が多そうでした。
ライセンスについてはこちらです。
Re:VIEWは未使用のため、もしかしたらもっといいところがあるかもしれません。
Re:VIEW のプログラムには、「GNU Lesser General Public License Version 2.1」（以下LGPL）が適用されます。
EPUB / TeX 用のレイアウトテンプレート、TeX 用のスタイルファイルについては「MIT License」（以下MIT）が適用されます。
TeX （pdfmaker）向けに内包している jumoline.sty スタイルファイルには「The LaTeX Project Public License」（以下LPPL）が適用されます。
https://review-knowledge-ja.readthedocs.io/ja/latest/faq/faq-license.html
iBooks に突っ込めばクラウドで共有されて iPhone でも iPad でも Mac でも読めて、読書状況やしおりも同期されるので便利。
— 大岡由佳『りあクト! 第4版』BOOTHで販売中！紙本も (@oukayuka) January 13, 2020
製本は Re:VIEW でもできるけど、Pandoc のほうが自由度高い。PDF だと Acrobat で最終調整するのを、Sigil でやる感じですかね。
pandocのデメリットとメリット
Re:VIEWとPandocのどちらかを少し使ってみようと思っていたところ、
個人的にnode.jsが入っていたためpandocを使うことに。Pandocがライセンス的には１番厳しいGPLで多少気になる人もいるかもですが、いうても電子書籍のソースコードなんかテンプレートを使うならHtmlやCSS程度で大したものではないですし。
Pandoc導入1年後の感想
不満点はほとんどないけど、
コードブロックのファイル名をQiita風に書きたかった。→luaのフィルターを使ったら簡単に解決できました。htmlのテンプレで目次じゃなくてmdのファイル名のリストを取得する命令がないっぽい。章のファイルが増えるたびに手動追加。→Node.jsでスクリプトをかいて解決
デフォ機能ではできないっぽい。
他はかなり満足しています。PDFは直接出力するより、1回Wordに変換する方法がよさそうです。VivliostyleというCSS組版もあります。
pandocの評判(商用利用もあり?ライセンスは?)
普通に出版社さんが使っているようですね。
Pandocはmunepiさんのようなプロフェッショナルと組めば十分商用に耐える品質の制作ができることがわかったのは大きな収穫でした。Pandocはfilterが強力で処理の柔軟性が高く、PC系の書籍編集がほしい機能はだいたいあとからつけられそうです。
— Daiki Noda（技術評論社雑誌編集部） (@nodawep) March 4, 2021
All code must be released under the general license governing pandoc (GPL v2).
https://pandoc.org/CONTRIBUTING.html
公式サイトをみるとGPLのようですね。WordPressと同じといえばわかりやすいでしょうか。
- 有料テーマも販売できるけどGPLライセンスになる(Pandocを使っているTyporaも有料)
- ソースコードの公開が必要
- 配布しない限り、ソースを公開しなくていい
みたいな感じだった気がします。
販売についてはこちら!
詳しくは専門じゃないので本に譲ります。
ポチップ
こんなでもいいです。https://t.co/wbfvgn7oz6
— Toro_Unit（山の上のとろゆに） (@Toro_Unit) August 21, 2022
ソースを公開しないことはできないが、販売することはできる。ただし、ソースの値段 <= バイナリの値段。よくある質問参照。
— きさらぎ🚮 (@ksrg_tech) May 16, 2020
ライセンス次第ではありますが, 解説本の文章が著者による著作物であれば, そのOSSとは全く別の著作物なので, 何の問題も無いと思います.
— tomo🐧@learning (@cocoatomo) May 25, 2018
また個人的な感想ですが, そのような出版による商売を制限するようなライセンスは OSS っぽくないと感じます (曖昧な表現ですみません).
むしろ、「解説本書いちゃダメ」なんていったらオープンソースとしてはあまりよろしくないかと思いますよ。
— 鈴木㌠@C100 1日目 東レ05a (@linuxsearchers) May 25, 2018
Pandocは個人的にもなかなかいい気がしますね。
(追記)markdown preview enhancedのエクスポート機能は使わず、markdown preview enhancedはプレビューのみにして、pandocでエキスポートが最適解になりつつあります。
pacdocの使い方の電子書籍
解説本はこちらの洋書です。
ポチップ
markdownの書籍でも少しだけ紹介されていました。
ポチップ
pandocはシェルスクリプトの知識があると、いろいろ自動化できます。
ポチップ
vscodeでpandocの使い方
pandocのインストールと基本的な使い方
長くなったため、noteに寄稿しました。
pandocの目次
2階層目まで目次をつけます。mdの上部に目次がつきます。
pandoc -s --toc --toc-depth=2 test.md -o test.html
--toc,--table-of-contents出力文書に自動生成された目次を含めます
https://pandoc-doc-ja.readthedocs.io/ja/latest/users-guide.html
--toc-depth=NUMBER目次に含めるセクションレベルを指定します。既定は3です
https://pandoc-doc-ja.readthedocs.io/ja/latest/users-guide.html
ただ、サイドバーに目次をつけたいですかね。サイドバーで目次をつける際はMarkdown Preview Enhancedを使う方法もあります。ただpandocでつけた方がソースコードは扱いやすいですね。
pandocのhtmlカスタムテンプレート
pandocのhtmlカスタムテンプレート
pandoc -D htmlこのコマンドはテンプレートファイルを作成するのではなく、コマンドラインやターミナルの画面上に直接表示するだけです。
pandoc -D html > mytemplate.htmlテンプレートを生成したい場合は、このコマンドです。同階層に作られます。htmlをカスタマイズしたい場合、mytemplate.htmlをいじるとよいです。
変換する際はテンプレートを割り当てます。
pandoc -f markdown -t html --template=mytemplate index.md > index.html
pandoc -s sample.md -c ./theme/css/base.css --template=template/mytemplate.html -o sample.html–templateは拡張子をつけてもつけなくても通りました。
各コマンドの補足です。
ファイルへ出力したい場合は
https://pandoc-doc-ja.readthedocs.io/ja/latest/users-guide.html-oオプションを使用してください
Pandoc は分割された文書群を生成します。スタンドアロン文書（例えば、
https://pandoc-doc-ja.readthedocs.io/ja/latest/users-guide.html<head>と<body>を含む有効な HTML ファイル）を生成するには、-sまたは-standaloneフラグを使います:
入力形式の指定は
https://pandoc-doc-ja.readthedocs.io/ja/latest/users-guide.html-f/--fromオプションを、出力形式の指定は-t/--toオプションを使います。
pandocのカスタムCSS
単純な外部リンクになりますね。もとから適応されるスタイルシートはなくなるようです。逆に指定しないとデフォルトのCSSが入るため注意です。
同階層の場合です。
pandoc -s sample.md -c base.css -o sample.html複数のときはこう。
pandoc -s sample.md -c base.css -c theme.css -o sample.htmlまとめ
まとめるとこんな感じです。
pandoc -s sample.md -c base.css --template=template --toc --toc-depth=2 -o sample.htmlpandocでJavaScriptを追加
次のものを使うと、各々の場所に追加されます。
--include-in-header=FILENAME
--include-before-body=FILENAME
--include-after-body=FILENAME JavaScriptはbodyの前でしょうから–include-after-bodyで指定してあげます。
読み込むJSのファイルは外部ファイルと違ってあらかじめscriptで囲う必要があります。
<script></script>pandocでコードブロック(シンタックスハイライト)を追加
長くなったため別記事にしました。
pandocのメタデータ
markdownファイルの1番上に記載する感じです。
タイトルは最低限必要です。
---
title: "タイトル"
---htmlの場合、メタ情報が変更されることはもちろんタブに表示される名前が、ファイル名からタイトルに変わります。
ePUBの場合、画面上がタイトルになります。mdを1つだけ変えると全般的に反映されてしまうようです。
デフォルトテンプレートがforになっていたため、少し謎でした。
$for(author)$
<p class="author">$author$</p>
$endfor$どうやら引数が複数あるので、forを使っているようです。
---
author:
- neru
- kun
---$date$
dateは引数ひとつのようです。日付を表示します。
$if(date)$
<p class="date">$date$</p>
$endif$自動で表示するわけではなく、YAMLの指定が必要です。
---
date: 2021/04/27
---$abstract$、$include-before$
$abstract$は文書の要約に使うみたいだけど、個人的に使わなさそうなのでテンプレートから削ってしまった。$abstract-title$も同様。必要なら戻せばいいし。
$include-before$も用途がいまいちわからないので消し。あんま調べてないけど。。
$styles.html()$
<style>
$styles.html()$
</style>あまり詳しく調べていませんが、こちら削ると、コードブロックなどのスタイルが無効化されますね。
pandocのePUB編
表紙をつける
pandoc -s sample.md -o sample.epub --epub-cover-image=theme/images/cover.pngePUBのスタイルシート
–epub-stylesheetは使わないでください。過去のもののようです。
Removed –epub-stylesheet; use –css instead
https://github.com/rstudio/bookdown/issues/478
pandoc $(dir *.md) -c base-epub.css -o export.epubePUBのCSS、tips
ePUBのCSSってシンプルになりますかね。
htmlと違ってメニューも勝手にできます。
そのためePUBは専用のCSSを作成します。一部のコードはそのまま使いまわしがききますかね。
なおコードブロックは全部折り返した方がよさそうですね。
white-space: pre-wrap;ePUBのリーダーは背景色を変更できるものが多いです。background-colorは透明度を指定する形で見せた方がよい気もします。
目次をつける
pandoc $(dir *.md) -o output.epub --toc --toc-depth=2なお、AppleBooksなどでメニューから開く目次は、この指定をしなくても勝手につくようです。あくまで本の最初に目次ページを作るか否かです。
ePUBは文頭に目次を入れていない場合もあるようです。UIに目次がついていますから、そのように割り切っているのでしょう。
html書き出し時に使った目次は使えなかったため、このePUBの目次を使わないとダメなようです。
目次の数字を消す
/* 目次の数字を消す */
nav ol {list-style-type: none;}目次のタイトルを消す
目次って普通、”目次”と表示されるのですが、Pandocの本のタイトルが割り当てられています。
CSSで消してしまいましょう。
/* 目次のタイトル消す */
nav #toc-title { display: none; }新規で追加したい場合はePUBのカスタムフォーマットでいけるようです。
$if(navpage)$
<h1>目次</h1>
$endif$pandoc作者さまのコメントを参考にしました。
Try putting this inside a conditional
$if(navpage)$
…
$endif$That variable is set for nav.xhtml but not the
https://github.com/jgm/pandoc/issues/4829
other pages.
ePUBの改ページ(見出し)
ePUBの改ページをする方法は2とおりあります。
1つはpandocのコンバートするときに指定してあげます。デフォルトではh1の見出しのみ改ページされます。ただ、見出しにh2で使っていると、ePUBが前の章と繋がってしまって見栄えが悪いです。
その際は変換する際に次のオプションを指定するとh2の見出しまで改ページされます。
--epub-chapter-level=2この指定によりxhtmlがどの単位で分割されるかが決まります。
ePUBは拡張子をzipに変えると中身を見ることができます。見出しを細かく分割するとxhtmlが増えているはずです。
ePUBの改ページ(CSS)
もう1つはcssで分割する方法です。長いリストやコードブロックなどうしても1つのページにおさめたいとき便利です。
区切り線のhr改ページできるように。
/* 改ページ */
hr.pagebreak {
height: 0;
visibility: hidden;
border: 0;
/* page-break-after: always; */
break-after: always;
}老舗とほほさんの記載によると、page-break-afterからbreak-afterになったようです。
印刷時に、page-break-before は要素の直前で、page-break-after は要素の直後での改ページを制御します。CSS3 では、改カラムを制御する機能が拡張された break-before, break-after に移行される予定
https://www.tohoho-web.com/css/prop/page-break-x.htm
ヘッダー・フッター
デフォルトの場合、ヘッダーに本のタイトル、フッターにページ数が入るようです。Apple Booksで確認。
ePUBのデータサイズが大きい!
単純に画像やgifなど動画系のデータが大きくなっていることが多いですね。圧縮し忘れなど。9999kbぐらいにおさえたいですかね。
ePUBの拡張子をzipファイルにして調査するとわかります。
コマンドが長いから、設定ファイルをYAMLファイルに書く
ePUBを真面目につくればつくるほど、ePUBのコマンドが長くなります。コピペで使っていても見にくいと感じる人がいるでしょう。Default fileがPandoc 2.8以降使えるようになりました。
New FileでYAMLファイルを新規生成します。
YAMLファイルはコメントもかけます。
# 入力
input-files:
- test.md
# 出力
output-file: outputfile.epubYAMLの詳しい使い方は適当に調べましょう。
どんなオプションがあるのかは公式サイトをみましょう。
Default fileのGeneral options以下です。
次のコマンドでコンバートできます。
pandoc -d epub.yamlpandocのepubカスタムテンプレート
htmlのカスタムテンプレートを考え方は一緒です。
pandoc -D epubただ、コードを確認したところ、htmlのテンプレートと中身はもちろん違いましたね。ePUBはePUBのカスタムテンプレートを使う必要がありそうです。
生成はこうやります。海外も含めてほとんど情報がなかったのですが、たぶんxmlファイルのテンプレでいいんじゃないかな。
pandoc -D epub > epub.xml
pandoc -D epub3 > epub3.xmlどちらも中身は一緒です。
(追記)xmlでも特に問題なさそうだったのですが、こちらの方がいいかもです。拡張子はepub3です。epubにするとVsCode上でコードが見えないなんていう理由もあります。
pandoc -D epub3 > custom.epub3デフォルトのテンプレート自体はこちらから見れます。
なぜテンプレを作ったのかといえば、1ページ目に挟まるヘッダーみたいなものが邪魔だったから少しカスタマイズしたかったからです。
子のテンプレもyamlから読み込めばテンプレもOKです。
PandocでPDFの書き出し(Wordのテンプレートにした方がよい!?)
長くなったため別記事にしました。
コメント