Docusaurusを使った時の個人的ハマりどころまとめ

静的サイトジェネレーターの Docusaurus を使った際に、私がハマったポイントをまとめます。Docusaurus を使う皆様の参考になれば幸いです。

https://docusaurus.io/

前提条件

• 筆者のスキルは、WEB フロントエンド領域の興味はあるが知識がない状態です
• 動作検証をした環境は以下の通りです
  • Node.js v16.17.1
  • package.json は Docusaurus v2.1.0 で npx create-docusaurus@latest my-website classic を実行しただけの状態です

package.json

{
  "name": "my-website",
  "version": "0.0.0",
  "private": true,
  "scripts": {
    "docusaurus": "docusaurus",
    "start": "docusaurus start",
    "build": "docusaurus build",
    "swizzle": "docusaurus swizzle",
    "deploy": "docusaurus deploy",
    "clear": "docusaurus clear",
    "serve": "docusaurus serve",
    "write-translations": "docusaurus write-translations",
    "write-heading-ids": "docusaurus write-heading-ids"
  },
  "dependencies": {
    "@docusaurus/core": "2.1.0",
    "@docusaurus/preset-classic": "2.1.0",
    "@mdx-js/react": "^1.6.22",
    "clsx": "^1.2.1",
    "prism-react-renderer": "^1.3.5",
    "react": "^17.0.2",
    "react-dom": "^17.0.2"
  },
  "devDependencies": {
    "@docusaurus/module-type-aliases": "2.1.0"
  },
  "browserslist": {
    "production": [
      ">0.5%",
      "not dead",
      "not op_mini all"
    ],
    "development": [
      "last 1 chrome version",
      "last 1 firefox version",
      "last 1 safari version"
    ]
  },
  "engines": {
    "node": ">=16.14"
  }
}

バージョンによっては、異なる結果になる可能性があります

ドキュメントの最終更新日時・最終更新者は Git がある環境でのビルドが必要

Docusaurus では、ドキュメント (デフォルト設定では docs フォルダ内の .md, .mdx ファイル) に最終更新日時・最終更新者を表示させることができます。

この機能で表示する最終更新日時、最終更新者は Git のコミット履歴から取得されます。公式ドキュメントには記載されていませんでしたが、下記の Issue で明言されていました。

https://github.com/facebook/docusaurus/issues/2798#issuecomment-634374773

そのため、最終更新日時、最終更新者を表示させる機能を有効にする場合は、以下の対策を実施する必要があります。

• Git のある環境でビルドする
• CI 等でビルドする場合は、シャロークローンにならないような設定をする

私は、node-slim イメージ上でこの機能を有効にしてビルドしようとし、時間を浪費しました......
よく考えたら、最終更新者の情報はコミット履歴くらいしか情報の取得元がありませんね。

静的ファイルのファイル名に自動でハッシュ値が追加される

Dosusaurus では、静的ファイルのファイル名に自動でハッシュ値が追加されます。公式ドキュメントには画像ファイルを例にあげて説明されています。

https://docusaurus.io/docs/markdown-features/assets#static-assets

2. The image enters Webpack's build pipeline and its name will be appended by a hash, which enables browsers to aggressively cache the image and improves your site's performance.

ファイル名にハッシュ値を追加させたくない場合は、以下の手順を踏む必要があります。

1. ファイルを静的ファイル用のディレクトリ (デフォルト設定では static フォルダ) に配置する
2. ファイルへのリンクの URL に pathname:// をつける
   • 例 : static/assets/xxx.zip へのリンクは [ダウンロード](pathname:///assets/xxx.zip) のようにする

私は、static フォルダに配置したファイルのダウンロードリンクを作る際、このことに気が付かず苦労しました......
環境の制約がなければ、ダウンロードさせたいファイルはクラウドストレージなどに置いておくのがよさそうです。

Docusaurus 標準のコンポーネントは Swizzling しなくても文言の変更が可能

Docusaurus 標準のコンポーネント (例： Admonitions) の文言は、docusaurus.config.js の i18n を変更した場合でも訳されない場合があります。

その場合、docusaurus write-translations [siteDir] を実行し、i18n/code.json から該当するコンポーネントの message を変更すれば文言の変更が可能です。

たとえば、docusaurus.config.js の i18n の設定 を日本語に変更したとき、

  // Even if you don't use internalization, you can use this field to set useful
  // metadata like html lang. For example, if your site is Chinese, you may want
  // to replace "en" with "zh-Hans".
  i18n: {
    defaultLocale: 'ja',
    locales: ['ja'],
  },

Admonitions のラベルは翻訳されません。

公式ドキュメントの Admonitions を描画させた例

そこで、docusaurus write-translations コマンドを実行し、

$ npm run write-translations -- --locale ja

> my-website@0.0.0 write-translations
> docusaurus write-translations

[INFO] 64 translations will be written at "i18n/ja/code.json".
[INFO] 4 translations will be written at "i18n/ja/docusaurus-theme-classic/navbar.json".
[INFO] 10 translations will be written at "i18n/ja/docusaurus-theme-classic/footer.json".
[INFO] 3 translations will be written at "i18n/ja/docusaurus-plugin-content-blog/options.json".
[INFO] 4 translations will be written at "i18n/ja/docusaurus-plugin-content-docs/current.json".

i18n/code.json を以下のように変えると、

  "theme.admonition.note": {
-   "message": "note",
+   "meessage": "メモ",
    "description": "The default label used for the Note admonition (:::note)"
  },
  "theme.admonition.tip": {
-   "message": "tip",
+   "message": "ヒント",
    "description": "The default label used for the Tip admonition (:::tip)"
  },
  "theme.admonition.danger": {
-   "message": "danger",
+   "message": "警告",
    "description": "The default label used for the Danger admonition (:::danger)"
  },
  "theme.admonition.info": {
-   "message": "info",
+   "message": "備考",
    "description": "The default label used for the Info admonition (:::info)"
  },
  "theme.admonition.caution": {
-   "message": "caution",
+   "message": "注意",
    "description": "The default label used for the Caution admonition (:::caution)"
  },

Admonitions のラベルに変更が反映されます。

私は、なぜかこの機能は翻訳 API を使うときに利用するものだと思い込んでいました。そのため、Swizzling でコンポーネントの文言を変更しようとして時間を浪費しました......