このブログで利用しているフレームワーク（Docusaurus）をv2からv3へアップデートしてみました。

2024年12月29日

perapera

こんにちは、ぺらぺら(peraperavrc)です。

本日は、このブログのフレームワークをアップデートしたので、その過程を共有したいと思います。

Docusaurusについて

Docusaurusは、ブログやドキュメントサイトの構築に特化したサイトジェネレーターです。Reactベースで開発されており、高いカスタマイズ性を持つのが特徴です。

今回実施したv2.4.3からv3.6.3へのアップデートは、大規模な変更を含むメジャーアップデートでした。以下では、その具体的な変更点と対応方法について備忘録として残しておきたいと思います。

アップデートの動機

アップデートのきっかけは、pnpm startを本日実行したところ、メジャーアップデートがあることが分かりましたので、アップデートを行いました。

以下のコマンドを実行して、必要なパッケージを最新バージョンにアップデートします。

バージョンアップ手順

まず、Updating to Docusaurus v3により詳細なアップデート方法が記載されています。

Docusaurus v2とv3には、以下のような主な違いがあります。

MDXのバージョン: v2ではMDX v1を使用していましたが、v3ではMDX v3にアップグレードされ、より厳密なチェックが行われるようになりました。

Reactのバージョン: v2はReact v17を使用していましたが、v3ではReact v18が必要です。

パフォーマンスの向上: v3ではビルド速度が大幅に向上し、開発体験が改善されています。特に、ビルド時間の短縮が強調されています。

新機能の追加: v3では新しいプラグインやテーマが追加され、カスタマイズ性が向上しています。

1. パッケージのアップデート

私は、pnpmを利用していますので、pnpmコマンドを実行します。

npm
Yarn
pnpm

npm install @docusaurus/core@latest @docusaurus/plugin-content-blog@latest @docusaurus/preset-classic@latest @docusaurus/module-type-aliases@latest

yarn add @docusaurus/core@latest @docusaurus/plugin-content-blog@latest @docusaurus/preset-classic@latest @docusaurus/module-type-aliases@latest

pnpm add @docusaurus/core@latest @docusaurus/plugin-content-blog@latest @docusaurus/preset-classic@latest @docusaurus/module-type-aliases@latest

2. 依存関係のアップデート

インストールが終わると、"umet peer"というWarningが出ています。 docusaurus-react-warning

このWarningは、reactとreact-domのバージョンが古いことを示しています。

そのため、package.jsonを書き換えます。

package.json内の依存関係を手動で書き換えます。特に、ReactとReact DOMのバージョンを18にアップデートする必要があります。最終的なpackage.jsonは以下のようになります。

変更前:

{
  "dependencies": {
    "@docusaurus/core": "^2.4.3",
    "@docusaurus/plugin-content-blog": "^2.4.3",
    "@docusaurus/preset-classic": "^2.4.3",
    "@mdx-js/react": "^1.6.22",
    "prism-react-renderer": "^1.3.5",
    "react": "^17.0.2",
    "react-dom": "^17.0.2"
  }
}

変更後:

{
  "dependencies": {
    "@docusaurus/core": "^3.6.3", // v3にアップデート
    "@docusaurus/plugin-content-blog": "^3.6.3", // v3にアップデート
    "@docusaurus/preset-classic": "^3.6.3", // v3にアップデート
    "@mdx-js/react": "^3.0.0", // v3にアップデート
    "prism-react-renderer": "^1.3.5", // 後でアップデートをすることになるが、最初はこのままでした
    "react": "^18.0.0", // ここを18.0.0に変更
    "react-dom": "^18.0.0" // ここを18.0.0に変更
  }
}

これで

npm
Yarn
pnpm

npm start

yarn start

pnpm start

を実行をすると、まだ動きませんでした。

いくつか仕様が変わっているようです。とくにマークダウンのバージョンがMDX v1からv3に変わっていることが大きいようです。なので主にマークダウンの記述方法を変更します。

マークダウンの記述方法の変更

1. メタデータの修正

v3では、記事(mdファイル内でdraft: trueとunlisted: trueを同時に使用していた箇所がありエラーの原因となっていました。完全に非公開にしたい場合はunlisted: trueを削除し、draft: trueを残し、URLを知っている人のみアクセスできるようにしたい場合はdraft: trueを削除し、unlisted: trueを残します。

2. 改行に関するエラーの修正

MDX v3では、より厳密なチェックが行われるため、改行に関するエラーが発生する可能性があります。これは、MDXファイルの記述を修正することで解決できます。

これはキャプションが改行されていることが原因でした。

3. browserslistの設定

ビルド周りでエラーも出てしまっていました。package.jsonにbrowserslistの設定が原因でした。これを修正します。変更前:

"browserslist": {
    "production": [
      ">0.5%",
      "not dead",
      "not op_mini all"
    ],
    "development": [
      "last 1 chrome version",
      "last 1 firefox version",
      "last 1 safari version"
    ]
  },

変更後:

"browserslist": [
    "defaults",
    "Chrome >= 60",
    "Firefox >= 54",
    "Edge >= 15",
    "Safari >= 10",
    "Opera >= 46"
  ],

4. 続きを読む機能のエラー対応

v3では、続きを読むを設定していない記事で警告が表示されるようになりました。記事の適切な位置にタグを挿入することで、警告を解消しました。

記事内にを追加することで、「続きを読む」機能に関するエラーを回避できます。

ここまでで記事関係のエラーは解消しました。

実行環境などの追加の修正

アップデートのガイドが、Updating to Docusaurus v3に公開をされていまうが、最初はこちらをあまり読まないで進めてしまっていたため、こちらを参考にしっかりと修正をしていきます。

1. prism-react-rendererのアップデート

追記: 2024年12月29日ドキュメントなどのディレクトリではうまく言ったのですが、ブログのディレクトリの場合、prism-react-rendererがうまく動作しなかったため、最終的にはhighlight.jsを使用しています

prism-react-rendererは、コードのシンタックスハイライトを行うためのライブラリです。 v3では、このライブラリのアップデートについても記載されていました。

まずパッケージをアップデートします。

npm
Yarn
pnpm

npm install prism-react-renderer@latest

yarn add prism-react-renderer@latest

pnpm add prism-react-renderer@latest

次にdocusaurus.config.jsを修正します。

docusaurus.config.jsの修正:

// 変更前
// const lightCodeTheme = require("prism-react-renderer/themes/github");
// const darkCodeTheme = require("prism-react-renderer/themes/dracula");

// 変更後
const { themes } = require('prism-react-renderer');
const lightCodeTheme = themes.github;
const darkCodeTheme = themes.dracula;

2. Node.jsのバージョン指定

v2では実行環境がNode.jsの16以上でしたが、v3ではNode.jsの18以上が必要でした。 package.jsonにenginesフィールドを変更をして、Node.jsのバージョンを18以上にします。

"engines": {
    "node": ">=18.0"
}

確認

これでバージョンアップをしたら、

npm
Yarn
pnpm

npm start

yarn start

pnpm start

を実行してみます。変更点として、見栄えも変わっていました。

Docusaurus v2のデザイン

Docusaurus v3のデザイン

2024年や2023年に書かれた記事という形でカテゴライズされています。ちょっと新しくなった気がします。

アップデートに関しては、ここまでで終わりです。次に、この際なのでデザインのカスタマイズをしていきます。

デザインのカスタマイズ

ここまでできたので、デザインのカスタマイズをしていきます。

1. サイドバーとブログ内に表示される記事の一覧の調整

まずは、ブログの一覽とサイドバーに表示されている記事が少ないと感じたので、記事の数を増やします。今回、すべての記事を表示するようにしました。 docusaurus.config.jsに以下の設定を追加することで、ブログのサイドバーに表示される記事の数を増やすことができます。

module.exports = {
  // ...
  presets: [
    [
      '@docusaurus/preset-classic',
      {
        // ...
        blog: {
          // ...
          postsPerPage: "ALL",
          blogSidebarCount: 'ALL',
        },
      },
    ],
  ],
  // ...
};

変更点

2. ブログ記事一覽をカスタマイズ

ページの記事一覽がどうしてもブログサービスのようなかたちではなくて、記事本文が表示されてしまうので、カスタマイズします。カスタマイズをするためにカスタムのコンポーネントを利用をすることができます。

例として、docusaurus.config.jsでblogListComponentを設定することで、ブログ一覧ページで表示をするためのコンポーネントをカスタマイズできます。

module.exports = {
  // ...
  presets: [
    [
      '@docusaurus/preset-classic',
      {
        // ...
        blog: {
          // ...
          blogListComponent: require.resolve('./src/components/BlogListPage.js'),
        },
      },
    ],
  ],
  // ...
};

例えばこのように、BlogListPageというコンポーネントをカスタマイズします。

結果は、ブログのパスの部分がすべてこのコンポーネントになります。

swizzleコマンド

１からカスタマイズするのは大変なので、既存のテーマをカスタマイズするためのファイルを取得できます。 pnpm run swizzleコマンドを実行することで、テーマをカスタマイズするためのファイルを取得できます。

例えばこのコマンドを実行するとCLIと対話形式で、カスタマイズしたいコンポーネントを選んで取得できます。

npm
Yarn
pnpm

npm run swizzle

yarn swizzle

pnpm run swizzle

を実行します。指示に従って、カスタマイズしたいコンポーネントを選びます。例えば、BlogPostItemというコンポーネントをカスタマイズしたい場合は、BlogPostItemと入力します。

そうすることで、src/theme/BlogPostItem/にスクリプト（Reactコンポーネント）が生成されます。

必要なパッケージがあるのでインストールします。

npm
Yarn
pnpm

npm install @docusaurus/theme-common @docusaurus/utils-common

yarn add @docusaurus/theme-common @docusaurus/utils-common

pnpm add @docusaurus/theme-common @docusaurus/utils-common

これで先程生成された、BlogPostItemコンポーネントを編集することで、ブログ一覧ページのデザインを変更できるようになりました。

例えばフッダーやコンテンツ本文を消すとこの用になります。

あとはひたすらカスタマイズをしていきます。

これで、カスタマイズをした結果がこのようになりました。

かなりやりたかったデザインに近づけることができました。

まとめ

今でブログのカスタマイズはあまりしていないので、カスタマイズの方法を知ることができてよかったです。

v3では多言語化対応などもできるようになったとのことなので、そのあたりもカスタマイズしていきたいと思います。

この記事をシェアする