vscodeでpandocの使い方/商用利用やライセンスは?Re:VIEWとSphinxとの比較

個人出版・AI校正

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、海外製ならpandocやSphinxという単純な理解をしました。

Re:VIEWのメリットデメリット

Re:VIEWのメリットデメリットです。Re:VIEWとPandocを使っている人が多そうでした。

  • 使っている人が多いため情報が豊富でした。
  • テンプレートもあります。
  • Re:VIEWはRubyのインストールが必要ならしいです。
  • LATeX。組版といえどもそこまでPDFを作るのに、結構、細かすぎるかなと思い、
  • また、デザインの柔軟性が欠ける情報もありで見送り。

ライセンスについてはこちらです。

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

pandocのデメリットとメリット

  • 使っている人が多いため情報が豊富でした。
  • Pandocのインストールほか、日本語対応も必要です。
  • node.jsを使っているjavascript系の人はこっちがいいかも。
  • 環境構築が面倒。
  • LATeX(個人的にCSSの方が取っつきやすいというだけです。人により違うかもしれません)。ただし、ePUBやHtmlは関係ない
  • デザインの柔軟性がかけるっぽい。。

Re:VIEWとPandocのどちらかを少し使ってみようと思っていたところ、

個人的にnode.jsが入っていたためpandocを使うことに。Pandocがライセンス的には1番厳しいGPLで多少気になる人もいるかもですが、いうても電子書籍のソースコードなんかテンプレートを使うならHtmlやCSS程度で大したものではないですし。

スポンサーリンク

vscodeでpandocの使い方

pandocとは

pandocはコンバーターです。公式サイトをみるとhtmlやePUBのエクスポートに対応しているのがわかります。

Wikidediaをみると、John MacFarlaneさんが作ったようです。エンジニアとは書かれておらず、哲学科の教授という点が興味深いです。University of California, Berkeleyの所属のようです。

プラグインはスクリプト言語でおなじみのluaで記述可能と書かれています。

pacdocの使い方の電子書籍

解説本はこちらの洋書です。

markdownの書籍でも少しだけ紹介されていました。

pandocはシェルスクリプトの知識があると、いろいろ自動化できます。

pandocの評判(商用利用もあり?ライセンスは?)

普通に出版社さんが使っているようですね。

All code must be released under the general license governing pandoc (GPL v2).

https://pandoc.org/CONTRIBUTING.html

公式サイトをみるとGPLのようですね。WordPressと同じといえばわかりやすいでしょうか。

  • 有料テーマも販売できるけどGPLライセンスになる(Pandocを使っているTyporaも有料)
  • ソースコードの公開が必要
  • 配布しない限り、ソースを公開しなくていい

みたいな感じだった気がします。

販売についてはこちら!

詳しくは専門じゃないので本に譲ります。

著:上田 理, 監修:岩井 久美子
¥3,168 (2022/09/13 15:18時点 | Amazon調べ)
著:姉崎章博
¥2,010 (2022/09/13 15:22時点 | Amazon調べ)

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というソフトを使った際にインストールしてしまいました。

  1. pandoc-X.X.XX-windows-x86_64.msiをダウンロード(MacはMacの場合、pandoc-X.XX.X-macOS.pkgをダウンロードします。)
  2. インストール(特に迷うところはない)
  3. 再起動はたぶん必要だったかな

Homebrewなどコマンドラインからインストールする方法もありますが、また、Homebrewのインストールが必要になります。

pandocの基本的な使い方

インストールすると次のコマンドが使えます。

ePUBに変換します。

pandoc -s test.md -o test.epub

htmlに変換します。

pandoc -s test.md -o test.html

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の一括変換

コマンドでも複数のmdを1つのhtmlなどにまとめることができるようです。

pandoc *.md -o output.html

ファイルの順番は他にも方法があるかもしれませんが、ひとまずファイル名で制御してみました。

01-sample.md
02-sample.md

Windowsのバッチファイル (.bat)やUnixのシェルスクリプト (.sh)を使って対応されている方もいるようですね。

スポンサーリンク

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は拡張子をつけてもつけなくても通りました。

各コマンドの補足です。

ファイルへ出力したい場合は -o オプションを使用してください

https://pandoc-doc-ja.readthedocs.io/ja/latest/users-guide.html

Pandoc は分割された文書群を生成します。スタンドアロン文書(例えば、 <head> と <body> を含む有効な HTML ファイル)を生成するには、 -s または -standalone フラグを使います:

https://pandoc-doc-ja.readthedocs.io/ja/latest/users-guide.html

入力形式の指定は -f/--from オプションを、出力形式の指定は -t/--to オプションを使います。

https://pandoc-doc-ja.readthedocs.io/ja/latest/users-guide.html

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.html

pandocで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つだけ変えると全般的に反映されてしまうようです。

$author$

デフォルトテンプレートが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.png

ePUBのスタイルシート

–epub-stylesheetは使わないでください。過去のもののようです。

Removed –epub-stylesheet; use –css instead

https://github.com/rstudio/bookdown/issues/478
pandoc $(dir *.md) -c base-epub.css -o export.epub

ePUBの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
other pages.

https://github.com/jgm/pandoc/issues/4829

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.epub

YAMLの詳しい使い方は適当に調べましょう。

どんなオプションがあるのかは公式サイトをみましょう。

Default fileのGeneral options以下です。

次のコマンドでコンバートできます。

pandoc -d epub.yaml

pandocの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.html

En 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のテンプレで目次じゃなくてファイル名のリストを取得する命令がないっぽい。章のファイルが増えるたびに手動追加。

デフォ機能ではできないっぽい。致命的ではないのでいったん保留にします。

参考になれば幸いです。

スポンサーリンク
個人出版・AI校正
neruをフォローする
スポンサーリンク
ebookbrain

コメント