@vivliostyle/theme-academic でレポート書いてみた！

サンプルはこんな感じ

theme-academic は、Vivliostyle でアカデミックな文書を作るためのスタイルテーマです。現状、Create Book というツールを通して使うことができます。

theme-academic では、Markdown で構造化された文書を書くだけでいい感じにレポートらしい PDF が出力できることを目指しています。サンプルをいくつか紹介しましょう。

こんなレポートが CSS 組版で書けるなんてわくわくしますね！　特に表のスタイルなんかはこだわり甲斐がありそうです。では、実際にレポートを書いて自分好みにカスタマイズしてみましょう。

サンプルのレポートをビルドしてみよう

以下の環境を仮定します。

• Node.js: v14.8.0
• @vivliostyle/core: 2.1.1
• @vivliostyle/cli: 3.0.0-pre.3
• @vivliostyle/vfm: 1.0.0-alpha.10
• @vivliostyle/theme-academic: 0.2.0

まずは Create Book を使ってプロジェクトを作りましょう。簡単は流れは次の通りです。詳細は 『特集企画：Create Book で同人誌を作ろう！』の『Create Book を使うには』の章を参考にしてください。

1. npm create book お好きなプロジェクト名
2. テーマは @vivliostyle/theme-academic を選択

"Happy writing!" と出てプロジェクトが作成できたら、サンプルのレポートをビルドして PDF を作ってみましょう。vivliostyle.config.js の entry の部分を以下のように変更して yarn build すると、先程のスクショと同じ PDF が生成されているはずです。

entry: [
    // サンプルのレポート
    'node_modules/@vivliostyle/theme-academic/example/microcomputer.md',
],

余談ですが、yarn preview で立ち上がる Chromium の印刷機能で生成した PDF は、文字の選択とコピーなどができないようです。自分はこれを知らないままレポートを出して教員を苦しめてしまった実績があります……。yarn build で作られた PDF は文字が選択できます。

サンプルで学ぶ、基本の使い方

theme-academic では、レポートを書く際に必要と思われる基本的な要素をサポートしています。以下の表はその一例です。具体的な記法はサンプルのレポート（マークダウンで書かれたもの）をご覧ください。VFM の記法は https://vivliostyle.github.io/vfm/#/vfm にまとまっています。

基本的な要素	記法	出力（PDF）
見出し	GFM 準拠。.nocounter でカウンタを削除（例）
箇条書き	GFM 準拠。ol.nostyle ul.nostyle で箇条書きの記号を削除
参考文献リスト	ol.reference に HTML をそのまま書く（例）
図	VFM 準拠（例）
表	表キャプションが未実装のため、HTML をそのまま書く（例）。キャプション無しなら GFM 準拠
参考文献・図表カウンタの参照	VFM で仕様が決まっていないため、参照元に <a href="#id" data-ref="fig"></a>、参照先に <span id="id"></span> を書くことで代用（例）
後注	VFM 準拠
右・中央・左寄せ	.right .center .left
数式	KaTeX の記法が使える（例）
ソースコード	prism.js を使用（例）
囲み	.frame（例）
タイトル下の著者情報など	.author 内に箇条書き（例）
ヘッダー・フッターのテキスト	SCSS の $page-top-left などの変数で指定。後述
表紙の有無	SCSS の $cover 変数で指定。section.cover 要素が表紙になり、表紙はページ番号がつかない（例）。後述

スタイルをカスタマイズしよう

公式テーマのスタイルをどのようにカスタマイズすべきかは How to customize the style of themes? #9 で目下議論中ですが、現状できる筋肉解決的な方法のひとつに、テーマで使っている SCSS ファイルを編集する方法があります。面倒ですが、package.json と vivliostyle.config.js を以下のように変更し、yarn dev で SCSS ファイルをトランスパイルすればスタイルをカスタマイズできます。

$ yarn add node-sass npm-run-all

"scripts": {
    "build": "vivliostyle build",
    "dev": "run-p preview watch:scss",
    "preview": "vivliostyle preview",
    "watch:scss": "node-sass node_modules/@vivliostyle/theme-academic/scss/main.scss custom.css -w -r -q --source-map true --output-style expanded"
}

theme: 'custom.css'

たとえば node_modules/@vivliostyle/theme-academic/scss/variables.scss で定義された変数の値を書き換えることで、たとえば以下のようなカスタマイズができます。