0009-Docusaurusを採用する

今まで執筆に用いてきたGitBookでは次の課題が生じた。これを解決すべくDocusaurusを採用する。理由は、次にあげる。

背景#

PDF出力するために年間40万円かかる。
CIが難しい。
最近のUIリニューアルで、エディターが重すぎて編集がままならない状況が出てきた。
その他の細かい問題点
- h1, h2, h3など漢字がヘッダーアンカーで中国語ピンインになる。
- GitHubのPRをマージした後に、GitBookで編集するとインデックス型やmapped typeのコード行が消える不具合がある。
- GitBookエディターが日本語に十分に対応できてない。

Docusaurusは、React製オープンソースのJAMStack型ドキュメント生成ツール。

Good: アップデートが継続していて、成長にも期待が持てる。
Good: 権威と実績がある。Facebookが開発し、ReactやJestなど多くのオープンソースのドキュメントに用いられている。
Good: PDF出力が可能。docusaurus-prince-pdfを用いてPDF出力ができる。
Good: CIで自動校閲が可能。GitHub Actionsと自動校閲ツールを組み合わせることで、自動的に誤字や表記ゆれを検出、場合によっては修正までできる。
Good: カスタマイズ性が高い。DocusaurusはReactで作られていて、Reactでできることができる。
Good: ドキュメントの表現力が高い。コードブロックの行ハイライトなど。
Good: ページ遷移が速い。
Good: 編集をすべてプルリクエストを通じてやるようにすれば、CLAが求めやすくなる。
Good: 執筆会レギュラーメンバーじゃない人も同じワークフローになり、シンプル化。誤字脱字修正者から執筆者へのレベルアップもしやすくなる。
Bad: 検索機能が弱い。特に日本語IMEで変換に十分に対応していない。
Bad: 自前でホスティングする必要がある。

Next.jsはフロントエンドアプリケーション向けのフレームワーク。静的サイト生成にも用いられる。

Good: アップデートが継続していて、成長にも期待が持てる。
Good: CIで自動校閲が可能。GitHub Actionsと自動校閲ツールを組み合わせることで、自動的に誤字や表記ゆれを検出、場合によっては修正までできる。
Good: カスタマイズ性が高い。
Good: ページ遷移が速い。
Good: 編集をすべてプルリクエストを通じてやるようにすれば、CLAが求めやすくなる。
Good: 執筆会レギュラーメンバーじゃない人も同じワークフローになり、シンプル化。誤字脱字修正者から執筆者へのレベルアップもしやすくなる。
Bad: UIを自作する必要がある。
Bad: Markdownからコンテンツページを生成するロジックを自作する必要がある。