背景
元々、gitbookやmkdocsなどでAPIのドキュメントを管理していたのですが、新しいサービスを制作するにあたって静的ファイルジェネレーターも新しく試すことにしました。
docusaurusは、いわゆる静的サイトジェネレーター(Static site generator)などと呼ばれるソフトウェアの一種で、多数のmarkdownファイルをまとめてメニューを生成し、一つのドキュメントサイトにしてくれるプロダクトです。
ライバルとしてはmkdocs、vuepress、docsify、slateなんかがあり、古いものだとgitbookなんかが有名です。
ブログ向きだけどHugoなんかも類似ソフトかな。
環境
Win10（サーバーはCentOS Stream8）
Node.js16.14
メリット
①オートジェネレート
デフォルトで「オートジェネレートモード」が有効になっていて、これがまぁ素晴らしく使いやすいです。
オートジェネレートは、ファイルやフォルダを自動で検知して、自動でリンクやメニューを作ってくれる機能で、これがあるだけでリンクを修正したりする手間が激減します。
しかも、プレビュー中にも自動反映される仕様で、その生成もまぁまぁ早い。
自動で作られたリンク名も、フォルダの場合は”_category_.json”という特別なファイルや、markdownもファイルの先頭にYAML Front-matterで”title”などを付ければ、好きなリンク名に変更したり並び替えたりできます。
古いタイプの静的ファイルジェネレーターはこれに対応してません。gitbookとか。mkdocsは調べたらpluginが出ているらしいですが機能は微妙でした。VuePressなどにも外部Pluginはありますが使い勝手は悪かったです。
まぁ、とにかくこれがすこぶる便利です。しかも公式デフォルト。神機能と言って差し支えないと思います。
②デザインが良い
デフォルトのデザインが見やすくて何もカスタマイズしなくて良いくらいに良いです。
gitbookやmkdocsなんかはちょっと野暮ったさがあったんですが、docusaurusのデザインはモダンで見やすいです。
③ファイル管理が優秀
私はVisual Studio Codeで「Markdown Paste」という、画像をコピペするとファイル保存してリンクを生成してくれる拡張機能を使用しています。これは非常に便利なのですがmdファイルの文書ごとにimagesディレクトリができ、各所に画像やコンテンツが分散して保存されるようになってしまいます。
しかし、docusaurusは全ての画像ファイルを収集してTOPディレクトリの/imagesに保存してくれます。
直接的な利便性にはかかわりませんが、これはスマートだと思いました。
デメリット
①埋め込みが使えない
Twitter、Instagram、Facebook、Youtubeなんかの埋め込みが貼り付けられない。Twitterは貼り付けられますがそのままではネイティブに表示されません。
これは正直かなり不便で、ブログ代わりに使ったらまず問題になる箇所だと思います。
わりとTwitterを引用してメモを取ることがあるので、不便極まりないと思いました。
埋め込みを使えないと画像が表示されない点が特に困ります。
Issueに投げてみたんですが、仕様とのことで対応する予定も無いらしいです。
ちなみに、mkdocsやvuepressはそのまま使えます。
一応MDXの構文に合わせれば使えるようですが、毎回書き換えるのも面倒です。
SNS embed script does not work (Twitter, Facebook, Instagram etc.)
https://github.com/facebook/docusaurus/issues/7149
②コンフィグが書きにくい
JavaScriptベースなので、module.exportsにコンフィグを書けとか、アレはそっち、コレはこっちと、いろいろな場所に設定を書かされます。
しかもbeta版が推奨されている状況なので、公式のコンフィグの書き方が古かったりと追いついていない。
デフォルトは特別な設定が有効になっているので、ナビゲーションバー（上にある親メニュー）の追加はハゲるくらいに分かりにくかったです。
まぁそのうち文書は整備されるでしょうけど、少し凝ったことをしようとすると困る可能性が高いです。
この辺はGitbookやmkdocsなどが分かりやすいと私は思っています。
③ファイル数が増えるとかなり重い
うちの文書はファイル数が300を超えているのですが、お陰さまで生成やプレビューが激重になっています。
buildに7分間かかり、メモリは2GB使用、CPUも100%に張り付きっぱなしとなりました。
ノートパソコンで文章を書いていると熱を持ちすぎて熱いことこの上ない。ひぃ！
ビルドくらいならCIを使えば良いんですが、プレビューまでだんだん重くなります。大量に文書があると厳しいと思った方がいいです。
④デフォルトの検索がクラウドベース
検索システムはクラウドサービスのalgoliaがデフォルトの検索で、しかもオープンソースじゃないと無料で使えず、インデックスの生成に時間がかかるのですぐにテストできません。
いやいや、デフォルトはローカル検索にしといてくださいよと。外部Pluginでローカル検索を有効にできますが、日本語非対応やら、デフォルトのディレクトリしか検索できないやら、使えるプラグインを探すのに苦労しました。
しかもそのローカル検索プラグインもcode blockが検索できないので、エラーログなどが検索できません。テキストにエラーログそのまま貼り付けるわけにもいかない。
というわけで検索系はかなり不便です。非オープンソースはお金を払うしか無いし、社内文書や個人文書の場合は我慢するしかありません。
総論
色々と書きましたが、はっきり言って、オートジェネレートモードが便利すぎるので、これだけでdocusaurusを選ぶ理由になります。
ファイルやフォルダを次々に作ったり削除したりするような使い方をするなら、docusaurus以外の選択肢はないと言っても過言ではないと思います。
これを体験すると他のプロダクトを使えなくなるぐらいには革命的で、頻繁に更新するような技術メモの場合は特にオススメしたいです。（まぁcode blockが検索できないですが）
一方で、埋め込みを使えないのは致命的だと感じました。
埋め込みを使う場合があるなら、選択肢には入らないと思います。
VuePressなんかでオートジェネレートPluginを使ったほうが良い体験ができると思います。
＃誰か埋め込みPluginと、ローカル検索Plugin作ってください
以上
コメント