VSCode でドキュメントをかくための環境を整える
よつはじめに
ドキュメントを書くために Word 開いたり、図を描くために Excel 使ったりするのがあまりに嫌だと感じていたので、そろそろ VSCode ですべてをまかなう方法を考える。具体的には、以下の要件を満たせるといい。
- 入力形式
- Markdown
- 図
- ER図
- UML
- 出力形式
よつMarkdown
これがないと生きていけない。
今回は、Typoraを導入した。VSCode 上で動作するマークダウンエディタ。
インストールした状態で .md ファイルを開くと、マークダウンエディタが開く。
書き心地は Notion に似てる。プレビューとエディタが一体化しているかんじ。
Pdf としての出力も OK。
よつ図
図を描く拡張機能を探す前に、ドキュメントで使う図の種類を大きくふたつに分けておく。
-
イメージを共有するための、多少雑でもいい図
- かんたんなフロー、画像など
- 手軽にかけることが求められ、再度編集されることは少ない
-
ドキュメントとして情報を共有するための、きれいにまとまっているべき図
- ER図、サービスフローなど
- 内容の整合性が高いことが求められ、比較的頻繁に編集される
今回は、それぞれのアプローチにあった拡張機能をふたつ導入する。
Draw.io
Draw.io は、かんたんな図や画像編集を行うのに最適な GUI エディタ。以下のようなシンプルなフローを書くのにはとくに重用する。
拡張機能を使うためには、.drawio.png のつくファイルを作成する。ファイルを VSCode で開くと、GUI エディタが表示される。
このファイルは draw.io から編集できるうえ、表向きは .png ファイルとして機能するため、毎回エクスポートする必要がない。そのため、ファイルを画像フォルダに置き、先ほどの Markdown ファイルから参照してしまえば、かんたんに編集可能な画像を Markdown に含めることができる。
ただし、そのまま Markdown に投げ込んでしまうと、コピーが作成されてそっちが参照されるので更新できない。
これを回避するために、.drawio.png ファイルは VSCode 側から挿入する。
- 「Edit in VSCode」 をクリック
- さっき作成した
.drawio.pngファイルを Shift を押しながら投げ込む
これで、 Markdown 上からさっき作成した図が直接参照できます。
もちろん、この状態から変更を加えれば、 Markdown 側も変更が反映されます。
（一度開きなおさないと変更が反映されないっぽくはありますが）
