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

プログラミング学習

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で記述可能と書かれています。

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)を使って対応されている方もいるようですね。

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のカスタムテンプレート

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

highlight.jsやprismjsを使う場合はこちらを先に参照するとよい気がします。

こちらでは通常のやり方を書きます。

まず言語が対応しているか見ます。

pandoc --list-highlight-languages

次のように表示されるはずです。

abc
actionscript
ada
agda
apache
asn1
asp
ats
awk
bash
bibtex
boo
c
changelog
clojure
cmake
coffee
coldfusion
comments
commonlisp
cpp
cs
css
curry
d
default
diff
djangotemplate
dockerfile
dot
doxygen
doxygenlua
dtd
eiffel
elixir
elm
email
erlang
fasm
fortranfixed
fortranfree
fsharp
gcc
glsl
gnuassembler
go
graphql
groovy
hamlet
haskell
haxe
html
idris
ini
isocpp
j
java
javadoc
javascript
javascriptreact
json
jsp
julia
kotlin
latex
lex
lilypond
literatecurry
literatehaskell
llvm
lua
m4
makefile
mandoc
markdown
mathematica
matlab
maxima
mediawiki
metafont
mips
modelines
modula2
modula3
monobasic
mustache
nasm
nim
nix
noweb
objectivec
objectivecpp
ocaml
octave
opencl
orgmode
pascal
perl
php
pike
postscript
povray
powershell
prolog
protobuf
pure
purebasic
python
qml
r
raku
relaxng
relaxngcompact
rest
rhtml
roff
ruby
rust
sass
tcsh
texinfo
toml
typescript
verilog
vhdl
xml
xorg
xslt
xul
yacc
yaml
zsh

今回はJavaScriptだったため、問題なく進みました。javascriptreactもありますね。分けたいとき便利そう。vueに使っても問題ないのかな。

なお、markdownの場合、言語を指定しないとコードブロックが効かないです。

NGです。変換した際に変わりません。

```
```

OKです。言語リストのまま追加しました。大文字と小文字も注意してください。

```javascript
```

コードブロックのスタイルは次のものがあります。

オプションは pygments (既定)、 kate , monochrome, breezeDark, espresso, zenburn, haddock, tango です。

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

コードブロックの中身を見たい場合はこうです。

pandoc --print-highlight-style zenburn

白地だったためわかりやすい黒地のzenburnを選びました。

他の見た目のサンプルはこちらのサイトにありました。

なお、自分でカスタマイズしたものを適用することもできます。

VsCodeの同階層に生成されます。

pandoc --print-highlight-style zenburn > codestyle.theme

適用します。

pandoc --highlight-style codestyle.theme

pandocのコードブロックにファイル名を追加

luaのフィルターを使うか、CSSで普通にやるかのようです

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$も用途がいまいちわからないので消し。あんま調べてないけど。。

スポンサーリンク

pandocのePUB編

表示をつける

 pandoc -s sample.md -o sample.epub --epub-cover-image=theme/images/cover.png

目次をつける

pandoc  $(dir *.md) -o output.epub --toc --toc-depth=2

ePUBのスタイルシート

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

Removed –epub-stylesheet; use –css instead

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

ヘッダー・フッター

デフォルトの場合、ヘッダーに本のタイトル、フッターにページ数が入るようです。Apple Booksで確認。

スポンサーリンク

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ならではのバッチファイルにして対応しました。

参考になれば幸いです。

コメント

タイトルとURLをコピーしました