Metabase の内部表現ドキュメントを NextJS で書き直した

Facebook 発のドキュメントフレームワーク docusaurus を使って Metabase の内部表現ドキュメント を公開していたが、脆弱性のアラートがいっぱい来るようになった。 docusaurus は素晴らしいライブラリだが、近頃はメンテが止まっていて依存関係のアップデートも難しいのでシンプルなもので書き直すことにした。

もともと docusaurus は Markdown + React な構成なのでフレームワークはそれに近しいことができる NextJS を選択した。 next markdown blog あたりでググって出てきたページを参考にした。

• https://tamalog.szmd.jp/next-markdown-blog/

作り直してみて、 docusaurus はファイルの読み込みやリンク、 Heading Link などかなり細かい部分まで面倒を見てくれていたことがよく分かった。 ユーザは Markdown を書くことに集中すればいい。

詰まったこと

パス解決まわり

/docs/section/item のようなパスを持つページがあったとして、 section と item がそれぞれダイナミックなルーティングのとき、そのままではパスを解決できなかった。 custom server を書くみたいなやり方はあるみたいだけど SSG では使えなさそうなので諦めて上位のパスをディレクトリとして用意してなんとかした。

# できるならこんな感じにしたい
pages
├── _app.tsx
├── docs
│  ├── [category]
│  │  └── [slug].tsx
└── index.tsx

# 実際
pages
├── _app.tsx
├── docs
│  ├── data-structures
│  │  └── [slug].tsx
│  ├── parameters
│  │  └── [slug].tsx
│  └── visualizations
│     └── [slug].tsx
└── index.tsx

本番デプロイ時の basePath

GitHub Pages のサブディレクトリとしてデプロイする関係で、本番ではリンクや asset のベースパスが開発中と異なる。 next の config に basePath, assetsPrefix, publicRuntimeConfig あたりを設定してある程度なんとかなったが、 本文の Markdown に書いてしまっているリンクは面倒だったので最終的に開発時を含めてすべて本番同様のパスにしてしまうことで解決した。

この辺りは docusaurus では特に意識せずにクリアできていた問題なのでもう少し丁寧に作ればなんとかなるのだろう。 独自の記法を導入して markdown をパースした後に変換するとかでもいい。