Migration to Docusaurus
サイトをリニューアルしました．そして、数年振りのブログ更新です． 自分のサイトを持つ意味があまりなくなってきている感じはし ますが、もはや学習も含めて新しいフレームワークを使ってみるテストになりつつあります．
Docusaurus
これまで、WordPressやMkDocs、Jekyllなどを使ってきました．今回は Meta(旧Facebook)製 Docusaurus v2 を使いました．
なぜ、Docusaurusにしたのか．
それはReactを使いたかったから．あとは、バージョン指定だったりAPIなどに対応したサイトも作れるということで試してみたかった．まだまだReactやらTypeScriptに慣れていないこともあって、Docusaurusを使う前にある程度学習したおかげか、ここまで作るのに4,5日程度でした．Jekyllで使っていたMarkdownは多少の調整は入ったものの、ほぼそのまま移行できているのであまり苦労はしなかったです．環境を構築できればかなり楽かなとは思います．まあ、それはどのフレームワークでも同じことが言えます．
ReactとMDX
やはり目玉はこの2つ React と MDX です． React はUIフレームワーク、 MDX はマークダウンの中に JSX を使用することができる機能です． JSXはJavaScriptの拡張構文で、JavaScript内にタグ構文をそのまま使用できます．今、 React や MDX という表示がありますが、まさにこれがReactコンポーネントです．ちなみに、 codeタグで囲むと、 React, MDX というようになります．このブログのソースファイルはマークダウン形式であり、Reactコンポーネントを使用できます．しかも簡単に．ただ、通常のマークダウンは MDX と互換がありますが、MDXは通常のマークダウンとは互換がありません．
Docusaurusで構築するときにReactコンポーネントを使って構築しなければならないかと言われればそうではないです．マークダウンファイルだけでも十分構築できます．今回のサイトではトップページのみ JSX で構築していますが、それ以外のものはすべてマークダウンを使っています．
静的サイトジェネレータとしての比較
個人的な所感に基づいて、以下のドキュメントサイトを生成するツールの使い分けみたいなのを書いておきます．
単にブログを書きたいなら
ブログサービスを使いましょう．静的サイトを使う理由がとくにないです．
ブログをマークダウンで書きたいけど、githubで管理したい
Jekyllを使いましょう．GitHubが標準でサポートしています．お手軽ですし、こだわりたいならテンプレートを使ってレイアウトを自分で構築してカスタマイズできます．
ドキュメントをマークダウンのみでWeb上に公開するなら
MkDocsを使いましょう．お手軽です． また、mdBookでも構いません． Nodeの環境があるなら MkDocs、Rust (cargo) の環境があるなら mdBook という感じでもいいです．どちらの環境もあってどうしようという場合は mdBook を使いましょう．
本のようなある程度まとまったドキュメントを公開するなら
もし、それがローカルではなくワールドに公開したいのであれば、 Zennのブックを使いましょう． Zennのブックなら、無料で公開していてもサポートでお金が入ってくることがあります．また、有料にすることもできます．SEOも強いので、検索で見つけやすいです．Qiitaではできないですし、なによりQiitaは規約で公開した内容がQiita側にも帰属することになります．
ローカルの場合や、Zenn以外の方法だと mdBookを使いましょう．mdBookは機能が他よりも劣っているように見えるかもしれませんが、本として執筆する最低限の環境は整っています．むしろ、余計な機能（Webでのインタラクティブなものなど）があると、実際に印刷するときに困ることになります．mdBookの印刷はブラウザの機能を使うことになりますが、1つのPDFとして出力できます．PDFでも出力したいということであれば mdBook がいいでしょ う．また、 mdBook は Rust のエコシステムの一部なので、メンテナンスがしっかりしていることもあります．
Notion
Notionはマークダウンの文法をサポートしていて、かつさまざまなブロックを使うことができるツールです．お手軽に公開することもできて便利です．私もずっと使っています．ブロックはReactコンポーネントと考えることもできます．ブロックを開発することはできませんが、多くのブロックがあったり、埋め込みブロックでウィジットという形で追加することもできます．1人だったり多人数であってもドキュメントを構築するツールとして Notion はありかなと思っています．ただ、ブログとか記事をNotionで公開するのは限定的なので、どこからかリンクするかサイトとしてデプロイするといったことをやったほうがいいです．また、ReactコンポーネントとしてNotionを使うこともできますので、Notionで原稿を書いてReactで表示するといったことも可能だと思います．
えっ、じゃあ Docusaurusは？
正直なところ、あまりオススメはしないです．用途もあまり思いつきません．恐らく Docusaurusで作るなら Next で作った方がいいよね、ということになるとは思います．もしくはそれ以外で Gatsby とか．Reactの公式サイトは Gatsby ですし、新しいReactのドキュメントサイトも Next みたいです．Nextなどに精通しているなら、そちらを使った方がいいです．では、あまり詳しくない場合、Docusaurusはどうかという話になると思いますが、日本語の解説がかなり不足しているので、余計につらいかなと思います．公式ドキュメントはもちろんありますが、あまりわかりやすいものではないです．また、対応状況ももはや保守という感じも否めません．標準で採用しているCSSフレームワークの Infima もまだ開発段階みたいですし．時間があるなら、Nextを覚えた方がいいのではと思ってしまいます．ただ、DocusaurusもReactに精通しているならアリかなとは思います．プラグインとか数は少ないように見えますが、それで十分とも言えなくもないです．あとはReactで構築してどうぞという感じ．もう少しいろいろいじったら、まとめて記事にするかもしれません．
さいごに
DocusaurusはドキュメントをReactで構築するフレームワークだと思います．どこにどのファイルを置くのか、どういうルーティング処理がされるのか、プラグインはどう実装するのか、そういったことが決まっているものです．あとはそれをベースにカスタマイズしていってね、というものですね．とくに最初はナビゲーション当たりが手こずる感じです．わかると大分サクっと作れるようになるのですが、ただ、今でもまだ完全には把握できていないです．まだ、導入したばかりなので探っていきたいところですね．それでは．