サバイバルTypeScriptをDocusaurus v2からFumadocsへ移行することを提案します。
文脈
- 現在Docusaurus v2を使っている。
- Docusaurus v3に移行したい。
- v2→v3は結構な労力がいる。（破壊的変更があるため）
- どうせなら、Fumadocsへ移行もあり
概要
現在Docusaurus v3への移行を検討しています。しかし、v3は
- MDXのバージョンが違うことで、コンテンツの変更が必要
- 各種独自コンポーネントも改修が必要
など結構な労力が必要です。
また、Docusaurusについて満足しているかというとそうではなく、次のような課題もあります。
- ビルドが遅い （不満度=高）
- llms.txtやMarkdownソースファイルを提供できず、生成AIニーズに対応しにくい （高）
- Mermaidが使えない（高）
- フレームワークが独自なので、拡張しずらい（中）
- デザインフレームワークがtailwindなどポピュラーなものでなくカスタマイズしにくい（中）
- yarn classicでinstallが遅い（中）
- サイドバーの管理がグローバルなので数百ページある本プロジェクトでは管理しにくい（低）
どうせ苦労するなら、もっとモダンなツールに移行するほうがいいと考えました。具体的にはFumadocsです。Fumadocsは
- Next.jsベースで、扱える人も多い
- ISRが使えるのでビルド時間が短い
- LLMフレンドリーな機能がある
- ルックアンドフィールがモダン
- ZodやArkType、Zen Browserなど有名なOSSでも使われている
といった特徴があります。
移行のメリット
- ビルド速度の向上: FumadocsはNext.jsベースであり、Docusaurus v2と比較して大幅なビルド時間の短縮が期待できます。これは開発効率の向上に直結します。
- Next.jsとの高い統合性: Next.js App Routerとのシームレスな連携は、既存のNext.jsエコシステムとの親和性を高め、将来的な機能追加やカスタマイズを容易にします。
- LLMフレンドリーなコンテンツ管理: コンテンツをツリーデータとして扱えるため、生成AIによるコンテンツ活用が容易になります。llms.txtやMarkdownソースの提供に関する課題を解決できます。
- モダンな見た目とカスタマイズ性: 洗練されたデフォルトデザインに加え、Tailwind CSSベースのカスタマイズ性により、より柔軟でモダンなUIを実現できます。Docusaurusの独自フレームワークによるデザインの制約から解放されます。
- bun対応: bunによる高速なパッケージインストールとnode_modulesの容量削減は、開発環境の最適化に貢献します。
- 既存機能の継続利用: Algolia検索やShiki Twoslashといった現在利用中の主要機能は、Fumadocsでもサポートされており、スムーズな移行が可能です。
- Mermaid: MermaidをFumadocsはサポートしており、今まで図が書けなかった問題が解決します。
- ディレクトリごとの目次設定: ディレクトリごとにmeta.jsonを配置することで、目次が設定できるため、Docusaurusのsidebar.jsのように肥大化して管理がしにくいといったことが防げます。
既存機能は使えるか？
- Algolia検索: Algolia検索はFumadocsでもサポートされています。AlgoliaのAPIキーを設定することで、ドキュメントを検索できます。
- Shiki Twoslash: Shiki TwoslashはFumadocsでもサポートされています。コードブロックにTwoslashを適用することで、型推論やエラー表示ができます。
- PageRef: 移植する必要はありますが、機能的には可能です。
- PostILearned: 移植する必要はありますが、ほぼそのままで動くはずです。
- MDXv2: MDXv3への書き換えが必要。
- TypeScript解読アシスタント: LLMが登場したため不要になったと判断し削除します。
- OGP画像生成: 画像生成機能は別システムなので移行の必要はないです。
- twoslashの細かい点
twoslash include main: 要調査
- コードブロックの細かい機能
- 行ハイライト: 対応しているが、書き換えが必要？
- ファイル名表示(
title=): 書き換え不要で使える
:::tip: 書き換えが必要
サバイバルTypeScriptをDocusaurus v2からFumadocsへ移行することを提案します。
文脈
概要
現在Docusaurus v3への移行を検討しています。しかし、v3は
など結構な労力が必要です。
また、Docusaurusについて満足しているかというとそうではなく、次のような課題もあります。
どうせ苦労するなら、もっとモダンなツールに移行するほうがいいと考えました。具体的にはFumadocsです。Fumadocsは
といった特徴があります。
移行のメリット
既存機能は使えるか？
twoslash include main: 要調査title=): 書き換え不要で使える:::tip: 書き換えが必要