やりたいこと
- ドキュメント類をMarkdownで管理し、良い感じで見れるようにしたい
- ドキュメントに差し込む画像も一緒に管理したい、画像の加工(スクリーンショットに文字を入れたり)もしたい
どうやるか
良い感じで見れるようにしたい → Docusaurus
Github等のリポジトリで管理してもいいですが、閲覧目的では少々使いづらいです。
かといって一からページを作るのも面倒です。
そこでDocusaurusというMeta社製の静的サイトジェネレータを使用します。
標準でデザインが用意されており、今回の用途的にも標準のデザインで十分です。
というかめっちゃ見やすそうです。
画像の加工も管理もしたい → VSCode + draw.io
普段、図形の作成等は基本的にdraw.ioで行っていて、Google Workspace連携によりGoogle Driveで管理しています。
Google Driveからダウンロードして使用するのはめんどくさいなと思っていましたが、VSCodeでdraw.ioのエディタを利用できる拡張機能が公開されていました。
これを利用することで、VSCode内で図形の作成を行いつつ、図形はsvg形式で保存されている為Docusaurusでそのまま利用できます。
ブラウザでdraw.io描いてダウンロードしてローカルのフォルダに配置して・・・という作業が無くなり、めっちゃ良い感じになりそうです。
やってみる
Docusaurusの導入
※Node.jsやnpmはすでにインストールされている前提です。
公式ドキュメントに沿って進めます。
まずは任意のフォルダで以下を実行します。
npx create-docusaurus@latest my-website classic
できあがったmy-websiteに移動してnpm run startを実行すると、ローカルサーバーが立ち上がります。
表示されているURL(http://localhost:3000/)にアクセスしてみます。
めっちゃいい感じです。
VSCode + draw.io拡張機能の導入
こちらについては特にコメントもないので詳細は割愛します。
公式サイトよりインストールを進めてください。
VSCode
https://code.visualstudio.com/
Draw.io Integration
https://marketplace.visualstudio.com/items?itemName=hediet.vscode-drawio
画像を加工して表示してみる
画像格納用のフォルダを用意
まず画像を格納する為のフォルダを作成します。
ドキュメントに従い、docs配下にassetsを作成します。
Draw.io Integrationで図を書いてみる
先ほど作ったassetsフォルダ配下に画像を作成していきます。
拡張子については色々書き方はあるようですが、今回は.drawio.svgを使用します。
ファイルを作成して開くと、VSCode内にdraw.ioのエディタ画面が表示されました。
本家と比べると多少制限はあるようですが、今回やりたいことは十分行えそうです。
なお画像の挿入についてはブラウザ版のようにドラッグ&ドロップではできないようでした。
スクリーンショットに文字や図形を入れるという作業が多いので少々痛手ですが、ローカルに落として配置するといった作業と比べるとかなり作業工数は減るのでよしとします。
Docusaurusで表示してみる
先ほど作成した画像を保存し、ドキュメントに埋め込んでDocusaurusで表示してみます。
元から用意されていたサンプルのmdファイルdocs/intro.mdに以下の記述を追加します。
保存するとローカルサーバーにリアルタイムで反映されます。
draw.ioで作成した画像が、何の変換作業を行うこともなく 表示できています。
めっちゃ素敵です。
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はホスティングも楽に行うことができそうなので、マニュアルサイト等の管理・公開もかなり便利に行えるのではないでしょうか。
また機会があればやってみます。