ドキュメントの作成と画像の加工・管理も良い感じでやりたい(VSCode,draw.io,Markdown,Docusaurus)

# やりたいこと

- ドキュメント類をMarkdownで管理し、良い感じで見れるようにしたい
- ドキュメントに差し込む画像も一緒に管理したい、画像の加工(スクリーンショットに文字を入れたり)もしたい

# どうやるか

## 良い感じで見れるようにしたい → Docusaurus

Github等のリポジトリで管理してもいいですが、閲覧目的では少々使いづらいです。
かといって一からページを作るのも面倒です。
そこでDocusaurusというMeta社製の静的サイトジェネレータを使用します。

https://docusaurus.io/

標準でデザインが用意されており、今回の用途的にも標準のデザインで十分です。
というかめっちゃ見やすそうです。

## 画像の加工も管理もしたい → VSCode + draw.io

普段、図形の作成等は基本的にdraw.ioで行っていて、Google Workspace連携によりGoogle Driveで管理しています。
Google Driveからダウンロードして使用するのはめんどくさいなと思っていましたが、VSCodeでdraw.ioのエディタを利用できる拡張機能が公開されていました。

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

これを利用することで、VSCode内で図形の作成を行いつつ、図形はsvg形式で保存されている為Docusaurusでそのまま利用できます。
ブラウザでdraw.io描いてダウンロードしてローカルのフォルダに配置して・・・という作業が無くなり、めっちゃ良い感じになりそうです。

# やってみる

## Docusaurusの導入

※Node.jsやnpmはすでにインストールされている前提です。

[公式ドキュメント](https://docusaurus.io/docs/installation)に沿って進めます。

まずは任意のフォルダで以下を実行します。

```
npx create-docusaurus@latest my-website classic
```

できあがった`my-website`に移動して`npm run start`を実行すると、ローカルサーバーが立ち上がります。

![スクリーンショット 2025-01-07 120633.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/356430/ad8c6584-4a67-c374-b5d5-cfaae898f7a4.png)

表示されているURL(`http://localhost:3000/`)にアクセスしてみます。

![スクリーンショット 2025-01-07 120154.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/356430/fc6c6a1d-9b79-2cfb-406e-45eecec90b65.png)

めっちゃいい感じです。

## VSCode + draw.io拡張機能の導入

こちらについては特にコメントもないので詳細は割愛します。
公式サイトよりインストールを進めてください。

VSCode
https://code.visualstudio.com/

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

## 画像を加工して表示してみる

### 画像格納用のフォルダを用意

まず画像を格納する為のフォルダを作成します。
[ドキュメント](https://docusaurus.io/docs/markdown-features/assets)に従い、`docs`配下に`assets`を作成します。

![スクリーンショット 2025-01-07 121410.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/356430/f4d3edc7-2949-7b5f-6b1f-94f4325ac3ed.png)

### Draw.io Integrationで図を書いてみる

先ほど作った`assets`フォルダ配下に画像を作成していきます。
拡張子については色々書き方はあるようですが、今回は`.drawio.svg`を使用します。
ファイルを作成して開くと、VSCode内にdraw.ioのエディタ画面が表示されました。

![スクリーンショット 2025-01-07 122103.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/356430/c58fde4e-b745-b0fd-e12b-c78f728a8641.png)

本家と比べると多少制限はあるようですが、今回やりたいことは十分行えそうです。

![スクリーンショット 2025-01-07 122354.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/356430/fe9a4b59-641c-c132-8968-e0400a17886a.png)

なお画像の挿入についてはブラウザ版のようにドラッグ&ドロップではできないようでした。
スクリーンショットに文字や図形を入れるという作業が多いので少々痛手ですが、ローカルに落として配置するといった作業と比べるとかなり作業工数は減るのでよしとします。

### Docusaurusで表示してみる

先ほど作成した画像を保存し、ドキュメントに埋め込んでDocusaurusで表示してみます。
元から用意されていたサンプルのmdファイル`docs/intro.md`に以下の記述を追加します。

```markdown
![test](./assets/test.drawio.svg)
```

保存するとローカルサーバーにリアルタイムで反映されます。

![スクリーンショット 2025-01-07 123023.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/356430/2080c542-addd-92eb-1c07-74e942760f18.png)

draw.ioで作成した画像が、**何の変換作業を行うこともなく** 表示できています。
めっちゃ素敵です。

:::note info
Docusaurusのビルド時に`[WARNING] The image at "~.svg" can't be read correctly. Please ensure it's a valid image. unsupported file type: undefined`といった警告が表示されました。今回は一旦無視しています。
こちらの詳細は以下のissueを参照してください。
https://github.com/facebook/docusaurus/issues/9715
:::

# さいごに

VScodeで文章作成から画像加工まで完結し、1つのリポジトリですべて管理できるのはかなり魅力的な体験です。
Docusaurusはホスティングも楽に行うことができそうなので、マニュアルサイト等の管理・公開もかなり便利に行えるのではないでしょうか。
また機会があればやってみます。