Headless document site generator
最近ドキュメントサイト生成ツールや静的サイトジェネレータをいくつか触ってみたがどれも不満が多くて困った。
具体的には、コンポーネントライブラリや #デザインシステム のドキュメントはそれ自身のコンポーネントで作ったほうがかっこいいんだけど、そういうことをしたい場合は Next.js などで完全な自由を得る形になり、その分初速とか手軽さが失われるという点に悩んでいる。 ドキュメントサイトの定番機能を一瞬で作れて、かつカスタマイズ性を両立した存在が欲しい。
docusaurus、docsify、11ty でドキュメントサイトを書いてみての感想と、そこから自分が欲しいとおもうものを整理したい。
CSS ライブラリを強制しないで欲しい
docusaurus は Infima という CSS ライブラリを前提にしている
カスタマイズする場合は Infima の CSS Variables を自分で定義する形になる
一応カスタム CSS は読めるが、読んでも Infima の提供するクラスや変数定義は bundle されてしまうっぽい?
CSS をカスタムできる場合にクラス名を強制しないで欲しい
docsify は楽チンで良いのだが、カスタマイズしようと思うとクラス名が決まってて内容だけ変えた css を書かないといけない
つまり、レイアウトに手は出せないが CSS だけ変えられると言った感じで片手落ち感がある
目次や検索機能が勝手についてきて欲しい
11ty を使うとカスタマイズがいろいろ簡単にできる
その代わり、ドキュメントサイトに必要な自動生成系(目次の自動生成とか)が弱い
問題は検索系。docusaurus もその他の静的サイトジェネレータも Algoria のアカウントをつくってトークンを発行しろと要求してくる
docsify は Algoria なしでも勝手に検索機能がついてきて体験が良かった
local search というらしい
あんまり本格的じゃなくていい、雑でいいからビルド時に incremental search 用の json や js も一緒に吐いてくれる感じが良い
これは 11ty 向けの incremental search プラグインを書けば部分的には解決しそう
ページのサイドバーとかもある程度自動生成できたいが、まぁ最悪 siteNav: [] みたいな配列に要素を手書きするのはやぶさかではない
docsify の _sidebar.md みたいなファイルでも良いよ
コードは勝手にハイライトして欲しい
syntax highlight の色はそんなに変えられなくて良い、PrismJS の提供するテーマから選べますでもまぁ構わない
コンポーネントのドキュメントはセルフホスティングしたいにしても、syntax highlight は業界標準で良いはず
ここまでの条件を一応満たせそうなのは Gatsby とかになる。
一方 Gatsby だと次の条件に合わないなーと感じている。
( optional ) ビルドシステムが可能な限りシンプル、あるいは存在を意識しないぐらいが良い
ライブラリのドキュメントの場合、ドキュメントサイトを同じリポジトリに置くかどうかという問題が存在する
別々にすればどんなツールでドキュメントを書いても良いことになるけど、そこまで本格的に公式サイトをやりたいケースは多くない
ライブラリのリポジトリに /docs ディレクトリを掘って済ませたいときもある
ただ自由にカスタマイズしたい時点でリポジトリ分けろという意見もまぁわかる
同じリポジトリに置いた場合、ライブラリそのもののビルドツールとドキュメントのビルドツールが同居することになる
一度 monorepo 内に docusaurus 置こうとしたら自分たちで使う webpack と docusaurus の webpack のバージョンが合わなくて困ったことがあった
うーんしかしカスタマイズしたいけど大げさにしたくないってかなりわがままな欲求だな。そんなことできるんだろうか。