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程度で大したものではないですし。
vscodeでpandocの使い方
pandocとは
pandocはコンバーターです。公式サイトをみるとhtmlやePUBのエクスポートに対応しているのがわかります。
Wikidediaをみると、John MacFarlaneさんが作ったようです。エンジニアとは書かれておらず、哲学科の教授という点が興味深いです。University of California, Berkeleyの所属のようです。
プラグインはスクリプト言語でおなじみのluaで記述可能と書かれています。
pacdocの使い方の電子書籍
解説本はこちらの洋書です。
ポチップmarkdownの書籍でも少しだけ紹介されていました。
ポチップpandocはシェルスクリプトの知識があると、いろいろ自動化できます。
ポチップ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でエキスポートが最適解になりつつあります。
pandocのインストールの確認
typoraなどマークダウンエディタを使っているとすでに入っている可能性があります。
pandoc -v$ pandoc -v
pandoc 2.10.1
Compiled with pandoc-types 1.21, texmath 0.12.0.2, skylighting 0.8.5
Default user data directory: /Users/neru/.local/share/pandoc or /Users/neru/.pandoc
Copyright (C) 2006-2020 John MacFarlane
Web: https://pandoc.org
This is free software; see the source for copying conditions.
There is no warranty, not even for merchantability or fitness
for a particular purpose.
pandocのインストール
pandocはインストーラーでインストールするのが楽です。typoraというソフトを使った際にインストールしてしまいました。
- pandoc-X.X.XX-windows-x86_64.msiをダウンロード(MacはMacの場合、pandoc-X.XX.X-macOS.pkgをダウンロードします。)
- インストール(特に迷うところはない)
- 再起動はたぶん必要だったかな
Homebrewなどコマンドラインからインストールする方法もありますが、また、Homebrewのインストールが必要になります。
pandocの基本的な使い方
インストールすると次のコマンドが使えます。
ePUBに変換します。
pandoc -s test.md -o test.epubhtmlに変換します。
pandoc -s test.md -o test.htmlpandocの目次
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の一括変換
コマンドでも複数のmdを1つのhtmlなどにまとめることができるようです。
pandoc *.md -o output.htmlファイルの順番は他にも方法があるかもしれませんが、ひとまずファイル名で制御してみました。
01-sample.md
02-sample.mdWindowsのバッチファイル (.bat)やUnixのシェルスクリプト (.sh)を使って対応されている方もいるようですね。
pandocのhtmlカスタムテンプレート
pandocのhtmlカスタムテンプレート
デフォルトのテンプレートは次のコマンドでターミナル上に表示されます。
pandoc -D htmlテンプレートを生成する場合は次のような感じです。同階層に作られます。
pandoc -D html > mytemplate.htmlhtmlをカスタマイズしたい場合、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などでメニューから開く目次は、この指定をしなくても勝手につくようです。あくまで本の最初に目次ページを作るか否かです。
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の書き出しは今のところ利用していない
PDFを書き出すことはすぐにできません。書き出そうとすると、次のエラーがでます。
pdflatex not found. Please select a different --pdf-engine or install pdflatex公式サイトのpdfの作成をみると、pdf engineが必要なようです。
TeX Liveのリンクを辿ります。macの場合は
MacTeX distribution. > MacTeX Download. > MacTeX.pkg
をダウンロードします。このファイルは重たいですね。
簡易版のBasicTeX.pkgもでていました。重たさにびっくりして結局こちらを使いました。
ttp://tug.org/mactex/morepackages.html
中途半端ですいませんが、この先はpandocを使う人は他のサイトをみてください。
PDFのエクスポートはvivliostyleが進化してきたこともあり、CSS組版でやることに路線変更しました。もともとブロガーなので、CSSの方がわかりやすいです。デザインはそのうちこりたくなるかも気がしたため。
pandocのluaのフィルターの使い方
まだ使っていません。このあたりに情報がありましたので情報提供のみで。
PandocがLuaインタプリタを内蔵しているので、実行環境をユーザーが用意する必要なし。
https://blog.atusy.net/2020/12/07/lua-filter-is-hot/
環境を用意しなくてもいいのはいいですね。
pandocのエラー
[WARNING] This document format requires a nonempty element.
[WARNING] This document format requires a nonempty <title> element.
Defaulting to 'index' as the title.
To specify a title, use 'title' in metadata or --metadata title="...".タイトルがないだけみたいです。タイトルをつけるとePUBではタイトルが表示されます。
---
title: "ePUB変換"
---openBinaryFile: invalid argument (Invalid argument)
一括変換しようとした際に出たエラーです。なかなか解決策がなくフランス語のサイトをあさっていたら解決しました^^;。
openBinaryFile: invalid argument (Invalid argument)pandoc *.md -o output.html
↓
pandoc $(dir *.md) -o output.htmlサブフォルダもあわせて指定する場合はこう。
pandoc $(dir *.md) $(Get-ChildItem ./markdown/*.md) -o output.html
pandoc $(dir *.md) $(dir./markdown/*.md) -o output.htmlEn effet *.md n’est pas reconnu en powershell mais uniquement en shell sh ou bash.
https://forum.canardpc.com/threads/130205-Resolu-Utilisation-de-Pandoc-sous-windows
根本的なところではPowerShellではダメみたい。bashやshじゃないと。
bash --v
bash: The term 'bash' is not recognized as a name of a cmdlet, function, script file, or executable program.
Check the spelling of the name, or if a path was included, verify that the path is correct and try again.たしかにWindowsには入れてなかった。。
入れるのが面倒だったので、とりあえずWindowsならではのバッチファイルにして対応しました。
pandocのデメリット
不満点はほとんどないけど、
- コードブロックのファイル名をQiita風に書きたかった。
- htmlのテンプレで目次じゃなくてファイル名のリストを取得する命令がないっぽい。章のファイルが増えるたびに手動追加。
デフォ機能ではできないっぽい。致命的ではないのでいったん保留にします。
参考になれば幸いです。
コメント