VS Codeのmarkdownで技術同人誌(商用利用)を執筆する方法比較!【PDF/ePUB】

プログラミング学習

2010年頃にたくさん電子書籍の記事をたくさん書いていましたが、久々に電子書籍の記事です。noteも使ったのですが、markdownが利用できません。現在はVS Codeのmarkdownの環境に完全に移行しています。

markdownで技術書(同人誌)を執筆する方法は、実に多彩であり、普段はあんま迷わないのですけど、今回は悩んで軽くいろいろ使ってみることに。せっかく調べたので、覚書程度にまとめておきます。最終的に採用したのは最後のものになります。

VS Codeのmarkdownで技術書(同人誌)を執筆する方法比較!おすすめは?

まず、ざっくりとぐぐったあと、Twiterrでも情報収集しました。最初は簡単にすませたかったため、PDFを作成できるものを探しましたが、だんだんと組版の欲求がでてきてそこまでやることにしました。

Pandoc を描写エンジンに設定できる VSCode 拡張、Markdown Preview Enhanced、まじ最高なんだけど 80 万ダウンロードのそこそこメジャーなプロダクトなんだから、アイコンくらい設定して。https://t.co/pKg55kqBTD

— 大岡由佳『りあクト! 第3版』Booth/Amazonで近日刊行 (@oukayuka) February 27, 2020

Markdown Preview Enhanced で Pandoc をパーサーにして青空文庫ルビフィルターをかまし、Solarized Light テーマに合わせてスタイルをカスタマイズ。本文フォントはしっぽり明朝、見出しはヒラギノ角ゴ Pro。
これで ePub も docx も、なんなら PDF もそのまま作れる。これぞ最強の執筆環境だ! pic.twitter.com/rkw6ajSslk

— 大岡由佳『りあクト! 第3版』Booth/Amazonで近日刊行 (@oukayuka) January 12, 2020

これで全出版プラットフォームいけそうな気がする。

① Pandocとpandoc-crossrefプラグインによる拡張Markdownで原稿を書く
② ①をePubで出力しSigilで調整して、楽天KoboとiBooks Store に
③ ②をkindlegenで.mobiに変換してAmazon KDPに
④ ①を.docxで出力、Wordで調整してPDFにして紙の本に

— 大岡由佳『りあクト! 第3版』Booth/Amazonで近日刊行 (@oukayuka) January 5, 2020

参考までに、自分がまとめてる Pandoc 使い方メモです。https://t.co/QkHPLn3HFZ

— 大岡由佳『りあクト! 第3版』Booth/Amazonで近日刊行 (@oukayuka) January 13, 2020

いろいろと参考になりました。

技術同人誌の入稿用PDF作成(組版)については、個人的に「山の登山ルート」がいくつかあるような見方をしている。

– Re:VIEW→(LaTeX/CSS組版)→PDF
– (Markdown→)HTML/CSS→Vivliostyle→PDF(→入稿可能なPDF)
– Markdown→Pandoc→(LaTeX/Word/CSS組版)→PDF
– Word/PowerPoint→PDF

— 藤原惟📕 (@skyy_writing) September 1, 2019

Re:VIEW→LaTeX→PDF
HTML+CSS→Vivliostyle→PDF
Markdown→PDF
Asciidoc→PDF

お好きなものをお選びください

— なのなの (@nano2_aloerina) December 4, 2018

いろいろとありますね。

EPUB作る人は少数でほとんどは電子版もPDF。組版は粗くてもみんなそこまで気にしない。Re:ViewやSphinx、Pandocなど使われている。TechBoosterさんがテンプレートを出している関係で技術書典ではRe:View使用者が多い。 #jepa

— Jun Tajima (@JunTajima) May 29, 2019

組版はほどほどでいいですかね。ただ、デザインはできるとよいです。個人的にはCSS組版に流れ着きます。

LaTeXとCSS組版の比較

・装飾に強い
・周辺ツールの充実(例えば.mdから本文を生成するツールの選択肢はmd→texよりmd→htmlの方がずっと広い)
・旅行雑誌みたいに文章が並ぶことがメインコンテンツでない場合とかの対応性
あたりになるかと思います

— ライアーノーズ (@liarnose) November 20, 2019

夏コミ新刊、mdである程度書いてからRe:VIEW 3.0でレイアウトしたのだけど、システムとしてはありがたかった。でも細部をLaTeXで整えるのが大変すぎたのでCSS組版どうかなーと思ったが、まだやっぱり大変さはありそうという感じだった。
結局、自分が使える知識・技術とのトレードオフになりそう

— えすじ (@esuji) August 31, 2019

スポンサーリンク

VS Codeのmarkdownで技術書(同人誌)を執筆する方法一覧

Markdown-pdf

この拡張は簡単だったため、1番最初に試しました。

  • Vs Codeの拡張をいれてPDFに簡単に変換できます。お手軽です。
  • htmlにも変換できます。
  • highlight.jsにも対応。
  • CSSの適応はできたり、ページ数を表示したりできます。
一見、これでよさそうな気もしたのですが、そもそも書籍を作ることに特化していないためクオリエィが高い本が作成できません。物足りなさを感じて辞めました。ただの資料ならこれでもOKです。

Markdown Preview Enhanced

Markdown Preview Enhanced - Visual Studio Marketplace
Extension for Visual Studio Code - Markdown Preview Enhanced ported to vscode

Markdown Preview Enhancedは、VS Codeに高度なプレビュー機能を追加し、エクスポート機能がすごいあります。

  • 変換方法が多彩です。
  • html、ePUB、mobi、PDFなど。
  • pandocも対応(要インストール)。
  • プレビュー画面も高度でVS Codeのデフォルトよりよいため、プレビュー用としての利用価値もあるかも。
一見、これでよさそうな気もしたのですが、PDFの変換にやや難がある気がしました。ただ、使っている方もいるようですし、個人的にはそれほど使い込んでいません。もしかしたら頑張ればなんとかできるかもしれません。。

この拡張をインストールすると、たとえば、mdファイルを開いたとき画面右上にプレビューボタンが追加されます。

開いた上で右クリックすると、いろいろできます。

Open in BrowserとクリックするとHtmlファイルが確認できます。

CSSをカスタマイズする方法は次のとおりです。

コマンドパレットを実行します。

View > Command Palette > Markdown Preview Enhanced: Customize CSS

開いたファイルにCSSを記述するとOKです。

.markdown-preview.markdown-preview {
  // modify your style here
  // eg: background-color: blue;
  * {
    overflow: visible;
    font-family: Meiryo, sans-serif;
  }

  h1 {
    padding: 0.5em;
    background-color: #eee9d3;
    border: none;
    border-left: 24px solid #8fb0a9;
  }
}

なお、このファイルは共通のものになりますから他の本(VsCodeのプロジェクト)でもを作ったときも、このCSSが適応されます。

コードブロックやbackground-colorの背景がpdf化するとなくなる問題はChromeの印刷設定時に背景の設定を入れればOKです。

Chrome (Puppetter)
ファイル > 印刷 > 詳細設定 > 背景のグラフィックのチェックをいれる。
ファイル > 印刷 > 詳細設定 > ヘッダーフッダーのチェックをはずす。ページ数も表示されなくなります。

PDF(prince)は無料だと商用不可。

その他のpdf変換

他にもいろいろとあるみたいですね。ただ書籍用というより、ただPDFを作成するものが多いです。

MarkdownをPDFに変換する「md-to-pdf」は痒いところに手が届く素敵ツール | DevelopersIO
MarkdownをPDFに綺麗にいい感じに出力したい…!と探し回っていたところ、「md-to-pdf」が最も私の要件に合致したので使ってみました。
md2pdf - CSSを組版に使ってMarkdownをPDFに変換
MarkdownをPDFにするソフトウェアは幾つもありますが、細かい組版に対応しているものは多くありません。ごく簡単なものであれば問題ありませんが、ドキュメントなどで体裁にこだわりたい場合もあるでしょう。専用アプリもありますが、自動化したいというニーズもあります。 今回紹介するmd2pdfはコマンド一つでMarkdow...

FlightBook

(19) FlightBooks🐤MarkdownでPDFが作れるさん (@FlightBooksJP) / Twitter

FlightBooksという楽にPDFが作成できるサービスのようです。

すごく簡単そうです。
  • 個人的にはさまざまな拡張が使える、Vs Codeから使いたかったが、オンラインエディタのため用途があわず見送り。
  • 速度が遅いらしいという情報もみかけました。

未使用のため、ざっくりとしかとらえていません。もっといいところもあるかもしれません。こちらは同人誌がでていますね。

gitbook

未使用で詳しく調べていないため、紹介だけです。

gitbookの使い方 - Qiita
description: Let's start documentation with gitbook-cli. gitbookの使い方 手軽に記述できる Markdown形式を利用して各種の文章を作成できる gitboo...

Re:VIEW

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

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

Re:VIEWは未使用のため、もしかしたらもっといいところがあるかもしれません。

Pandoc

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

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

日本語化はそんなに問題なさそうだったのと、個人的に参考にしていたエンジニアさんがpandoxを使っていたため、こちらを使ってみることに。でも、Pandocをインストールし、途中までやりましたが、途中でCSS組版に興味がうつり、Vivliostyleに切り替えました。

また、使う機会もあるかもしれませんので簡単にめもです。
インスール方法がいろいろあって混乱かもしれませんが、インストーラーで普通にインストールするのが楽です。

Macの場合、pandoc-X.XX.X-macOS.pkgをダウンロードします。

Releases · jgm/pandoc
Universal markup converter. Contribute to jgm/pandoc development by creating an account on GitHub.

通常のソフトのようにインストールし、インストール後、ターミナルにpandoc -vで入っていることを確認しましょう。
(Vscodeは要再起動)

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

Homebrewなどコマンドラインからインストールする方法もありますが、また、Homebrewのインストールが必要になりますため、今回は採用しませんでした。

しかし、この状態でPDFを書き出すことはまだできません。書き出そうとすると、次のエラーがでます。

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

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

Pandoc User’s Guide 日本語版 — 日本Pandocユーザ会

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

MacTeX distribution. > MacTeX Download. > MacTeX.pkg

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

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

More Packages - MacTeX - TeX Users Group

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

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

スポンサーリンク

おすすめはVivliostyle(pandocいらずに)

もちろん、各々が触っている言語などにより導入しやすさも変わるでしょうが、個人的にVivliostyleを採用しました。採用理由は以下のとおりです。

  • 自由にデザインできるものがよかった。CSS組版で作成した本がわりと好みのデザインだった。
  • ブロガーなのでそこそこCSSはわかる。LATeXはわかりにくい情報を結構見かけた。
  • vueを使っていたため、nodo.jsとnpmがすでに入っていた。rudyなどを追加でいれたくなかった。
最初、知りたい情報はぐぐっても、Twitterをみても一部ないものやちょっとわかりにくいものがありました。でも、一度できてしまえば、あとは簡単ですかね。特に、Create Bookができたのち簡単になりました。最近、情報が増えてきましたかね。

markdown→html-[vivliostyle]→pdfをやる時のコツですが md→htmlはpandoc一択です –section-divsとヘッダにclassタグを設定できることを利用するとmdの特定の文法に場所によって違うcssを当てられるってのがだいじです

— ライアーノーズ (@liarnose) May 1, 2016

以前はmd → Html → PDFを生成する流れでやっていたため、少々面倒だったのですが、Create Bookができたのち、mdをpdfにダイレクトに変換できるようになりました。pandocもインストールしたけどいらなく。

Vivliostyleの商用利用は?

ライセンス形態が気になりました。

AGPL ライセンスであることによって、ソースコードを改変して、別製品にしたりWebサービスに埋め込む場合には、改変したソースコードを開示する義務がありますが、Vivliostyle をそのまま利用して、あるいは、Fidus Writer など、Vivliostyle を利用している別のサービスを利用して、商用の書籍を制作することに何ら問題はなく、制限なしで Vivliostyle を印刷やPDF生成に使用することができます。

https://vivliostyle.org/ja/blog/2018/11/12/interview-by-fiduswriter/

Vivliostyleの環境構築で混乱

初回インストールした際に、過去情報もあって若干混乱しました。おそらく下記のように進化しています。

viola-savepdf

vivliostyle-savepdf

vivliostyle-cli

npm install -g @vivliostyle/cli

そうか、viola-savepdf の後継が vivliostyle-savepdf なのか。#Vivliostyle

— 某ZR(ざんねん🙃) (@zr_tex8r) August 31, 2019

その後、create bookができたようです。今ならcreate bookを調べてインストールです。

Vivliostyleの使い方

簡単に書いてみました。

スポンサーリンク

puppeteerとは

puppeteerという言葉がよくでてきます。

PuppeteerとはGoogleのメンバーが開発したOSSで、ChromeやChromium(vivliostyleのプレビューで使われている)のNodeライブラリです。

markdown-pdfの公式ダウンロード、Markdown Preview EnhancedのPDF変換時、そしてvivliostyleも。

現時点の CLI は CSS 組版と PDF 出力を実行するプラットフォームとして Chromium を利用している。これは puppeteer 経由で操作して をインストールすると puppeteer が定義したバージョンの Chromium を一緒にダウンロードする仕組みだ。

https://akabeko.me/blog/2020/11/vivliostyle/

つまり大元はみんな一緒のようです!やれることは似通ってくるかもしれません。

markdown-pdfやMarkdown Preview Enhancedとvivliostyleの違い

vivliostyleは本を作ることを目指しています。

  • 1番の違いに感じるのは、複数のmdファイルをPDF化できることです。
  • 章分けなどヘッダーの設定が充実しています(いまひとつのところもあります)
  • プレビュー機能もあります(これはMarkdown Preview Enhancedでもできますけど)
スポンサーリンク

Font AwesomeのPDF埋め込みはライセンス的に可能?

ちょっと気になったので。ここしか記載がないっぽいですね。可能ぽい。

Embed FA Free in documents. (e.g. .pdf, .doc, etc.)

https://fontawesome.com/license/free

stackoverflowにも質問がありました。参考になるかと。

技術同人誌の表紙の作り方

自分で描けるならクリスタがおすすめです。Adobeと違って買い切りなのでたまに描く人におすすめです。

外注化するならココナラやsukimaでしょうか。

ご参考になれば幸いです。

コメント

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