Vivliostyle で技術書を書いてみる

先日、会社の有志で技術同人誌を執筆しました。

この本は CSS で本の組版ができる Vivliostyle を利用しました。メンバーが執筆環境を構築してくれて、私は執筆原稿の markdown ファイルをコミットするだけで本ができて、とても便利なツールだなーと利用していました。

最近、技術書の原稿を書く機会ができたので、自分で Vivliostyle の執筆環境を作ってみようと思いました。今回は、その時の導入手順をまとめています。なお、前提として、nodenv などで node.js や yarn をインストールしている macOS の環境を想定しています。

Vivliostyle の環境を整える

techbook というディレクトリで作業を想定します。

% mkdir techbook
% cd techbook

yarn を使って、環境を作成します。

% yarn init
% yarn add @vivliostyle/cli
% mkdir manuscripts
% touch manuscripts/index.md
% open manuscripts/index.md
% yarn vivliostyle build manuscripts/index.md

これで最低限の環境ができました。

構成ファイル

このままでも執筆はできるのですが、いろいろ不便なので 構成ファイル を作成します。次のコマンドを打つと、構成ファイル vivliostyle.config.js が作成されます。

yarn vivliostyle init

私は、次のように構成ファイルを編集しました。

vivliostyle.config.js

module.exports = {
    title: '本のタイトル',
    author: '著者名です',
    language: 'ja',
    theme: '@vivliostyle/theme-techbook',
    entry: [
      'index.md',
    ],
    entryContext: './manuscripts',
    output: [
      './output/output.pdf',
    ],
    workspaceDir: '.vivliostyle',
    toc: false,
    cover: undefined,
    vfm: {
      hardLineBreaks: false,
      disableFormatHtml: false,
    },
  }

コマンドの定義

利用する vivliostyle のコマンドを package.json に定義しておきます。

package.json

{
  "scripts": {
    "pdf": "vivliostyle build",
    "open": "open ./output/output.pdf",
  },
}

これで yarn pdf で PDF の作成、yarn open で PDF が表示されます。

テーマをカスタマイズしよう

vivliostyle.config.js にて Vivliostyle が用意している技術書向けのテーマを利用しました。しかし、余白や柱の表示など、納品先のガイドラインにあわせて修正する必要があります。この既存のテーマをカスタマイズしましょう。

まず、このテーマを取得します。

yarn add -D @vivliostyle/theme-techbook

node_modules から @vivliostyle/theme-techbook を探して、theme/my-theme-techbook にコピーします。

そして vivliostyle.config.js でこのテーマを参照するように変更します。

vivliostyle.config.js

module.exports = {
    theme: 'theme/my-theme-techbook',

では、実際にテーマを変更しましょう。テーマの変更は css ファイルではなく、scss　ファイルを編集します。まずは必要なライブラリを追加します。

yarn add -D sass

themeをビルドするコマンドを定義します。

package.json

{
  "scripts": {
    "build-theme": "sass theme/my-theme-techbook/scss:theme/my-theme-techbook"
  }
}

これで、scss　ファイルを編集した後に yarn build-theme を実行すればテーマが変更されます。この手順はメンバーの書いたこちらの記事を参考にしました。

TextLint

執筆でもっとも重要なことは文章の正しさ、読みやすさです。文章校正は文章の知識や経験が必要で、素人が行うのは難しいです。そこで、校正ツールの TextLint を利用します。校正ルールに基づいて、文書を静的解析します。

yarn add -D textlint textlint-filter-rule-comments textlint-rule-preset-ja-spacing textlint-rule-preset-ja-technical-writing textlint-rule-prh textlint-rule-spellcheck-tech-word

フェーズに関するルールはテックブースターが提供する rules を利用しました。以上より、私はこのようなルールを作成しました。

.textlintrc.json

{
    "plugins": {
    },
    "filters": {
      "comments": true
    },
    "rules": {
      "preset-ja-spacing": {
        "ja-space-between-half-and-full-width": {
          "space": "always"
        }
      },
      "preset-ja-technical-writing": true,
      "spellcheck-tech-word": true,
      "prh": {
        "rulePaths" :["./prh-rules/media/techbooster.yml"]
      }
    }
}

つぎに、TextLint用のコマンドを定義します。

package.json

{
  "scripts": {
    "lint": "textlint ./manuscripts/"
  },
}

ただし、このままだと毎回コマンドを打つ必要があり、校正のたびに執筆が中断されて、効率が悪いです。そこで、私は Visual Studio Code を利用していたので、アドオン vscode-textlint を追加して、保存時に実行するようにしました。とても便利に使っています。

extensions.json

{
    "recommendations": [
      "taichi.vscode-textlint"
    ],
}

まとめ

自分で構成したことで、Vivliostyle の使い方が少し分かったような気がします。しかし、使っているとまだ設定が甘いと感じることがありました。同僚が構築してくれた技術同人誌の環境は快適だったので、有り難みを感じました。Vivliostyle の使い方をより理解して、単独でも技術書の良い執筆環境を構築したいと思うようになりました。