📗

74thの技術同人誌執筆環境(Markdown+Vivliostyle+VS Code)

6 min read

これは Visual Studio Code Advent Calendar 2021 の19日目の記事です。

https://qiita.com/advent-calendar/2021/vscode

技術記事や、技術書を書くことが多数あります。技術書典11では、以下を執筆していました。

https://techbookfest.org/product/5873782252109824?productVariantID=4622977314324480

https://techbookfest.org/product/4548114826395648?productVariantID=4723763495043072

今も技術書典12に向けて、執筆を続けています。ここで使っているツールセットを紹介したいと思います。

CSS組版 Vivliostyle で Markdown をPDFにする

HTML&CSSで組版ができる Vivliostyle を使っています。

https://vivliostyle.org/

Vivliostyle は CLI ツールが提供されており、これを使うことで、執筆環境を簡単に整えたり、1コマンドでPDFをビルドできたりします。

https://github.com/vivliostyle/vivliostyle-cli

執筆環境を整えるには、Create Bookを使います。

https://github.com/vivliostyle/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 の拡張書式を使うことができます。

https://vivliostyle.github.io/vfm/#/vfm

VFMでは、図にキャプションを追加したり、図のサイズを調整したり、脚注を入れたりする機能を持っていて、それを中心に使っています。

Markdown 執筆の決まり

主に執筆は Markdown で記述しています。Markdownは句点「。」ごとに改行することで、gitで差分を確認しやすくしています。

Markdownで表現力が足りない部分(主に表など)には、直接HTMLを記述するようにしています。

Markdownのファイルは、章ごと(ヘッダーと、改ページを行う単位)に分割しています。

基本的な本としてのレイアウトはCSSで記述

Vivliostyle ではレイアウトはCSS(SCSS)で記述します。
Vivliostyleで使える技術同人誌用のテーマが公開されています。

https://github.com/vivliostyle/themes/tree/master/packages/%40vivliostyle/theme-techbook

このテーマをベースに、自分でアレンジを加えたものをずっと使っています。
設定例を紹介します。

段落ごとに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を使って作成しています。

https://marketplace.visualstudio.com/items?itemName=hediet.vscode-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を使って作成しました。ぜひこの執筆環境を体験してみてください。

https://techbookfest.org/product/5694331843248128?productVariantID=5747426480619520

https://techbookfest.org/product/5119162372325376?productVariantID=5656038049054720

https://techbookfest.org/product/4696850535809024?productVariantID=5428870601768960

https://techbookfest.org/product/5691779347120128?productVariantID=5564437123563520

Discussion

ログインするとコメントできます