VSCode と Marp で A4 マニュアルを作成する方法

VSCode と Marp で A4 マニュアルを作成する方法

背景

PowerPoint や Word で資料を作成するのが苦手なので、他に何か良い方法がないものかと探して見つけ出した手段を紹介。

というか、PowerPoint はそもそもスライド作成ソフトなので、それで書類作成するのはナンセンスですよね？
Marp もスライド作成ツール？ ……はて？
Word で作ればいい？ ……ちょっと何言ってるかわからないです。
というか、Word も PowerPoint も画像やデザインまわりの UI が煩雑すぎて正直苦手。

ちなみに、本来のスライド作成においても Marp はかなり優秀なので、そのあたりは各自で調べてみてほしい。

メリット

• 画像以外、全てテキストだけで作成できる
• マウス操作で細かい操作が不要、各サイズなどは数字入力で調整できる

デメリット

• デザインの融通が効きづらい
• けっこうな知識が必要（ html, CSS, Markdown の前提知識はほぼ必須）

VSCode とは

Microsfot 社製の高機能テキストエディタ、あるいはコードエディタ（無料）。
主にプログラミングに使用される。

正式名称： Visual Studio Code
DLページ： https://azure.microsoft.com/ja-jp/products/visual-studio-code/

Marp とは

VSCode の拡張機能の一つで、Markdown記法（と CSS ）を用いてテキストベースでスライドを作成することを目的に作られたツール。

• Markdown記法
  軽量マークアップ言語の一つで、簡単に言えば、簡単な html を簡単に記述できる記法、つまり簡単。（参考サイト： Markdown記法 チートシート）
• CSS
  Cascading Style Sheets の略。Web サイトのデザインを記述するための言語。今回は、これを少しでも理解していることが必須。（参考サイト： あまりにも多い）

マニュアル作成手順

1. VSCode をインストールする

上記の DL ページから DL してインストール。
インストールできたら VSCode を起動。

2. VSCode に Marp とその他各種拡張機能をインストールする

起動できたら早速、拡張機能である Marp を導入したいところだが、その前、あるいは合わせてインストールしておきたい拡張機能がけっこうある。

VSCode を起動した状態で「ctrl + Shift + x」を押せば拡張機能のサイドメニューが開くので、そこから下記の拡張機能を検索し、見つけたら表示させて「Install」ボタンを押していってほしい。

• Japanese Language Pack for VS Code（日本語化パック）
  起動しておわかりだと思うが、VSCode は英語表記のみ。
  こういうテキストエディタって開発ツールだからか、なぜか拡張機能でローカライズさせられることが多いよね。
• Markdown All in One
  Markdown記法を VSCode で記述する上で便利な機能が色々あるらしい。
  その色々な機能はここでは割愛するが、まあ入れ得なのでとりあえずインストールしておこう。
• Markdown Emoji
  Markdown で絵文字が使えるようになる拡張機能。
  絵文字が使えると何かと便利。
• markdownlint
  Markdown記法には 50 のルールが定められており、その文法チェックをしてくれる拡張機能。（参考サイト： Markdown 50 のルール）
  文法から外れると黄色い波線で教えてくれるが、外れていても実はそんなに問題ないことが多い。
  なので、煩わしいようならインストールしなくても構わないかと。
  ちなみに、lint とは（特にプログラミングなどにおける）文法のこと。
  ここではリントの言葉で話せ。
• Marp for VSCode
  （別に先にインストールしてても問題ないが）ここでようやく Marp の登場。
  説明は上記してあるので割愛。
  ちなみに、Marpit という独立したアプリケーションもあるらしい。
• Paste Image
  クリップボードにコピーされているスクリーンショットなどの画像ファイルを、そのまま編集中のテキスト内にペーストできる超便利拡張機能。
  通常 Markdown で画像を記述する際は、html と同じくファイル参照する必要があるのだが、この機能で画像をペーストすると、編集している Markdown ファイルと同じ階層のフォルダ内に自動で画像ファイルを保存し、そこから参照してくれるようになる。
  なお、保存名はデフォルトだと「年-月-日-時-分-秒」のような形式。もし不都合なら、保存先フォルダや保存名も設定で変えられる。

3. その他、あると便利なアプリケーションをインストールする

• Zoomit
  Microsoft社製のデスクトップ拡大表示ツール。
  PC 画面を拡大表示してくれるので、操作説明などにおいて非常に便利なのだが、デスクトップ上に手書きや矩形の赤線をオーバーレイで一時表示させる機能も備わっており、これがマニュアル作成などにおいてハチャメチャに便利。
  PC の操作説明マニュアルを作成する際、通常はスクショした画面上で操作してほしい場所を赤（あるいは何か目立つ色の）枠で囲んで際立たせる画像編集が必要だったりするのだが、正直これがかなり面倒。
  そこで逆転の発想としてコレ。
  このツールを使い、操作部分を先に赤枠で囲んだあとにスクショすれば、あとは貼り付けるだけでよく、編集が不要となるのだ。
  上記した Paste Image と併用すれば、かなりのスピードで画像挿入が可能となり、とてもおすすめ。
  参考＆DLサイト： Zoomit
• その他のツール
  • 切り取り＆スケッチ
    Windows 10 標準搭載のスクリーンショットアプリケーション。
    「Windowsマーク + Shift + S キー」でショートカット起動できる。
    選択域を矩形スクショできれば、正直これでなくても問題なし。
  • いずれかの PDF リーダー
    Marp で作成した書類は最終的に PDF 出力するので、確認用に。

4. マニュアルを格納するフォルダと Markdown ファイルの作成、それらと VSCode の挙動について

Markdown ファイルは、関連ファイルと同じフォルダで管理する

言ってしまえば、Marp は html ベースの Markdown テキストを無理やりスライド形式に落とし込んでいるようなものなので、html ファイルの作成時と同様に、専用の作業フォルダを（任意の場所に）作成する必要がある。
そして、そのフォルダ内に Markdown テキスト、CSS テキスト、画像ファイル、などをまとめて格納するのがわかりやすい。

画像ファイルの格納場所については好みが分かれそうだが、よくわからないという方はそのまま同じフォルダ内でも問題ないように思う。
というか、めんどくさいので自分はそうしてる。
ただ、長大なマニュアルを作成する際などはセクションごとに分けた方がいいかも。

フォルダの作成方法について

フォルダの作成は既知の方法でやってもらっても問題ないが、実は VSCode からでも可能。
「ctrl + shift + e」でエクスプローラーがサイドメニューで展開され、そこからフォルダの作成＆展開＆編集ができる。
今回は Markdown テキストだけでなく、CSS テキストも編集するため、ここから各ファイルを展開すると便利。
というか、サイドメニューのエクスプローラーからフォルダを展開しないと、フォルダ内のファイル同士が紐づけされないっぽい。

VSCode からフォルダを展開しなければならない

どういうことかと言うと、サイドメニューのフォルダを介さず単独で Markdown テキストを開いてしまうと、同じフォルダ内の CSS テキストなどをうまく認識してくれないようなのだ。（正直、ここは自分も仕組みがよくわからない）

なお、VSCode 下部に色の付いたステータスバーがあるが、サイドメニューからフォルダが展開されていれば、そこが青色になっているはず。
もし紫色になっていたら、単独で Markdown を開いてしまっている状態なので、サイドメニューからフォルダを展開するように開き直そう。

Markdown ファイルの作成について

色々な方法で作成できるが、メモ帳の「.txt」でメモったファイルをそのまま「.md」に名前変更する方法が一番やりやすいかも。
いずれにせよ、作成した「.md」ファイルはフォルダと同じく VSCode から展開する必要がある。

あと、フォルダ名とファイル名は同じ名称にした方が良かった気がするけど、理由が思い出せない……。

VSCode のプレビュー機能について

Markdown ファイルを作成し VSCode で展開したら、画面右側にプレビューを表示しておこう。
「ctrl + k」を押したあとに「v」を押せば表示されるはず。（画面右上あたりにプレビューボタンもあるので、そこを押してもOK）
試しに何か文章を入力してみれば、すぐに右側にも反映されるので、試してみてほしい。

5. Marp の設定について

Marp の有効化

VSCode にインストールした Marp の拡張機能を利用するには、Markdown ファイル内で Marp を有効化する必要がある。
有効化する方法は、Markdown ファイルの文頭に下記文章を記述するだけ。

---
marp: true
---

記述してプレビュー画面がスライド形式に変わったらOK。
また、この文頭の記述部分は「Directive」と呼ばれており、とても重要。

スライドを複数枚に分割する方法（区切り線について）

プレビュー画面にはスライドが一枚だけ表示されているはずだが、分割したい場所で --- を入力すれば、複数ページに分割することができる。
なお、区切り線としての --- は、上記した Marp の有効化で記述した --- とは別物なので注意。
それでは試しに、下記のように記述してみてほしい。

---
marp: true
---

# タイトル

---

## 見出し1

本文1

---

## 見出し2

本文2

---

タイトルスライドを先頭に、見出し1 と 見出し2 でそれぞれページが分割されていればOK。（この書き方なら markdownlint にも怒られないはず）

ちなみに、Markdown では本来 --- は「水平線」に変換されるコードであるが、Marp を有効化することによりページの区切り線に変わっている。
気になったら、文頭の Marp の有効化部分をまるっと削除してみるとわかりやすい。

スライドを複数枚に分割する方法 その2

--- 以外にもページを分割する方法がある。
見てもらえればわかりやすいので、一旦 Markdown を白紙に戻して下記内容を記述してみてほしい。

---
marp: true
headingDivider: 2
---

# タイトル

## 見出し1

本文1

## 見出し2

本文2

見出しごとにページが分割できただろうか。
このように Directive へ headingDivider という項目を追記することにより、見出しをそのままページ区切りにして分割することが可能となっている。
なお、headingDivider の数字と、見出しのコード「#」の数が連動しているので、ここを 3 とすれば「#」「##」「###」全てでページが分割される。

事前に Markdown で本文を記述していたら、この方法でページ分割した方が早い場合もあるので、状況に合わせて使い分けてみるといいかも。

Directive でスライドのページ設定をする

文頭の Directive ではスライドの基本的なページ設定を行うことができる。（詳しいデザインなどは CSS ファイルで行う）
なお、設定できる種類が多いので詳しい説明は割愛し、今回は必要な部分だけをピックアップしていく。
詳しく知りたい場合は 公式ページ（英語） や 有志の日本語解説ページ などを参照してほしい。

というわけで、今回のような A4 マニュアルを作る場合は、ほとんどのページデザインを CSS ファイルで行っていくため、記述すべき Directive は以下の 6つぐらいでよいかと。

---
marp: true
paginate: true
theme: A4-Manual
header:
footer:
backgroundImage:
---

marp を除いた各項目の内容は以下の通り。

• paginate
  true を指定すると、各スライド右下にページ番号が振られる。
• theme
  本来のテーマは 3種類（default, gaia, uncover）のみだが、自身で作成した CSS ファイルをテーマに設定することもできる。今回は「A4-Manual.css」というファイルを作成し適用させるので、この CSS ファイルと同じ名称を入力してある。なお「.css」の手前までの名称でOK。
• header, footer
  文字列を入力することでヘッダーとフッターをそれぞれ設定できる。
• backgroundImage
  背景に画像を設定できる。

内容を見てわかるかもしれないが、この中でも実際に必須となるのは marp と theme のみなので、必要最低限の A4 体裁を整えたいだけなら、他は削っても問題ない。
（paginate はあっても良さそう、headingDivider も好みによるか）

また、ここに記載されていない項目を追記しても（基本的には）問題はない。

6. Markdown でマニュアルの本文を記述する

Markdown記法 チートシート を参考に本文を記述してもらえればOK。
ただし、上述したように --- という水平線のコードだけは、ページ分割に役割が変わっているため要注意。

また、Markdown は html に基づいている記法のため、実は本文中で html を使うこともできる。（markdownlint さんに怒られるので個人的には非推奨。ここではリントの言葉で話せ）

7. CSS でマニュアルのデザインを記述する

本文の記述と CSS ファイルの作成は前後してもいいし並行しても問題ない。
ただ、ある程度は本文ができていないとデザインのプレビュー確認ができないので、おおまかなアウトラインだけでも記述しておくと確認がしやすくなる。

なお、CSS の名称は前述したように Markdown で適用させるオリジナルテーマと同じ名称にする必要があるので、今回は「A4-Manual.css」という名前でファイルを作成してほしい。

加えて、以降は CSS の知識を前提として要所のみをピックアップして解説していくつもりだが、自身も相当 CSS の知識があやふやなので、より適切な記述方法などがあれば、逆に教えてもらえると嬉しい。

CSS のオリジナルテーマが適用されるように VSCode の設定を変更する

VSCode で「ctrl + ,」と押すと、VSCode の設定画面を開くことができる。
開いたら、設定の検索窓に「marp theme」と入力。
すると、Marp のオリジナルテーマを追加する項目が表示されるので「項目の追加」をクリック。
入力欄に「A4-Manual.css」と入力したら「OK」を押して完了。
これで、 Markdown に A4-Manual という CSS ファイルが適用できるようになる。

CSS ファイル冒頭の記述

今回作成する A4 マニュアルにおいては、冒頭部分を以下のように記述するとよいかと。

/* @theme A4-Manual */

@import 'default';

section
{
  width: 210mm;
  height: 297mm;
  justify-content: start;
  padding: 50px;
}

Markdown のみを記述したプレビュー画面を見てお気づきだと思うが、Marp では 4:3 の横画面サイズ（スライド準拠）がデフォルトになっている。
なので、A4 サイズになるように設定している記述がこちらに当たる。
各項目の内容は下記の通り。

• /* @theme A4-Manual */： 作成中の CSS を Marp へ適用させるオリジナルテーマとして「A4-Manual（任意の名称）」を定義。（Marp の Directive で 入力した theme と同一のもの）
• @import 'default';： Marp の通常テーマである default を流用する宣言。
• section： CSS における section とは少し違い、Marp においては一つのページ全体を指している。
• width, height： section（ページ）のサイズを設定する項目。A4 の縦横サイズを入力してあるが、他のサイズでも入力可能。
• justify-content： コンテンツを配置する基準位置を設定する項目。何も設定しないとデフォルトの center になってしまうので start がよい。
• padding： 余白の設定。ここでは上下左右全て 50px に設定してある。

文章系要素のデザイン

特に自由にデザインしてもらって大丈夫だが、文字サイズだけはデフォルトが大き過ぎるので個別で設定した方がいいかと。
デフォルトだと 30px ぐらいなので、最小を 16px ぐらいにすると読みやすい。

画像要素のデザイン

正直、Markdown 記法においては画像の微調整が一番難しいように思う。
サイズ変更はともかく、個別の配置については html で CSS のセレクタ指定をしなければいけないからだ。
なので、Markdown 本文に html を記述することに抵抗がなければその方法で微調整が可能だろう。
（個人的には Markdown 記法ならではのシンプルさが失われれてしまうので非推奨）

装飾について

Markdown 本文への html 記述に抵抗があると、CSS による装飾は更に難易度が高くなる。
Markdown では、空のボックスなどが記述できないからだ。
なのでもう、基本的にはできるだけ複雑な装飾やデザインは想定せずに作成することをおすすめしたい。

とはいえ、もしどうしても必要になった場合は CSS の疑似要素である ::before や ::after を使用すれば、多少はデザインの幅を出すことができるので、あとは各自で工夫すると良いだろう。

8. PDF で出力する

「ctrl + shift + p」を押すとコマンドパレットが開くので「export」と入力する。
検索候補に「Marp: Export Slide Deck...」と出てきたら、それをクリックするだけ。

まとめ

あとで知ったことだが、このようにドキュメントの体裁を整える作業のことを「組版処理（くみはんしょり）」と呼ぶらしく、その組版処理を行うためのテキストベースシステムとして LaTeX（計算式や図表の表現が得意で論文執筆向き）というものもあるらしい。
ただ、けっこう複雑かつ古めのシステムとのこと。Marp の勉強も無駄ではないはず。

というわけで、WYSIWYG が苦手な方々は、ぜひ Marp で組版処理に挑戦してみてほしい。
そして、改善点などのフィードバックもあると嬉しい。

ちなみに、このマニュアルそのものも Markdown と Marp で作成しており、このサイトには Markdown のみをそのままコピペしてある。（ Directive とページ区切りの水平線のみ手動で削除したが）
つまり、今回紹介した方法なら Web とドキュメントの体裁をほぼ同時に作成できる、というのも強みかも。

追記

今回の内容を出力した PDF も Google Drive にアップロードしたので、下記 URL からご参考までに。
https://drive.google.com/file/d/1TP6RM2KHy3K2CvNET4vVDN2_UqZDDmOv/view?usp=sharing