Skip to main content

docusaurus-memo

背景​

散在したメモのまとめ先と、きれいに出力、検索しやすくする仕組み、などをずっと模索してきていたが、気がついたらこんなに便利な仕組みの既成のものがあったのか・・と知る。

VuePress も便利だったが、自分のなかでは Docusaurus がブレークスルーだった。

というわけで、これに情報を集約していくのだが、最初はどうしても、これ自体の機能を調べることやまとめ、に時間を割いてしまう。

練習としては良いか。ということで、まとめていく。

気に入った理由と、それぞれの使い方へのリンク​

1. Markdown 整形用として、すぐに使用できる​

Markdown で書きためたメモがいくつかあるなら、

  1. コマンドでプロジェクト作成
  2. 所定フォルダに、ありものの Markdown ファイルを突っ込む

これだけで、自分の書いた Markdown がブラウザ上にきれいに整形される。

フォルダ構成は左にメニューとして現れる。

→ [環境構築]

2. 公式ドキュメントとサンプルが充実している​

公式ドキュメントと、作成したプロジェクトの ひな型が、とても分かりやすい。

英語がさほど分からなくても、触りながら進められる。
カスタマイズも、理解不能な動作には なりづらい。

充実している、というと量に圧倒されそうな気もするが、
必要なところから書かれているので、最小限でスタートできる。(という工夫がなされているように思う)

3. 日本語表記と、URLの表記を分けて管理しやすい​

  • ファイルには [front matter] という仕組みを使って Markdown 単位の設定を記載
  • フォルダには [category.json] というファイルを使って フォルダ単位の設定を記載

こうすることで、

  • URLは英字のまま
  • メニューやタイトルは日本語にする
  • 辞書順でなく並び順を明示できる

といった運用がやりやすい。

詳しくカスタマイズするほどかゆいところに手が届くを実感。

4. 応用的なカスタマイズ方法も用意されている​

  1. [Swizzle] という仕組みを使って、各ページのカスタマイズ用テンプレートが用意される。
    • ここをカスタマイズしていくことで、広告を入れたり、フォルダ毎の自動処理を入れたりできる。
  2. npm を使用しているため、自分で書いた整形スクリプトなどをビルドの[前処理]として呼べたりする
    • フォルダ名からnode でもシェルスクリプトでも Python でも
  3. [カスタムコンポーネント] も作れるようになっている
    • 自作 HTML タグみたいなものを作れるということ

深堀りしがいのある作りといえる。

5. カスタマイズで React に触れていくことになる​

React 知らずに触り始めたものの、カスタマイズしていくうちに、React が分かってたらもっとスッキリ行けるんじゃないかという気持ちにさせられるわけで。

そんなところで見つけた 美麗な公式 React 入門ドキュメント・・。

https://ja.react.dev/learn

完全に入信しかけている感覚があります。

ジェーン・スーさん風に言うなら「Docusaurus は React のゲートウェイドラッグ」ですね。

といっても、悪い道へのゲートウェイではないので何の問題もなく、完全に「良い機会」なのですが。（あれ、この発言、もしかして既に盲信になってないか・・？ 眠くないときに見直してみよう・・）

Last updated on