74thの技術同人誌執筆環境（Markdown+Vivliostyle+VS Code）
これは Visual Studio Code Advent Calendar 2021 の19日目の記事です。
技術記事や、技術書を書くことが多数あります。技術書典11では、以下を執筆していました。
今も技術書典12に向けて、執筆を続けています。ここで使っているツールセットを紹介したいと思います。
CSS組版 Vivliostyle で Markdown をPDFにする
HTML&CSSで組版ができる Vivliostyle を使っています。
Vivliostyle は CLI ツールが提供されており、これを使うことで、執筆環境を簡単に整えたり、1コマンドでPDFをビルドできたりします。
執筆環境を整えるには、Create Bookを使います。
以下のコマンドでビルドするための環境が整います。
yarn create book <directory>
このコマンドでできた環境では、npmに付属するタスクランナーでビルドコマンドが組まれています。そのため、VS Codeでタスクの設定を行わなくとも、タスクの実行からタスクランナーとしてnpmを選択すると、VS Codeのタスクとして実行できるようになります。
執筆中は頻繁にPDFを作成し、ページ数が増えたことを喜びます。
VS Code の Markdown Preview の機能はあまり使わず、VS Code のエディタ上で閲覧、推敲しています。
Markdown の書式は VFM + HTML
Vivliostyle で利用できる Markdown には、Vivoliostyle Flavored Markdown（以下VFM）という Markdown の拡張書式を使うことができます。
VFMでは、図にキャプションを追加したり、図のサイズを調整したり、脚注を入れたりする機能を持っていて、それを中心に使っています。
Markdown 執筆の決まり
主に執筆は Markdown で記述しています。Markdownは句点「。」ごとに改行することで、gitで差分を確認しやすくしています。
Markdownで表現力が足りない部分（主に表など）には、直接HTMLを記述するようにしています。
Markdownのファイルは、章ごと（ヘッダーと、改ページを行う単位）に分割しています。
基本的な本としてのレイアウトはCSSで記述
Vivliostyle ではレイアウトはCSS（SCSS）で記述します。
Vivliostyleで使える技術同人誌用のテーマが公開されています。
このテーマをベースに、自分でアレンジを加えたものをずっと使っています。
設定例を紹介します。
段落ごとに1文字インデントしつつ、段落ごとに間は開けない設定
p {
text-indent: 1em;
margin-block-start: 0em;
margin-block-end: 0em;
}
章、節の見出し（文字を大きくして、下線を入れる）
h1 {
font-size: 2rem;
line-height: 1.2;
text-align: left;
border-bottom-width: 1px;
border-bottom-style: solid;
}
h2 {
font-size: 1.8rem;
line-height: 1.2;
margin-top: 2em;
border-bottom-width: 0.5px;
border-bottom-style: solid;
}
ページ右上のヘッダー
$page-margin-outer: 8mm;
$page-margin-inner: 12mm;
@page :right {
font-family: $font-family;
margin-left: $page-margin-inner;
margin-right: $page-margin-outer;
@top-center {
content: env(doc-title);
font-size: 10px;
text-align: right;
padding: 8mm 2mm 8mm 2mm;
}
@bottom-right {
font-size: 10px;
content: counter(page);
}
}
図は拡張子 .drawio.svg で編集可能な画像ファイルにする
図はすべて、VS Code内で、drawioを使って作成しています。
拡張子を、.drawio.svg にすることで、VS Codeで編集が可能で、かつそのまま Vivliostyle で読み込むことの可能な図の形式になります。
ファイルを作り始めるときには VS Code 上で、xxx.drawio.svg という空ファイルを作成します。
あと、執筆時はダークテーマが好きなため、黒背景で作業できますが、紙面は白であるため、設定でdrawioの中では白背景になるように設定しています。
// .vscode/settings.json
{
"hediet.vscode-drawio.theme": "Kennedy"
}
目次、奥付は HTML で作成
目次、奥付については、デザインが他のページと明らかに異なるため、VFMは使わず、HTMLを直接利用しています。
Vivliostyle ではリンクを作成すると、PDFであってもジャンプ可能になります。
目次の作成は一時スクリプト化していましたが、細かい調整とかしたくなるので、結局制作の最後にHTMLを改めて記述する形に落ち着いています。
vivliostyle のマニフェスト
雰囲気だけを掴んでもらえたらと思います。
ページ構成の異なる扉ページは別のCSSを当てる感じです。
// vivliostyle.config.js
module.exports = {
title: "VS Code デバッグ技術 2nd",
author: "Atsushi Morimoto (74th)",
language: "ja",
size: "A5",
// theme-techbook ディレクトリにあるテーマが展開され、theme-techbook/theme.css が参照される
theme: "theme-techbook",
entryContext: "./",
entry: [
// 扉ページと目次
{
path: "toc.html",
title: "目次",
// theme-techbook/theme_no_header.css を当てる
// カスタムレイアウトのページは、ビルド後のCSSのパスを指定しておくと動く
theme:
"./themes/packages/@vivliostyle/theme-techbook/theme_no_header.css",
},
"./articles/0_introduction/README.md",
{
path: "./articles/1.0_basic/README.md",
title: "第1部 デバッグ機能の基本編",
theme: "./themes/packages/@vivliostyle/theme-techbook/theme_top_page.css",
},
"./articles/1.1_basic/1.1.0_lead.md",
"./articles/1.2_debug_ui/1.2.0_lead.md",
"./articles/1.3_launch_json/1.3_launch_json.md",
// 第1部が続く
{
path: "./articles/2.0_technichs/README.md",
title: "第2部 デバッグ応用技術編",
theme: "./themes/packages/@vivliostyle/theme-techbook/theme_top_page.css",
},
"./articles/2.1_ut/2.1.0_lead.md",
// 第2部が続く
// あとがき
{
path: "./articles/9_ending/README.md",
theme:
"./themes/packages/@vivliostyle/theme-techbook/theme_no_header.css",
},
],
workspaceDir: "./work",
};
まとめ
- Vivliostyle を使いMarkdownからPDFを作る。
- Vivliostyle では VFM が使えて、図のキャプションや脚注が追加できる。
- 拡張子 .drawio.svg を使うと、drawioで編集可能かつ、Vivliostyleで読み込み可能な図として作成できる。
このVivliostyleでの環境は非常に快適で、最初に紹介した本以外にも、以下の本もVivliostyleを使って作成しました。ぜひこの執筆環境を体験してみてください。
Discussion