動機
チームのストック型のレビューが必要なドキュメント(手順書, 仕様書など)をGitHubで管理をするならどういうのがあるのか気になったので、OSSでよく使われてそうなDocusaurusを試してみた。名前かわいい
下調べ
Docusaurusの強みは、MDXが使えたりAlgoliaの検索が使えたり翻訳やバージョニングに対応してたりするのが強み。ただチームのストック型のドキュメントで考えると翻訳やバージョニングは不要かなと思う。OSSだと便利そう。
特にAlgoliaの検索が気になっていて、Docusaurusで作られているJestの日本語ドキュメントで試したところ良さそうだった。ただちょっと補完したときにEnterを押すとドキュメント選択したことになってしまうのでバグってそうだけどいざとなったらOSSなので自分で頑張れる。
ただAlgoliaのDocSearchがオープンなドキュメントを対象としているので、IPでアクセスを制限しているプライベートなドキュメントはOSSになっているdocsearch-scraperを使って自分でindexしてあげる必要がある。しかしログインが必要なプライベートページには対応していないっぽい。例えばGitHub PagesでprivateにしているとGitHubのログインが必要になるはずなのでダメそう。
しかもクローラーのOSS自体も2週間ほど前に新しいDocSearchがリリースされたことで非推奨になってしまった。まだ使えるとはいえ新しいDocSearchの仕様が変わったりしたら困るし、自前で頑張ればいいけどまあ…めんどくさいよね…
Migrating from legacy | DocSearch by Algolia
動かした
まあ、一応やってみるかということでやってみた。
以下を実行してprivate repoにpushしてNetlifyにデプロイした。すぐできる。Deploy to Netlifyもあったけどエラーになった。あとNetlifyは認証を使うにはお金がかかるらしいので試していない。
npx @docusaurus/init@latest init website classic
肝心のAlgoliaは、Netlifyと連携していてAlgolia Crawlerがまだ使えない人でもAlgolia Crawlerを使える。しかもpushするたびクロールしてくれる。
Quickstart for Using Algolia on Netlify
ただsitemap.xmlに記載されているURLが、/docs/tutorial-extras/manage-docs-versions で /docs/tutorial-extras/manage-docs-versions/ にリダイレクトされてIgnoreされる。
しかし、sitemapに記載されている /docs/tutorial-extras/manage-docs-versions を優先するのでリダイレクトされたあとのURLもignoreされるという悲しいことが起きてしまう。
これをどうにかしたかったけどsitemap生成するプラグインも設定がないようなので諦めた。
所感
結構期待して調べてたけど、まあサクッとはいかんなという感じだった。OSSには良さそう。
