GitBookからDocusaurusに移行してはどうか？

[suin]

現状の執筆はSaaSのGitBookで行われていますが、GitBookをやめてオープンソースのDocusaurusに移行することを提案します。

動機

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

GitBookの問題点

• PDF出力するために年間40万円かかる
  • 日本語PDFが問題なく出力できるか不透明
• CIしにくい

Docusaurus移行後のメリット

PDF出力が可能

docusaurus-prince-pdfを用いてPDF出力ができる

CIで自動校閲が可能

GitHub Actionsと自動校閲ツールを組み合わせることで、自動的に誤字や表記ゆれを検出、場合によっては修正までできる。

• Prettier: サンプルコードの自動フォーマット
• textlint: 日本語の校閲

カスタマイズ性が高い

• GitBookと比べて、Docusaurusはカスタマイズ性が高い。
• DocusaurusはReactで作られていて、Reactでできることができる。
  • もちろんTypeScriptも利用可能。
• Docusaurusにはプラグイン機構もある。

ドキュメントの表現力が高い

• コードブロックの行ハイライト
• MDX
  • 実行できるサンプルコード

など。

ページ遷移が速い

GitBookよりワンテンポ速い

細かい改善

• h1, h2, h3などのヘッダーアンカーが中国語ピンインにならない
• ダークモードのサポート
• タグ機能

GitBookの不具合が解消される

• .gitbook.yamlのredirectsが効かない
• GitHubのPRをマージした後に、GitBookで編集するとインデックス型やマップ型のコード行が消える不具合
• GitBookエディターが日本語に十分に対応できてない

プルリクエスト時にCLAを求めることがしやすくなる

• 編集をすべてプルリクエストを通じてやるようにすれば、CLAが求めやすくなる。
• CLAの調査結果 - HackMD

Docusaurus移行後の執筆フロー

1. GitリポジトリをGitHubからローカルにチェックアウト
2. 執筆をコミット
3. GitHubにプルリクエストを作る
   • GitHub Actionsが走り校閲
4. プルリクエストをマージする (マージできるのは執筆会に良く来る人達でいいかと思う)
   • GitHub ActionsかVercelでビルドが走る
5. 公開

このフローのメリット

• 執筆会レギュラーメンバーじゃない人も同じワークフローになり、シンプル化。
• 誤字脱字修正者から執筆者へのレベルアップもしやすくなる。

Docusaurus移行後のホスティング先の候補

• GitHub Pages
• Vercel

Next.jsとDocusaurusの比較

• Next.jsのほうが自由度が高いが、開発コストもその分高い。
  • Docusaurusにはドキュメンテーションに特化したUIがあるが、Next.jsは自作する必要がある。
  • DocusaurusにはDocusaurusの使い方ドキュメントがあるが、Next.jsで作った場合は執筆者向けドキュメントを自作する必要がある。

移行までの流れ

アプリケーションの準備

1. ホスティング先を決める
2. Gitにdocusaurusブランチを作る
3. GitHub Actionsを設定する
   1. デプロイ
   2. 自動校閲
4. 執筆ワークフローに沿って、CIなどが実際に動作するか試す

コンテンツの準備

1. 編集を凍結
2. MarkdownをDocusaurus用に修正する

公開

1. docusaurusブランチをプルリクエスト
2. ホスティング先にデプロイされたことを確認
3. book.yyts.orgをホスティング先に振り向ける
4. GitBookとGitHubの連携を消す
5. masterブランチにマージ

Docusaurusのデモ

• 公開サイト https://docusaurus-demo-three.vercel.app/
• デモリポジトリ https://github.com/suin/docusaurus-demo
• プルリクエストの自動校閲のサンプル: feat: 🎸 型アサーションのページを追加しました。 suin/docusaurus-demo#1

[suin]

GitBookが最近UIをリニューアルしたところ、エディタが重すぎて編集がままならない状況が出てきました。Docusaurusのメリットが相対的にかなり強くなったと思います。