はじめに

ドキュメントを書くために Word 開いたり、図を描くために Excel 使ったりするのがあまりに嫌だと感じていたので、そろそろ VSCode ですべてをまかなう方法を考える。具体的には、以下の要件を満たせるといい。

• 入力形式
  • Markdown
  • 図
    • ER図
    • UML
• 出力形式
  • pdf

Markdown

これがないと生きていけない。
今回は、Typoraを導入した。VSCode 上で動作するマークダウンエディタ。

https://marketplace.visualstudio.com/items?itemName=cweijan.vscode-typora

インストールした状態で .md ファイルを開くと、マークダウンエディタが開く。
書き心地は Notion に似てる。プレビューとエディタが一体化しているかんじ。

Pdf としての出力も OK。

図

図を描く拡張機能を探す前に、ドキュメントで使う図の種類を大きくふたつに分けておく。

• イメージを共有するための、多少雑でもいい図

  • かんたんなフロー、画像など
  • 手軽にかけることが求められ、再度編集されることは少ない

• ドキュメントとして情報を共有するための、きれいにまとまっているべき図

  • ER図、サービスフローなど
  • 内容の整合性が高いことが求められ、比較的頻繁に編集される

今回は、それぞれのアプローチにあった拡張機能をふたつ導入する。

Draw.io

https://marketplace.visualstudio.com/items?itemName=hediet.vscode-drawio

Draw.io は、かんたんな図や画像編集を行うのに最適な GUI エディタ。以下のようなシンプルなフローを書くのにはとくに重用する。

拡張機能を使うためには、.drawio.png のつくファイルを作成する。ファイルを VSCode で開くと、GUI エディタが表示される。
このファイルは draw.io から編集できるうえ、表向きは .png ファイルとして機能するため、毎回エクスポートする必要がない。そのため、ファイルを画像フォルダに置き、先ほどの Markdown ファイルから参照してしまえば、かんたんに編集可能な画像を Markdown に含めることができる。

ただし、そのまま Markdown に投げ込んでしまうと、コピーが作成されてそっちが参照されるので更新できない。
これを回避するために、.drawio.png ファイルは VSCode 側から挿入する。

1. 「Edit in VSCode」 をクリック

2. さっき作成した .drawio.png ファイルを Shift を押しながら投げ込む

これで、 Markdown 上からさっき作成した図が直接参照できます。

もちろん、この状態から変更を加えれば、 Markdown 側も変更が反映されます。
（一度開きなおさないと変更が反映されないっぽくはありますが）