Docusaurusへ移行する

[suin]

背景

• PDF出力できるようにしたい
• CIで自動校閲できるようにしたい
• GitBookがバギーだったり重かったりするので脱したい

GitBookからDocusaurusに移行してはどうか？ · Discussion #38 · yytypescript/book

事前準備

• Vercelを課金する
• Vercelとリポジトリを連携する

準備

• GitBookをreadonlyにする。全員をReader権限に変更する。
• GitBookのGitHub Integrationを停止する。
• コンテンツを取り込む
  • docsディレクトリにMarkdownファイルを移す
    • node importFromGitbook/index.js .
    • rm -rf *.md overview reference tips tutorials writing .gitbook .gitbook.yaml
  • 移行スクリプトでMarkdownファイルの内容をDocusaurus用に書き換える
    • node importFromGitbook/updateContent.js
  • 執筆者向けの説明コンテンツを一部追加する
    • cp /Volumes/v/suinplayground/my-website/docs/writing/* docs/writing/
    • sidebar.jsに目次を追加する
  • MarkdownにPrettierをかける
    • yarn prettier:fix
  • 差分を確認しおかしなところを手修正する
  • 移行スクリプトで処理できなかった細かい修正
    • GitBook独自タグを書き換える ag '{%'で探す。
    • アンダースコアはじまりのファイルを、アンダースコアはじまりでなくする
    • バックスラッシュ
    • docs/reference/type-reuse/utility-types/record.md タイトルに謎のバックスラッシュ
  • ローカルでyarn build→yarn serveを試す

プルリクエスト

• プルリクエストを送る
• 動作確認
  • Vercel上で動作確認する
  • リダイレクトが効いているか確認する
• マージする
• 動作確認
  • /etc/hostsを書き換えて本番ドメインbook.yyts.orgをVercelに向ける
  • Vercel上で動作確認する
  • リダイレクトが効いているか確認する

公開手続き

• Vercelにカスタムドメインをセットする
• DNSの設定を変更して、book.yyts.orgをVercelに振り向ける

後処理

• GitBookの課金を停止する

その後のタスク

これらは別チケットでやる。

• PDRの「GitBookを使う」を廃止して「Docusaurusを使う」を書く #52
• textlintでエラーになるところを修正する #53
• markdownlintでエラーになるところを修正する #54
• ツイッターでシェアの部分をReactコンポーネントに置き換える #55
• 画像ファイルに適切なファイル名を与え、画像の置き場も適切にする #56
• importFromGitbookパッケージを消す #57
• その後のタスクを起票する

[suin]

Docusaurusへの移行が完了しました。