メインコンテンツまでスキップ

0009-Docusaurusを採用する

  • ステータス: 採用
  • 提案者: @suin
  • 決定者: @suin, @jamashita, @t-yng
  • 更新日: 2021-10-16

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

背景

  • Amazonに電子書籍を出すため、eBook(ePub, mobi, PDFのどれか)を出力したい。入門書を探すとき、Amazonを検索する人が多いため。
  • CIで日本語の校閲やサンプルコードの自動フォーマットを行いたい。

GitBookの課題

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

Docusaurus採用理由

  • PDFが無料で出力可能。
  • CIによるコンテンツの自動校閲が可能。

検討した選択肢

  1. Docusaurus
  2. Next.js

各選択肢のよい点と悪い点

候補1: Docusaurus

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: 自前でホスティングする必要がある。

候補2: Next.js

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

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

関連PDR

📄️ 0001-GitBookで執筆する

このPDRは廃止されました。代わって次のPDRを採用します。
  • 質問する ─ 読んでも分からなかったこと、TypeScriptで分からないこと、お気軽にGitHubまで🙂
  • 問題を報告する ─ 文章やサンプルコードなどの誤植はお知らせください。