Docusaurusを選ぶべきか？

Docusaurus は使いやすいのか？

これは私が Docsaid でサイトを立ち上げて 1 年以上経った後、最もよく聞かれる質問の 1 つです。

答えは「はい」、ですが、使いやすい理由はあなたが思っているものとは少し異なるかもしれません。

なぜ最初に Docusaurus を選んだのか？​

実は最初に選んだのは WordPress.org でした。（意外でしょ？）

なぜなら、その知名度が高く、たくさんの人が使っており、エコシステムも完成して成熟しているからです。多くの機能がすぐに使えるプラグインとして提供されていて、SEO やソーシャルメディアのシェア、サイトマップなどが簡単に設定できます。さらに、WordPress のユーザーインターフェースは非常に親しみやすく、コードに不慣れな人にとっても、簡単に使い始めることができます。

でも、私はプログラムが書けるんです！

プログラムを書くことができるとき、それが時には呪いになることもあります。なぜなら、何も知らないときは、ネットのチュートリアルを見ながら進めるだけで、選択肢はあまりありません。

でも、他の選択肢があることを知ると、この選択が本当に正しいのか疑問を持ち始めます：これで本当にいいのか？

特に、あなたが「できる」ことを知っている場合、例えば：

• なぜ Markdown で記事を書けないのか？

  実は可能ですが、プラグインを追加でインストールする必要があり、開発者ツールのシンタックスハイライト、バージョン管理、メタデータの統合などが難しくなります。

  ---

• なぜ Git でバージョン管理できないのか？

  実は可能ですが、ほとんどの WordPress の変更はバックエンドから行われるため、Git に同期するのが難しく、しかも多くのコンテンツはデータベースに保存されており、ファイルではありません。

  ---

• なぜ外部 API を呼び出せないのか？

  実は可能ですが、CORS を回避したり、カスタム JS を書いたり、テーマを汚さないようにフロントエンドコードを注入する方法を考えたりしなければなりません。

  ---

時間を節約できたと思っているかもしれませんが、実際にはこれらの問題にもっと多くの時間を費やしていることになります。

これらの問題を解決する方法は、単純なプラグインで解決できるものではなく、結局は自分でコードを書く必要があります。

結局のところ、やはり自分でコードを書くのなら、WordPress は何のために使うのでしょうか？

さらに、WordPress のプラグインエコシステムも完璧ではなく、多くのプラグインはサードパーティーが開発しており、品質にバラツキがあります。一部はサイトのパフォーマンスやセキュリティに悪影響を及ぼすこともあります。

このやり取りの間、結局得をしたのでしょうか？それとも損をしたのでしょうか？

他に選択肢はないのか？​

自分のニーズをよく考えたとき、最も基本的なニーズは「記事を書くこと」だと気づきました。

記事を書くこと自体がそれなりの負担であり、さらにレイアウトツールに気を取られると、すぐに疲れ果ててしまいます。

だから、「記事を書く」だけでなく、「Markdown で記事を書く」ことが重要でした。これにより、私は内容に集中できるからです。レイアウトではなく。

Markdown ベースの静的サイトジェネレーターはたくさんあり、それぞれに得意分野があります。

インターネットで調べた情報をもとに、簡単に比較してみました：

Docusaurus​

1. 技術文書と多言語サイトの構築に最適： 「文書指向」や「多言語サポート」に優れており、開発文書サイトの選択肢としての地位を強化しています。
2. フロントエンドのインタラクションには一定の柔軟性があり、React の経験が必要： React フレームワークをサポートし、インタラクティブ性は一定の水準を達成していますが、学習曲線が急であり、フロントエンドに慣れた開発者に向いています。
3. 頻繁な更新と優れたバージョン管理統合、チームでの共同作業に適している： Git ワークフローを必要とするチーム開発に適しており、活発な更新頻度を誇ります。

Hugo​

1. 静的サイトのコンパイルが非常に速く、速度と効率を重視する人に最適： Hugo は Go 言語で構築されており、すべてのフレームワークの中で最速のコンパイル速度を誇り、迅速なデプロイが可能です。
2. アーキテクチャの柔軟性とプラグイン統合に強み： 高度なカスタマイズやデータソース統合をサポートしており、大規模なコンテンツサイトに人気があります。
3. 多言語とフロントエンドのインタラクションサポートが弱い、国際化や動的アプリケーションには向かない： これらの弱点により、Hugo は単言語のコンテンツサイトやブログ向けに適しています。

Jekyll​

1. 最も学習曲線が平易で、静的サイト初心者に最適： Jekyll の構文は簡単で、エンジニアリングのバックグラウンドがないユーザーでも GitHub Pages デプロイを迅速に学べます。
2. 多くの機能が平均的で、複雑なアプリケーションには適していない： デプロイや SEO は良好ですが、特に優れた点がないため、他のフレームワークに取って代わられる傾向があります。
3. エコシステムとメンテナンスの動向が低下しており、将来の拡張性が限られている： 他のフレームワークと比較して、更新頻度やコミュニティの活発さが明らかに減少しており、低メンテナンスの個人ページに適しています。

Hexo​

1. 中国語コミュニティが活発で、中国語ユーザーに最適： 国際的なサポートは限られていますが、中国語のリソースが豊富で、チュートリアルやテーマパッケージを簡単に見つけることができます。
2. 簡単に学べ、デプロイも便利で、執筆を主な目的とするユーザーに最適： Hexo は Node.js を基盤としており、JS に慣れたユーザーには非常にフレンドリーで、迅速なウェブサイト作成が可能です。
3. プラグインと多言語サポートが弱く、長期的な大規模メンテナンスプロジェクトには適していない： よりシンプルなブログや個人紹介サイトに向いており、多言語対応や企業レベルの文書管理には難があります。

Astro​

1. フロントエンドのインタラクションと現代技術の統合能力が最強： React、Vue、Svelte などの現代的なフレームワークをサポートしており、インタラクティブで静的なハイブリッドサイトの構築に最適です。
2. アーキテクチャの柔軟性が高く、データ統合能力が優れており、高度にカスタマイズされたプロジェクトに最適： 複数のデータソースからの取得や複合的なアーキテクチャのサポートが可能で、コンテンツ駆動型やデザイン指向のサイトに有利です。
3. 多言語やテーマのエコシステムはまだ発展中で、学習曲線は中程度： 国際化や即時使用可能なテンプレートを必要とするユーザーにとっては、まだ成熟していない部分があります。

それが私にどんなことをしてくれたのか？​

私は全てを試す時間がなかったため、既存の資料を元に Docusaurus を選びました。

• ドキュメント指向の設計で、サイドバーやパンくずリストが自動生成される
• 多言語サポートが内蔵されており、現在私のサイトは中国語、英語、日本語の三言語対応
• Markdown / MDX の執筆が簡単で、React コンポーネントを挿入可能
• デフォルトテーマが十分に使いやすく、大量のカスタム CSS は不要
• GitHub Pages でワンクリックデプロイが可能、自ホスティングに適している

もし私が最も満足している機能を挙げるなら、それは「MDX 執筆」だと言います。

React 開発者にとって、MDX を使って React コンポーネントを挿入する能力は、コンテンツ表示の柔軟性を大きく高めます。足りない機能は React コンポーネントを自作すれば済みます。

さらに、私はほとんど前端のパッケージング、最適化、ルーティング設定や多国語設定などの細部を処理する必要がありません。

全体的に見ると、Docusaurus は私のウェブサイトのニーズの約 80%を処理してくれ、残りの 20%は自分で書いた React コンポーネントや記事です。

どんな制限があるのか？​

Docusaurus はドキュメント型ウェブサイトやナレッジベースの構築には非常に便利ですが、使用中にはいくつかの明らかな制限や欠点もあります：

1. 高度にカスタマイズされた動的なウェブサイトには不向き

   Docusaurus は静的コンテンツ生成のために設計されたツールなので、大量の動的インタラクションやリアルタイムデータ更新を必要とするウェブサイトには適していません。例えば、EC サイト、フォーラム、会員システムなどには向いていません。動的レンダリング（SSR）、頻繁なデータインタラクションやバックエンド統合が必要な場合は、Next.js、Remix、Nuxt などのフレームワークの方が適しています。

   ---

2. React が唯一内蔵サポートされているフレームワーク

   Docusaurus は React と MDX 技術を使用しており、他のフロントエンドフレームワーク（例えば、Vue、Svelte、Angular）をネイティブでサポートしていません。もしプロジェクトチームが他のフレームワークに精通している場合や、将来的にフレームワークを切り替える際に大幅な変更を避けたい場合、Docusaurus は制約となります。

   ---

3. スタイルや UI の調整に制限がある

   Docusaurus は内蔵テーマを提供し、CSS のカスタマイズを許可していますが、ほとんどの UI 調整は、内蔵コンポーネントを上書きしたり、テーマを再定義したりすることでしか実現できません。大規模な UI カスタマイズやビジュアルスタイルの再設計が必要な場合、逆に大量の追加作業が発生する可能性があります。

   ---

4. プラグイン拡張が限られている

   Docusaurus のプラグインエコシステムは活発ではありますが、Gatsby、Next.js、Hugo などのより成熟したエコシステムと比較すると、Docusaurus のサードパーティプラグインは少なめです。もし公式やコミュニティが提供するプラグインがなければ、自分で開発する必要があり、技術的なメンテナンスコストが増加する可能性があります。

   ---

5. 大規模ウェブサイトの構築におけるパフォーマンス問題

   コンテンツの規模が非常に大きく（数千ページ以上）、Docusaurus のビルド時間が明らかに延びる可能性があります。コンテンツを追加または変更するたびに、サイト全体のコンテンツを再ビルドする必要があり、頻繁にコンテンツが更新されるウェブサイトでは、ビルド効率に大きな問題が生じることがあります。この場合、より成熟してパフォーマンスが最適化された Hugo の方が適している可能性があります。

   ヒント

   この問題は最近の V3.6.0 バージョンで改善され、ビルド速度が明らかに向上しました。詳細な使用感はコミュニティによって検証が必要です。

   ---

6. 一部の機能はサードパーティサービスで実現する必要がある

   Docusaurus は静的サイト生成に特化しているため、検索（例：Algolia）、コメントシステム（例：Disqus や GitHub Issues）、ユーザーログインやデータベース統合などは、サードパーティサービスを通じて実現する必要があります。ウェブサイト内部には内蔵解決策が提供されていません。

   ---

7. 学習曲線は React の習熟度による

   Docusaurus は Markdown ライターには非常に親切ですが、MDX を活用して React コンポーネントやカスタム機能を追加する場合、React や JSX に精通している必要があります。フロントエンドエンジニアでない人や初心者にとっては、学習の難易度が増す可能性があります。

---

全体的に、Docusaurus の最適な使用シナリオは、ナレッジベース、チュートリアルドキュメント、技術的なコンテンツウェブサイトを迅速に構築することです。それ以外のニーズがある場合、上記の制限がユーザーエクスペリエンスや開発効率に影響を与える可能性があります。

私の使用状況​

現在、私のウェブサイト「Docsaid」は Docusaurus を使って 1 年以上運営しています：

• 170 篇以上の論文ノートを執筆
• 繁体字中国語、英語、日本語の三言語切替対応
• blog、docs、papers、playground などのモジュールを含む
• 自分でバックエンドを組み込み、ユーザー登録・ログイン、API トークン発行機能を提供
• 20 以上の React コンポーネントを自作し、さまざまな記事の表示ニーズに対応

Docusaurus は万能ではありませんが、私のような「コンテンツ集中型」のサイトにとっては、今のところ最も手間がかからず、最も安定した解決策です。

結論：誰が Docusaurus に向いているか？​

私は以下のようなユーザーに Docusaurus を推奨します：

• 大量のコンテンツ指向サイトを構築したい人（技術ドキュメント、学習ノート、オープンソースマニュアル）
• 多言語対応をしたいが、複雑なサイト構造の維持は避けたい人
• 低いメンテナンスコストで迅速にサイトを立ち上げたい人
• React エコシステムを受け入れられる人（MDX/JS 設定）

私はこれからも Docusaurus を使い続け、Docusaurus の使用技術やコンポーネント拡張に関するノウハウをさらに共有していきます。もしどんな内容について Docusaurus で取り上げてほしいことがあれば、下のコメントで教えてください。優先的に記事にします。

ウェブサイト作成を楽しんでください。