【VSCode】vivliostyleのmarkdownでpdf/epub作成【初心者に優しい】

プログラミング学習

電子書籍作成のために、vivliostyleの覚書です。現在は簡単に導入できます。

他にも色々と試したので、そのうち加筆します。

技術同人誌のまとめ記事はこちらです。

vivliostyleのVSCodeで環境構築

vivliostyleのインストール

まず、vivliostyleのローカルリポジトリを作成しましょう。VS Codeを使っています。

  1. vivliostyle-booksというフォルダを作成する(このフォルダに本を入れていきます)
  2. File > New Windows
  3. File > Add workspace folderでフォルダの位置を紐づける
  4. node -v(node.jsがインストールされているか確認。インストールされていない場合、インストールが必要)
  5. npm create book mybook

最後は本の名前で必須のようです。指定しないとエラーがでます。

npm create book bookname
Ok to proceed? (y) y
? description description
? author name neru
? author email
? license MIT
? choose theme @vivliostyle/theme-techbook - Techbook (技術同人誌) theme

emailはちょっとよくわからず指定しませんでした。

MACのfinderでファイルを確認したい場合は次のコマンドです。

open .

のちのち画像ファイルなどを確認する際によく使うため覚えておくとよいでしょう。

vivliostyleでpdf作成

ディレクトリを移動してビルド。

cd bookname
npm run build

ビルドすると初回にnode_modulesが勝手に作成されます。

またHtmlとPDFが生成されます。

以上でできあがりです。

ここでおしまいにすると簡単に終わってしまったため、もう少し設定を解説していきましょう。

スポンサーリンク

vivliostyleの本の作り方

cssとmdファイルを割り当てを変更

まず、cssとmdファイルを割り当てを変更する方法です。同フォルダにsample.mdとsample.cssを作成し、次のように書き換えるだけです。

theme: 'sample.css',
entry: [
  'sample.md',
],

本のサイズ

サイズの設定も重要です。1ページに入るコードや画像の入り方が変わります。紙の書籍なら小さい方が持ち運びが便利などあるかもしれませんが、電子書籍は多少大きめの方が見やすいかもしれません。

A4でもよかったのですが、本っぽいB5にしました。A5はソースコードが中途半端に区切られたり、1ページに画像1枚しか入らなかったりしたため、やめました。面積が小さい気がします。

size: 'B5', // paper size.

表紙のサイズ

vivliostyle.config.jsで指定された画像のサイズを用意します。ただし、微妙にあわないことがあります。

marginおよび画像サイズを微妙に調整します。3mm下に足しました。

@page :first {
  background-color: #626262;
  margin: -4mm -2mm;
  padding-top: 4px;

  /* 表紙ページはページヘッダー/フッター無し */
  @top-left { content: none; }

  @top-right { content: none; }

  @bottom-center { content: none; }
}

ただし、画像サイズが大きいと2ページ目に画像が落ちてしまうので、注意しましょう。Webのカラム落ちのようなものです。

cover.mdを作成して、画像を貼るコードを一行追加するだけです。

![](images/cover.png)

目次の作り方

最初、1つのmdファイルで執筆していきました。

その際、現状把握のため目次を作る拡張があると便利です。

いくつかでていますが、最終的にmarkdown all in oneを使いました。あくまで仮の目次を作成するものです。

使い方はコマンドパレットでtableと打てば、それっぽいものがでてきます。保存すれば自動的に目次は追加されます。ただ、これは執筆中にどんな項目があったのか自分用に把握するためのものです。本番では消します。

8割型できたあとで、mdファイルをわけました。この辺りは好みで最初からきちんとわけてもよいでしょう。

そしてindex.mdを作成してvivliostyleの目次を作成します。cssも必要です。

<nav id="toc" role="doc-toc">

## 目次

### Part1 ●●編

- [リンク1](1-01.html)
- [リンク2](1-02.html)

### Part2 ●●編

- [著者](colophon.html)

</nav>

<nav role="doc-toc"> … </nav> で囲むブロック内に目次項目(本文中の各見出しへのリンク)のリストを入れます。

https://vivliostyle.org/ja/faq/#%E7%9B%AE%E6%AC%A1%E3%82%92%E4%BD%9C%E3%82%8B%E3%81%AB%E3%81%AF

ちなみに、中扉に目次を挟みましたけど、それは効かなかったです。。

テーマの作り方

割り当て変更のところでテーマに直接CSSを割り当てました。

しかし、フォントなどいろいろなものを管理する場合、任意の名前のフォルダ(今回はtheme-original)を作成してそのフォルダ名を指定する方法があります。テーマごとに管理する場合はこの方が便利です。

theme: 'theme-original',

階層を’@vivliostyle/theme-original’とするとうまくいきません。

theme-originalのフォルダ内にpackage.jsonを作ります。次のような指定をします。

{
  "name": "theme-original",
  "main": "main.css"
}

originalthemeのディレクトリ内に、CSSファイル(メインのCSSファイルからimportする他のCSSファイル)、画像、フォントファイルなどを入れることができます。

nameは規約的に大文字禁止です。

このような状態でbuildすると、thme: に指定したディレクトリが丸ごと.vivliostyle/themes/packages/ の下にコピーされるようです。

npm run buildはvivliostyle.config.jsがある直下で実行します。

ヘッダーとページ数の入れ方

@page {
    @top-center {
        content: "ヘッダー";
    }
    @bottom-center {
        content: counter(page) " / " counter(pages);
    }
}

どのような配置ができるのか仕様は次とおりのようです。

ページヘッダー/フッターを指定する@top-center@bottom-centerなど(ページマージンボックスという)は CSS Paged Media 仕様で次の 16 個が定義されています。

https://vivliostyle.github.io/vivliostyle_doc/ja/vivliostyle-user-group-vol1/shinyu/index.html

変数を使うと、もっと応用的なこともできます。

コードブロック(highlight.js,prism.js)

デフォルトのままではスタイルはないため、スタイルを用意する必要があります。調べたらprism.jsに対応しているようです。highlight.js,は公式サイトに記載がありませんでした。

ソースコードのシンタックスハイライトには Prism.js が使えます。

https://vivliostyle.org/ja/tutorials/configure-basic-elements/

JavaScriptが使えるようになり、Chart.jsなども利用できるぽいです。

JavaScriptが使えるようになりました

https://vivliostyle.org/ja/blog/2022/01/24/JavaScript-can-now-be-used-in-typesetting-by-Vivliostyle/

prism.jsの使い方はこちらです。

スポンサーリンク

vivliostyleで執筆環境の自動化

文章の校正を自動化するtextlintの導入

VS Codeを利用するなら文章の校正が自動でできるtextlintを導入しましょう。詳しくはこちらの記事にまとめました。

CSSを自動修正するstylelint

CSS組版なのでCSSをかきます。CSSを自動修正するstylelintが入っているとあとあと楽でしょう。

スポンサーリンク

vivliostyleのFAQ

vivliostyleはepubの作成はできるの?

案内がありました。

create-book と CLI の関係

create-bookをインストールすると、CLI は勝手に最新版がインストールされるようです。

"@vivliostyle/cli": "latest",

CLIをインストールすると、vivliostyle系のコマンドが使えるようになるはずです。

vivliostyle: command not found

vivliostyle系のコマンドがエラーになります。

book $ vivliostyle preview 1-00.md
bash: vivliostyle: command not found

解決方法は次のとおりです。

vivliostyle preview

公式サイトに記載がなかったのですが、textlintみたくnpxをつけないとダメみたいですね。このコマンドでプレビューできます。

book $ npx vivliostyle preview 1-00.md
🚀 Up and running ([ctrl+c] to quit)
✔ Built images/test.jpg

主にGoogleによって開発とメンテナンスが行われているChromium(クロミウム)が起動します。

mdファイル以外もできるようです。

vivliostyle preview index.html
vivliostyle preview https://example.com –user-style my-style.css
vivliostyle preview publication.json
vivliostyle preview epub-sample.epub –user-style my-style.css
vivliostyle preview manuscript.md –theme my-theme/style.css

https://docs.vivliostyle.org/ja/vivliostyle-cli

執筆初期の頃はMarkdown Preview Enhancedの方がちょっとお手軽な感じもするので併用しています。

gifやmp4などの動画の電子書籍を作りたい

実際に少しだけ試してみました。

GifはHtmlなら動きます。markdownは画像の貼り方と一緒のようです。

![](videos/test.gif)

つまりHtmlの電子書籍ならいける気がします。個人的に印刷しなければ、もうHtmlでいいんじゃないの?って思っているところもややあります。

PDFはGIFに非対応なんです。Adobe Acrobat Proは動画フォーマット(.movや.mp4)に対応しているようですが、容量などいろいろ課題があるようです。。

では埋め込みではなくリンクを次に考えますよね。ローカルリンクと外部リンクがあります。

また詳しく検証していないのでわかりませんがローカル環境の相対パスもやや問題がありそうです。

余談ですけどsurfaceさん、いろいろなことにお答えになるんですね😳

まあ、知っているかぎりGoogleよりマイクロソフトの方が顧客対応は丁寧な企業なんですけど…。

結局、画像にして外部リンクみたいなやり方が現実的なんですかね?

Vscodeの文字数のカウント

VSCodeの拡張があります。日本人開発のCharacterCountです。

CharacterCount - Visual Studio Marketplace
Extension for Visual Studio Code - 文字数をリアルタイムでカウントする、Visual Studio Codeの機能拡張です。

作者の説明はこちらです。

小説家のためのVisual Studio Code 拡張機能を作成しました - Qiita
Visual Studio Code で小説を執筆してGitHubで公開している8amjpです。 Visual Studio Code、いいですよねー。私は開発にも執筆にもこのエディタを愛用しております。 LinuxでもMacでもW...

他にも小説用の拡張はいくつかでていて文字数のカウントはできるようです。

Vscodeのアウトライナー

本を執筆するとなるとよく前後の順番でを入れ替える作業をします。

VsCodeは左のエクスプローラーに、アウトライナー機能を実はデフォルトで持っています。しかし、順番を入れ替えることができません。

ただし、秀丸のアウトライナーならできるため、コピペで貼り付けて入れ替えて元に戻すみたいな作業はしてもいいかもです。2つのソフトを跨ぎますが、コピペは一瞬なので。やっぱり秀丸は優秀。

秀丸はWindowsのソフトです。個人的にMacとWindowsのハイブリット環境のためいいのですけど。

VsCodeのアウトライナーの拡張は調べたのですが、それっぽいものは見当たりませんでしたね。順番を入れ替えられる方法があったら教えてほしいです。

スポンサーリンク

vivliostyleで作成した電子書籍をgithubで管理する

あらかじめリポートリポジトリの作成をしておきます。git remote add originのパスは作成したものを使います。

git --version // macの場合、gitはデフォルトで入っています。
git init // その位置をルートディレクトリとし、gitの隠しファイルが作成される。必要ならその前にcdで移動
git remote add origin https://github.com/username/progectname
git remote -v  // パスの確認
git push -u origin master //add、コミットしたのち、次のコマンド

githubの使い方はこちらの記事を参考にしてください。

md、vivliostyle.config.js、package.jsonなどはGithub管理にします。

vivliostyleでgitignoreがない!node_modules/の除外

git pushしようと思ったらpush対象がすごい。

node_modules/まで対象になっていたため除外します。

.gitignoreという空ファイルを作成。

.gitignoreはgithubの管理外のファイルを指定するものです。自動生成されたファイルなどは管理しなくても平気です。
node_modules/
themes/
*.html
*.pdf

作成する際にディレクトリがあっていないと除外されないため作る場所を確認しましょう。

テーマはオリジナルで用意するため除外しています。

.gitignore自体は除外せずpushした方がよいでしょう。編集者とチーム開発しているなら共有物とした方がよさそうです。stackoverflowなどを参考にしましょう。

The .gitignore file’s purpose is to prevent everyone who collaborates on a project from accidentally commiting some common files in a project, such as generated cache files. Therefore you should not ignore .gitignore, since it’s supposed to be included in the repository.

https://stackoverflow.com/questions/10176875/add-gitignore-to-gitignore/

vivliostyleのエラー

✖ Error: Cannot set property ‘end’ of null

mdファイルの中身がおかしいとこけるようです。

(node:36546) ExperimentalWarning: The fs.promises API is experimental
◡ Collecting build config(node:36547) ExperimentalWarning: The fs.promises API is experimental
✖ Error: Cannot set property 'end' of null

If you think this is a bug, please report at https://github.com/vivliostyle/vivliostyle-cli/issues
npm ERR! code ELIFECYCLE
npm ERR! errno 1

フォントエラー

CSSファイルのフォントファイルがないとビルドは通りますが、次のようなエラーがでました。

(node:37639) ExperimentalWarning: The fs.promises API is experimental
◡ Collecting build config(node:37640) ExperimentalWarning: The fs.promises API is experimental
✖ 404 http://localhost:13000/themes/assets/fonts/hannari/Hannari.woff2
✖ 404 http://localhost:13000/themes/assets/fonts/hannari/Hannari.woff

ひとまず最低限の文字にしてみましょう。

Error: ENOENT: no such file or directory

ビルド時にでます。

Error: ENOENT: no such file or directory

このエラーは簡単です。単にファイルがないだけです。

ファイルをリネイムしたとき、うっかりvivliostyle.config.jsを修正し忘れるとでます。リネイムしたとき、不要なHtmlファイルも削除します。

この状態でVS Codeを保存しようとするとワークスペース を設定しますか?みたいなおかしな状態になるため注意しましょう。

Vivliostyleの事例

このかたはVivliostyleですね。

参考になれば幸いです。

コメント

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