個人出版・AI校正

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

個人出版・AI校正

pandocの使い方覚書です。ePUBとHtmlの出力に主に利用しています。

pandocはmarkdown preview enhancedとあわせて使うと便利です。

【使い方】markdown preview enhancedのエクスポートとpandoc
ebookbrain.net
1user
人気記事:電子書籍は半額で安く買える!?おすすめ比較全まとめ)!

目次

Re:VIEWとpandocとSphinxの比較

pandocを使う前にいろいろと検討しました。

typora有料化代替は!?!markdownエディタtyporaの使い方
ebookbrain.net

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がライセンス的には１番厳しいGPLで多少気になる人もいるかもですが、いうても電子書籍のソースコードなんかテンプレートを使うならHtmlやCSS程度で大したものではないですし。

スポンサーリンク

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

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

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

https://pandoc.org/CONTRIBUTING.html

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

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

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

販売についてはこちら!

GNUライセンスに関してよく聞かれる質問 - GNUプロジェクト - フリーソフトウェアファウンデーション
www.gnu.org

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

OSSライセンスの教科書
著:上田 理, 監修:岩井 久美子
¥3,168 （2022/09/13 15:18時点 | Amazon調べ）
Amazon
楽天市場
Yahooショッピング
OSSライセンスを正しく理解するための本
著:姉崎章博
¥2,010 （2022/09/13 15:22時点 | Amazon調べ）
Amazon
楽天市場
Yahooショッピング
これでできる！はじめてのOSSフィードバックガイド　「つよいエンジニア」になるための実績の育て方 (技術の泉シリーズ（NextPublishing）)
著:結城 洋志
¥1,980 （2022/09/13 15:19時点 | Amazon調べ）
Amazon
楽天市場
Yahooショッピング

Pandocは個人的にもなかなかいい気がしますね。

(追記)markdown preview enhancedのエクスポート機能は使わず、markdown preview enhancedはプレビューのみにして、pandocでエキスポートが最適解になりつつあります。

スポンサーリンク

pacdocの使い方の電子書籍

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

Introducing Markdown and Pandoc: Using Markup Language and Document Converter (English Edition)
著:Mailund, Thomas
¥3,531 （2022/10/08 16:34時点 | Amazon調べ）
Amazon
楽天市場
Yahooショッピング

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

Markdownライティング入門　プレーンテキストで気楽に書こう！ (技術の泉シリーズ（NextPublishing）)
著:藤原 惟
¥990 （2022/10/08 16:35時点 | Amazon調べ）
Amazon
楽天市場
Yahooショッピング

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

フルスクラッチから1日でCMSを作る シェルスクリプト高速開発手法入門 改訂2版
ドワンゴ
¥3,080 （2022/11/14 19:04時点 | Amazon調べ）
Amazon
楽天市場
Yahooショッピング
スポンサーリンク

vscodeでpandocの使い方

pandocとは

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

Pandoc - index
pandoc.org

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

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

Pandoc - Wikipedia
ja.wikipedia.org

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

Releases · jgm/pandoc
Universal markup converter. Contribute to jgm/pandoc development by creating an account on GitHub.
github.com
  1. pandoc-X.X.XX-windows-x86_64.msiをダウンロード(MacはMacの場合、pandoc-X.XX.X-macOS.pkgをダウンロードします。)
  2. インストール(特に迷うところはない)
  3. 再起動はたぶん必要だったかな

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

pandoc 3のアップデート

Windowsの場合、上書きインストールすればいいだけのようです。インストーラーでインストールしました。

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でコードブロック(シンタックスハイライト)を追加

長くなったため別記事にしました。

CSSでコードブロックのファイル名を表示(pandocのシンタックスハイライト自作)
ebookbrain.net

pandocのメタデータ

markdownファイルの1番上に記載する感じです。

タイトルは最低限必要です。

---
title: "タイトル"
---

htmlの場合、メタ情報が変更されることはもちろんタブに表示される名前が、ファイル名からタイトルに変わります。

ePUBの場合、画面上がタイトルになります。mdを1つだけ変えると全般的に反映されてしまうようです。

Pandoc User’s Guide 日本語版 — 日本Pandocユーザ会
pandoc-doc-ja.readthedocs.io

$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 - Pandoc User’s Guide
pandoc.org

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

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

デフォルトのテンプレート自体はこちらから見れます。

GitHub - jgm/pandoc-templates: Templates for pandoc, tagged to release
Templates for pandoc, tagged to release. Contribute to jgm/pandoc-templates development by creating an account on GitHub.
github.com

なぜテンプレを作ったのかといえば、1ページ目に挟まるヘッダーみたいなものが邪魔だったから少しカスタマイズしたかったからです。

子のテンプレもyamlから読み込めばテンプレもOKです。

pandocでPDFの書き出しは今のところ利用していない

PDFを書き出すことはすぐにできません。書き出そうとすると、次のエラーがでます。

pdflatex not found. Please select a different --pdf-engine or install pdflatex

公式サイトのpdfの作成をみると、pdf engineが必要なようです。

Pandoc User’s Guide 日本語版 — 日本Pandocユーザ会
pandoc-doc-ja.readthedocs.io

TeX Liveのリンクを辿ります。macの場合は

MacTeX distribution. > MacTeX Download. > MacTeX.pkg

をダウンロードします。このファイルは重たいですね。

簡易版のBasicTeX.pkgもでていました。重たさにびっくりして結局こちらを使いました。

ttp://tug.org/mactex/morepackages.html

中途半端ですいませんが、この先はpandocを使う人は他のサイトをみてください。

PDFのエクスポートはvivliostyleが進化してきたこともあり、CSS組版でやることに路線変更しました。もともとブロガーなので、CSSの方がわかりやすいです。デザインはそのうちこりたくなるかも気がしたため。