サマリ
OSSのAPI Referenceサイトを作るにあたり、TypeScriptからTypeDocを使って、しこしこドキュメントを作っていたのですが、サイト自体をDocusaurus v2で楽して公開したいなーと思ったのでやってみた記事となります。
なお、実際に下記の様なサイト(API Referenceの部分)がコマンド2発くらいで自動生成→デプロイできるようになります。
p5.toio - API Reference Site
https://tetunori.github.io/p5.toio/
前提と注意事項
すでにTypeScriptでビルドできる環境やソースコードがあり、TypeDocも導入済みの環境を想定しています。
以下は最小手数の導入方法を書いていますが、まずはご自分のサンドボックスリポジトリで色々いじくるのをお薦めします。
Docusaurus v2概要
DocusaurusはOSSのドキュメントサイトを簡単に作ることができるFacebook謹製OSSツールですが、現在正式版のv1と平行して、いろいろ改良中のv2が公開されています。(2020/05/23時点でまだα版です。v2.0.0-alpha.55)
今回は試用もかねて新しいバージョンを使ってみました。
Docusaurus v2をインストールする
基本はDocusaurusサイトの通りに導入することになります。一発コマンドが用意されているので、こちらで簡単にインストールできます。
npx @docusaurus/init@next init website classic
Docusaurus的にはフォルダ名は何でも良いのですが、後に使うツールのためにwebsiteフォルダとしておきます。classicはテンプレート名ですが、おまじないと思ってください。
この時点でもうサイトの立ち上げが可能です。一度立ち上げてみましょう。
cd website/
yarn run start
live-serverが自動で立ち上がり、ブラウザにテストサイトが表示されたかと思います。Docusaurus v2ではダークモードが標準サポートされていたり、モダンな感じにデザインされていますね。
TypeDocのプラグインをインストールする
さて、いったんDocusaurusから離れて、開発のルートに戻ります。
TypeDocではデフォルトの形式ですと、ドキュメントサイトの体裁で出力されます。嫌いではないですが、Global/Module/Class/Interfaceと少々冗長に感じる気がしており、見る方からすると直感的な構成にはなっていないと感じていました。
そこで、今回はTypeDocの出力をDocusaurus v2フォーマットのMarkdownとして出力してくれるプラグイン、typedoc-plugin-markdownを利用しました。小さいながら、今も活発に開発が続いているリポジトリなようです。
さて、インストールは下記のとおりです。
npm install --save-dev typedoc typedoc-plugin-markdown
Markdownとして書き出し
完了したら、さっそく、Markdownとして書き出してみましょう。
Docuzaurusへ静的ドキュメントとして読ませるためには、website/docsフォルダ以下にmdファイルを配置する必要があります。なので、typedoc.jsonなどで出力先を変更しておきます。
"out": "website/docs",
あとは、いつものtypedocの設定に加えて、プラグインオプションと、今回のmarkdownテーマオプションdocusaurus2をそれぞれ付帯してtypedocするだけです。
typedoc --plugin typedoc-plugin-markdown --theme docusaurus2
このコマンドを実行すると、指定したディレクトリ以下にhtml/jsではなく、mdファイルが並ぶことになります。とても簡単です。と同時に、Docusaurusのサイドバー上のメニュー表示を管轄するファイルwebsite/sidebar.jsが今回のmdファイルをappendしたうえで更新されます。
余談ですが、このappend、僕は不要なのでskipしたいのですが、--skipSidebarオプションがまだDocusaurus v2には非対応なようで、問答無用に上書きされます。Issueをみると、なんと、本日付けでPR→修正されているので、近日中にリリースされると思います。なので、必要な人は今からオプションをつけておくことをお勧めします。
さて、準備はこれで終わりです。最後にもう一度Docusaurusを立ち上げてみましょう。
cd website/
yarn run start
ちゃんと今回取り込んだドキュメントが表示できるようになっていますね。お疲れさまでした。体裁は・・・そんなに良くないけど、このコマンド数でしかもほぼ自動で変換してくれるなら御の字です！
必要に応じて、不要なファイルは表示しない様sidebar.jsを編集すると、無事に自分好みの公開が出来るようになります。
デプロイ
deployも簡単ですよー。GitHub Pagesなら、下記のコマンドを打てば、自動的にgh-pagesブランチにwebサイトとしてデプロイされます。
GIT_USER=<user> yarn deploy
Enjoy!