Zenn
Closed12

Docusaurus v2 事始め

Docusaurus
tmd45tmd45

Docusaurus

https://docusaurus.io/

  • Facebook 製で もちろん React ベース
  • ドキュメンテーションは Markdown で行う（MDX 可, JSX component の埋め込みが可能）
  • ドキュメントサイトに特化してとにかく手軽に構築できることを目指している
    • 反面、標準機能以外のカスタマイズは基本的に JavaScript コーディングが必要
    • 逆にいえば JavaScript（React）が使いこなせればいかようにでもなるにはなる
  • ドキュメントは バージョン管理 、 多言語管理 が可能
  • ブログ機能も利用できる
  • 固定ページも作成可能（src/pages）
  • 検索機能も標準で Algolia Docsearch との連携ができるようになっている
    • Docsearch は無料だが Web クローラ方式なので、導入するドキュメントサイトが Web 上に公開されている必要がある

確認バージョン

2.0.0-alpha.75

tmd45tmd45

公式ドキュメントのボリュームもそれほど多くないし、一通り読めばわかるレベル 😋

JS ベースの静的サイトになるので、デプロイは Netlify などでおｋ（アプリケションサーバは不要）。
こういうの今はなんて言うのかな？

自分は jamstack.org の Static Site Generators で出会ったけど 🤔
https://jamstack.org/generators/

tmd45tmd45

ドキュメントの画像サイズを変えたいとき、Markdown の拡張としてサイズ指定する記法は用意されていないので、React コンポーネントとして書く。

![普通の画像挿入の Markdown 記法](./assets/image01.png)

<img
  src={require('./assets/image01.png').default}
  alt="サイズ変えたい画像"
  style={{ width: '300px' }}
/>
tmd45tmd45

Docusaurus そのもののウェブサイトで使われているテクニック（カスタムスタイルなどなど）は、GitHub 上の website ソースコードを直接見ればおｋ
https://github.com/facebook/docusaurus/tree/master/website

たとえばダークモードでのカスタムテーマとか、復数サイドバーとヘッダメニューの構成例とか。

tmd45tmd45

Algolia DocSearch が使えない場合の代替手段
ドキュメントがインターネット上に公開されてないときとか。ドキュメント量が多いと厳しいかも？

https://github.com/cmfcmf/docusaurus-search-local

検索フォームなどのコンポーネントは docusaurus.conf.js に plugins の利用設定をすれば自動で反映されるが、プレースホルダや検索結果がない場合のメッセージは以下のように Docusaurus の i18n 機能で翻訳を作る。

i18n/ja/code.json
{
  "cmfcmf/d-s-l.searchBar.placeholderWithoutVersion": {
    "message": "ドキュメントを検索..."
  },
  "cmfcmf/d-s-l.searchBar.placeholderWithVersion": {
    "message": "ドキュメントを検索... [{version}]"
  },
  "cmfcmf/d-s-l.searchBar.noResults": {
    "message": "一致する結果が見つかりませんでした。"
  }
}

難点

惜しいことに、検索フォームで日本語の変換確定（Enter）をすると検索が実行されてしまう挙動。
ASCII 文化圏製 OSS の Multi-byte あるある(´・ω・｀)

※Chrome でのみ発生する様子。Firefox では正常に動いた。

また indexBlog を false に設定しているが、blog の内容も検索結果に含まれており、ここはまだ謎。

動作確認

実際の検索は build された環境でしか利用できない（yarn start では動かない）。
ローカル環境で試したいときは yarn build & yarn serve で build リソースを動かすことで確認できる。

tmd45tmd45

MDX/JSX の仕様だが、Markdown でドキュメント記述しているときに <br> タグや <img> タグを直接書きたい場合、きちんと閉じるタグにする必要がある <br /> や <img src="..." /> のような形。忘れるとコンパイルエラーになる。

tmd45tmd45

Not Found ページのメッセージを変更したい、など。
i18n のために用意されている仕組みで可能。

@docusaurus/theme-translations モジュールから、翻訳対象のキーを探す。

例 「ページが見つかりません」で検索
node_modules/@docusaurus/theme-translations/locales/ja/theme-common.json
11:  "theme.NotFound.p1": "お探しのページが見つかりませんでした。",
13:  "theme.NotFound.title": "ページが見つかりません",

このキーに対して core.js で翻訳内容を定義、上書きしてやる。

website/i18n/ja/code.json
{
  "theme.NotFound.p1": {
    "message": "ページが見つからんよ"
  },
}

https://docusaurus.io/docs/i18n/introduction

反映はリアルタイム（yarn server の再起動不要）

ぺーじが見つからんよ

このスクラップは2022/09/08にクローズされました