こんにちは、製造業でソフト開発エンジニアをやっているとみー(@tommyecguitar)です。
会社で納品物の説明ドキュメントを作ることがあり、その時にMarkdownでの組版をやってみたので、どう運用したか、困ったところ、いい点、悪い点をまとめてみようと思います。
Vivliostyleで組版したブログはたくさんあるので、見た目がどんな感じにできるかなどはそちらを見ていただくか、Vivliostyleのサイトをご覧ください。
Wordじゃだめなのか。
製造業で何かしら長大なドキュメントを作るとなったら、大抵はWordを複数人数で編集するという運用をしているところが多いと思います。
しかし、Wordにはいろいろと悪いところがあります。
- チーム内で共同編集すると、編集したところが消えたり、フォントやデザインがなぜか統一されなかったりする。
- セクションごとに担当を分けても、マージが手作業になってしまう。
前者ですが、まずWordを共有設定をしてチーム内で同時編集を試みると、保存のタイミングとかのせいか、編集内容が消えるということが珍しくないです。また、Wordにはデザインを統一するための機能が一応備わっているのですが、どういうわけか途中で一部のフォントがおかしくなったり、色が変わってたりと、デザイン管理でかなりフラストレーションが溜まります。
では担当範囲ごとにファイルを分けて、後でくっつける運用をしても、マージが手作業になるうえにヒューマンエラーがゼロとはいきません。しかもさっきのデザイン的な問題がなぜかつきまとってきます。
こんなこともあり、Wordで長大なドキュメントを複数人数で編集するのは、余計な気配りを要して面倒!他に何かやりようはないの？？となったのです。
MarkdownはCSSでスタイル指定できる!マージもGitHubが使える!
そこでMarkdownに目をつけました。
Markdownとは、以下のような感じでタグと引数で文章を記述する手法で、記述のときはデザインとは関係なく、文章の構造だけを指定していくものです。(そういうのをひっくるめてマークアップ言語って言いますが、そのうちの一つですね)
# 見出し1
## 見出し2
### 見出し3
何もタグがなければ本文
[リンク名](リンクURL)
ただのMarkdownだとかなり味気ないデザインなのですが、VSCodeにはMarkdown Preview Enhancedなどの拡張機能があり、少し調べればデザインの編集も割と簡単にできてしまいます。
これであれば、編集者とデザインが完全に切り離されるので、構造さえきちんと書いてくれれば、デザインは後から統括管理できます。デザインがなぜか変わってしまうWordの悪いところはこれで解決です。
もう一つMarkdownのいいところは、GitHubなどでマージ作業ができることです。Wordはそれができないので手動マージになってしまうのですが、GitHubでできるとなればマージの時に文章の一字一句と睨めっこしなくても良くなります。
Markdown + Markdown Preview Enhancedがお手軽最強!?
まず調べたのはVSCodeの拡張機能で、Markdownの見た目をいじれるものがないかです。
その中で、一番良さげだったのがMarkdown Preview Enhancedでした。とりあえずこれでテスト原稿を書いてみたのが最初のチャレンジ。
この拡張機能はカスタムスタイルを指定できるようになっていて、CSSとかTailwindとかの知識が多少あれば、基本的なデザイン指定はできます。お手軽さはかなり高いですし、デフォルトで入ってるスタイルも結構いけてるので、そう言った意味では最強かもしれません。
ただMarkdownにも悪いところが、、、
そんなMarkdownですが、Wordと同じことができるかというとできません。例えば図にキャプションをつけるときや、図のサイズを調整したいとき、Markdownの記法では書けないので、Markdown中に突然htmlのimgタグを書かなければなりません。
それはそれでいいのですが、デザイン統括の意味ではその図にだけスタイルが反映されない可能性もあるので、できれば避けたいところです。
従って、htmlを直書きされても対応可能なスタイル指定拡張機能、あとできればMarkdownでキャプション・サイズ指定くらいは書きたい。
そこでVivliostyleを発見した。
調べると、世の中にはMarkdownで書籍を執筆する方がいるのを発見しました。
その中でもVivliostyleというツールを使う人が多かったので、導入を検討してみました。
記法はVFM
Vivliostyleでは、Markdownの歯痒い部分を解決すべく、独自スタイルのVFMという記法を採用しています。基本はMarkdownと同じなのですが、クラス指定が簡単にできたり、図のキャプションやサイズ指定がhtml直書きしなくてもできるようになっています。
(それで完璧というわけにはいかないですが、Wordの編集性に比べればマシ。)
# クラス指定はこうする{.class-name}
# idはこうする{#id-name}
SCSSでスタイル指定。しかもページごとにスタイルを変えられる。
詳しい使い方は公式サイトやいろんな人のブログを見ていただくとして、スタイル指定の便利なところ。
Vivliostyleでは基本的にチャプターごとにMarkdownファイルを分けます。そうしなければいけないわけではなくて、運用上それを想定してるっぽいです。
例えば、表紙・目次・本文と、デザインを分けたいということはよくあるでしょう。先ほどのクラス指定で分けてもまったく問題ないのですが、Vivliostyleでは表紙にはこのCSSを、本文には別のCSSをあてがうことができます。Markdown Preview Enhancedなど有名な拡張機能ではここまでのことはできません。
PDF出力が簡単
Markdown Preview EnhancedでもWordでも、PDF化の時に少しイラつきます。
- Word
- 画質が
クソ粗くされてしまうので、私の思う品質と大きく乖離がある。 - フォント埋め込みできないことがある
- svgが使えないので
クソ(最新版では対応しているようです。社内の人が全員アップデートしてくれていれば解決です。)
- 画質が
- Markdown Preview Enhanced
- 背景がエクスポートされないことがある
- フォントが置換されることがある
これに比べてVivliostyleは、今の所全ての問題をクリアしています。
まずは自分でやってみた
とりあえず自分も初使用なので、いろんなブログを参考にしつつ、Create Bookをやってみました。
このあたりの記事が参考になります。
Node.jsを入れる
Vivliostyleを使うにはNode.js 10.0以上が必要とのことだったので入れました。
これでnpmを使えるわけですが、最近はyarnの方がいいという情報もありましたので、
npm install -g yarn
とかで入れておきました。以降はnpmをyarnに置き換えても大丈夫です。
Vivliostyle CLIを入れる
以下のコマンドをターミナルに打ち込んでvivliostyleをインストールします。
npm install -g @vivliostyle/cli
Create Bookをする
ドキュメントを作りたいディレクトリに移動して、以下を実行すると必要なファイルを全部作ってくれます。
npm create book <directory>
設定を入力しろって言われますが、さっきの記事を参照してください。
ここでスタイルのテーマを選べと言われるので、好きなものを選んでおきましょう。アカデミック化techbookがいいのではないかと。僕はアカデミックのテーマtheme-achademicを使います。
テーマをコピーしてくる
カスタムテーマを作るには、デフォルトのテーマをベースにするのが簡単です。
デフォルトのテーマは./node_modules/@vivliostyle/theme-xxxxにあるので、ごっそりコピーして適当なところにペーストしましょう。ドキュメントのディレクトリ内のどこかにした方がいいですね。僕はドキュメントディレクトリの直下にしました。こんな感じです。
- book-directory
- node_modules
- theme-achademic(今コピペしたやつ)
- .gitignore
- LICENCE
- manuscript.md
- package.json
- README.md
- vivliostyle.config.js
- (yarnを使うとyarn.lockができる。)
これでとりあえずカスタムの準備は完了です。
Vivliostyleをチームで運用するには
ここからが正念場でした。
これをチームで運用するには、他の人も簡単に環境を作れるようにしなきゃいけないので、不要なファイルは消して、なるべく使いやすく整えないといけません。
フォルダ構成を見てみる
この時点のフォルダ構成はさっき記した通りです。
theme-achademicの中身はこうなってます。
- theme-achademic
- example
- scss
- CHANGELOG.md
- LICENCE
- package.json
- README.md
- theme_common.css
- theme_common.css.map
- theme_print.css
- theme_print.css.map
- theme_screen.css
- theme_screen.css.map
- vivliostyle.config.js
exampleには原稿用のMarkdownの例があり、scssにはscssファイルがあります。*.cssはそれらscssをcssにコンパイルした結果です。
ここで、CHANGELOG.md、LICENCE、package.json、README.md、vivliostyle.config.jsは親フォルダの内容とかぶっています。CHANGELOG.md、LICENCE、README.mdはドキュメント作成には関係ないので、特に必要なければ消してもいいやつです。
package.jsonとvivliostyle.config.jsは、親フォルダのものと内容が異なっています。
vivliostyle.config.jsはドキュメントを作成する設定ファイルなので、theme-achademic内のものはexampleから作成する用の設定、親フォルダのはmanuscript.mdから作成する用のファイルです。チームで作成したいドキュメントに設定ファイルは複数いらないので、最終的にはひとつでいいです。
package.jsonは、npmやyarnを用いて、書面生成に必要なパッケージを入れるための設定と、書類生成に使えるコマンドをまとめたようなファイルです。なにもパッケージを入れてない環境で、
npm install
とすると、package.jsonの内容を読み込んで、必要なパッケージをインストールし、node_modulesフォルダに入れてくれます。
ここで、親ファイルとtheme-achademicのpackage.jsonを比べると、theme-achademicに入ってるほうが多機能なので、そっちを流用しようと思いました。
よく考えるとtheme-achademic内のファイルで完結できるぞ。
ここまででわかるかもしれませんが、theme-achademic内のファイルだけで必要なものはそろっています。
ですので、せっかくcreate bookしましたが、全部消します。（笑）
設定をいじる。
親フォルダからtheme-achademic以外を全部消して、今はtheme-achademicがトップディレクトリです。
いらないファイルも消してこのようにしました。(cssはビルドしたら生成されるので必須ではない。)
- book-directory
- md(exampleの名前変更)
- scss
- package.json
- vivliostyle.config.js
おーシンプル
package.jsonをいじる
ここは人によるんですが、もし上のフォルダ構成を変えた場合、package.jsonの中の設定を変更しないといけません。特にbuildスクリプトのsass系のフォルダ名、filesの値などです。ここは人によるので頑張ってやってください。
vivliostyle.config.jsをいじる
ここは製本の設定なので、公式ドキュメントを見ながら設定してください。
READMEを死ぬほどこの上なく丁寧に書く
これは製造業だからこそだと思うのですが、Wordに慣れきっていて、ドキュメント作成にMarkdownなど使わない人が多いので、こうすればビルドできるよ!っていうのを死ぬほど丁寧に書きます。
幸いNode.jsを入れて、途中でnpm installをやってもらうだけなので簡単なほうでした。
GitHubにアップ!
この状態でGitHubで管理します。やったね。
Vivliostyleにも悪いところはある。
便利なVivliostyleにもまだ不便な点があります。
まだアップデートをする予定があるみたいなので、新しくドキュメントを作るときは確認した方がいいですね。
カウンタのリセットがやや大変
今のところの不便な点の一つ目は、カウンタのリセットが大変っていうところです。
チャプター番号や小番号をふるのにcssでカウンタの設定を書くと思いますが、番号をリセットする際に@pageで書くのかどうかで、正常に動いたり動かなかったり、、、
キャプションの記法がまだまだ
画像のキャプションは簡単になったのですが、表のキャプションはまだVFMにはないようです。
仕方がないのでhtmlを直書きするしかないです。
結局はMarkdownベースなので、ある程度はしょうがないと思って使っていくのがいいでしょうね