手動移行

この手動移行プロセスは、自動移行プロセスの後、不足している部分を補完したり、移行CLI出力の問題をデバッグしたりするために実行する必要があります。

プロジェクトのセットアップ

package.json

スコープ付きパッケージ名

Docusaurus 2では、スコープ付きパッケージ名を使用します

• docusaurus → @docusaurus/core

これにより、Docusaurusの公式パッケージとコミュニティが管理するパッケージを明確に区別できます。つまり、Docusaurusの公式パッケージはすべて@docusaurus/のネームスペースに属します。

一方、Docusaurus 1で提供されていたデフォルトのドキュメントサイト機能は、現在は@docusaurus/preset-classicによって提供されています。そのため、この依存関係も追加する必要があります

package.json

{
  dependencies: {
-   "docusaurus": "^1.x.x",
+   "@docusaurus/core": "^2.0.0-beta.0",
+   "@docusaurus/preset-classic": "^2.0.0-beta.0",
  }
}

ヒント

こちら（latest タグを使用）で確認できる最新のDocusaurus 2バージョンを使用してください。

CLIコマンド

一方、CLIコマンドはdocusaurus <command>（docusaurus-commandの代わりに）という名前に変更されました。

package.jsonの"scripts"セクションは、次のように更新する必要があります

package.json

{
  "scripts": {
    "start": "docusaurus start",
    "build": "docusaurus build",
    "swizzle": "docusaurus swizzle",
    "deploy": "docusaurus deploy"
    // ...
  }
}

典型的なDocusaurus 2のpackage.jsonは次のようになります

package.json

{
  "scripts": {
    "docusaurus": "docusaurus",
    "start": "docusaurus start",
    "build": "docusaurus build",
    "swizzle": "docusaurus swizzle",
    "deploy": "docusaurus deploy",
    "serve": "docusaurus serve",
    "clear": "docusaurus clear"
  },
  "dependencies": {
    "@docusaurus/core": "^2.0.0-beta.0",
    "@docusaurus/preset-classic": "^2.0.0-beta.0",
    "clsx": "^1.1.1",
    "react": "^17.0.2",
    "react-dom": "^17.0.2"
  },
  "browserslist": {
    "production": [">0.5%", "not dead", "not op_mini all"],
    "development": [
      "last 1 chrome version",
      "last 1 firefox version",
      "last 1 safari version"
    ]
  }
}

buildディレクトリへの参照の更新

Docusaurus 1では、すべてのビルドアーティファクトはwebsite/build/<PROJECT_NAME>内にあります。

Docusaurus 2では、これがwebsite/buildに移動されました。デプロイ設定を更新して、正しいbuildディレクトリから生成されたファイルを読み取るようにしてください。

GitHub Pagesにデプロイする場合は、yarn publish-gh-pagesスクリプトの代わりにyarn deployを実行してください。

.gitignore

website内の.gitignoreには、次のものが含まれている必要があります

.gitignore

# dependencies
/node_modules

# production
/build

# generated files
.docusaurus
.cache-loader

# misc
.DS_Store
.env.local
.env.development.local
.env.test.local
.env.production.local

npm-debug.log*
yarn-debug.log*
yarn-error.log*

README

D1ウェブサイトには既存のREADMEファイルがある場合があります。D2の変更を反映するように変更するか、デフォルトのDocusaurus v2 READMEをコピーしてください。

サイト設定

docusaurus.config.js

siteConfig.jsの名前をdocusaurus.config.jsに変更します。

Docusaurus 2では、モジュール化のために各機能（ブログ、ドキュメント、ページ）をプラグインに分割しました。プリセットはプラグインのバンドルであり、下位互換性のために、Docusaurus 1に存在する重要なプラグインのほとんどをバンドルした@docusaurus/preset-classicプリセットを作成しました。

次のプリセット設定をdocusaurus.config.jsに追加します。

docusaurus.config.js

module.exports = {
  // ...
  presets: [
    [
      '@docusaurus/preset-classic',
      {
        docs: {
          // Docs folder path relative to website dir.
          path: '../docs',
          // Sidebars file relative to website dir.
          sidebarPath: require.resolve('./sidebars.json'),
        },
        // ...
      },
    ],
  ],
};

docsフォルダをwebsiteフォルダに移動することをお勧めします。これはv2のデフォルトのディレクトリ構造でもあります。Vercelは、docsディレクトリがwebsite内にある場合、Docusaurusプロジェクトのデプロイをすぐにサポートします。また、ドキュメントとウェブサイトの残りのコードが1つのwebsiteディレクトリ内に配置されるため、ドキュメントがウェブサイト内にある方が一般的に優れています。

Docusaurus v1 Webサイトを移行していて、保留中のドキュメントプルリクエストがある場合は、競合が発生しないように、一時的に/docsフォルダを元の場所に保持できます。

siteConfig.jsの各フィールドの移行ガイドについては、以下を参照してください。

更新されたフィールド

baseUrl、tagline、title、url、favicon、organizationName、projectName、githubHost、scripts、stylesheets

アクションは不要です。これらの設定フィールドは変更されていません。

colors

非推奨。Docusaurus 2用にInfimaというカスタムCSSフレームワークを作成しました。これは、テーマにCSS変数を使用します。ドキュメントはまだ準備できていません。準備ができたら、ここで更新します。InfimaのCSS変数を上書きするには、独自のCSSファイル（例：./src/css/custom.css）を作成し、@docusaurus/preset-classicにオプションとして渡すことでグローバルにインポートします

docusaurus.config.js

module.exports = {
  // ...
  presets: [
    [
      '@docusaurus/preset-classic',
      {
        theme: {
          customCss: [require.resolve('./src/css/custom.css')],
        },
      },
    ],
  ],
};

Infimaは各色の7つのシェードを使用します。

/src/css/custom.css

/**
 * You can override the default Infima variables here.
 * Note: this is not a complete list of --ifm- variables.
 */
:root {
  --ifm-color-primary: #25c2a0;
  --ifm-color-primary-dark: rgb(33, 175, 144);
  --ifm-color-primary-darker: rgb(31, 165, 136);
  --ifm-color-primary-darkest: rgb(26, 136, 112);
  --ifm-color-primary-light: rgb(70, 203, 174);
  --ifm-color-primary-lighter: rgb(102, 212, 189);
  --ifm-color-primary-lightest: rgb(146, 224, 208);
}

選択したプライマリカラーのさまざまなシェードを見つけるには、ColorBoxを使用することをお勧めします。

または、次のツールを使用して、Webサイトのさまざまなシェードを生成し、変数をsrc/css/custom.cssにコピーします。

ヒント

読みやすさを確保するために、プライマリカラーのWCAG-AAコントラスト比を少なくとも目指してください。Docusaurus Webサイト自体を使用して、カラーパレットがどのように見えるかプレビューします。1つの色は通常、ライトモードとダークモードの両方では機能しないため、ダークモードでは代替パレットを使用できます。

プライマリカラー

背景

CSS変数名	16進数	調整	コントラスト評価
--ifm-color-primary-lightest	#3cad6e		失敗 🔴
--ifm-color-primary-lighter	#359962		失敗 🔴
--ifm-color-primary-light	#33925d		失敗 🔴
--ifm-color-primary	#2e8555	0	AA 👍
--ifm-color-primary-dark	#29784c		AA 👍
--ifm-color-primary-darker	#277148		AA 👍
--ifm-color-primary-darkest	#205d3b		AAA 🏅

src/css/custom.cssの変数をこれらの新しい変数に置き換えます。

/src/css/custom.css

:root {
  --ifm-color-primary: #2e8555;
  --ifm-color-primary-dark: #29784c;
  --ifm-color-primary-darker: #277148;
  --ifm-color-primary-darkest: #205d3b;
  --ifm-color-primary-light: #33925d;
  --ifm-color-primary-lighter: #359962;
  --ifm-color-primary-lightest: #3cad6e;
}

footerIcon、copyright、ogImage、twitterImage、docsSideNavCollapsible

アセット、SEO、著作権情報などのサイトメタ情報は、テーマによって処理されるようになりました。カスタマイズするには、docusaurus.config.jsのthemeConfigフィールドを使用します

docusaurus.config.js

module.exports = {
  // ...
  themeConfig: {
    footer: {
      logo: {
        alt: 'Meta Open Source Logo',
        src: '/img/meta_oss_logo.png',
        href: 'https://opensource.facebook.com/',
      },
      copyright: `Copyright © ${new Date().getFullYear()} Facebook, Inc.`, // You can also put own HTML here.
    },
    image: 'img/docusaurus.png',
    // ...
  },
};

headerIcon、headerLinks

Docusaurus 1では、ヘッダーアイコンとヘッダーリンクはsiteConfigのルートフィールドでした

siteConfig.js

headerIcon: 'img/docusaurus.svg',
headerLinks: [
  { doc: "doc1", label: "Getting Started" },
  { page: "help", label: "Help" },
  { href: "https://github.com/", label: "GitHub" },
  { blog: true, label: "Blog" },
],

現在、これら2つのフィールドは両方ともテーマによって処理されています

docusaurus.config.js

module.exports = {
  // ...
  themeConfig: {
    navbar: {
      title: 'Docusaurus',
      logo: {
        alt: 'Docusaurus Logo',
        src: 'img/docusaurus.svg',
      },
      items: [
        {to: 'docs/doc1', label: 'Getting Started', position: 'left'},
        {to: 'help', label: 'Help', position: 'left'},
        {
          href: 'https://github.com/',
          label: 'GitHub',
          position: 'right',
        },
        {to: 'blog', label: 'Blog', position: 'left'},
      ],
    },
    // ...
  },
};

algolia

docusaurus.config.js

module.exports = {
  // ...
  themeConfig: {
    algolia: {
      apiKey: '47ecd3b21be71c5822571b9f59e52544',
      indexName: 'docusaurus-2',
      algoliaOptions: { //... },
    },
    // ...
  },
};

警告

Algolia DocSearch v1の設定（こちらにあります）は、Docusaurus v2用に更新する必要があります（例）。

サポートが必要な場合は、DocSearchチーム（@shortcuts、@s-pace）にご連絡ください。彼らはあなたのためにそれを更新し、あなたのサイトの再クロールをトリガーして検索を復元することができます（そうでない場合は、次のスケジュールされたクロールまで最大24時間待つ必要があります）。

blogSidebarCount

非推奨。代わりにブログオプションとして@docusaurus/preset-classicに渡してください。

docusaurus.config.js

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

cname

非推奨。代わりに、カスタムドメインを使用してstaticフォルダにCNAMEファイルを作成してください。 staticフォルダ内のファイルは、ビルドコマンドの実行中にbuildフォルダのルートにコピーされます。

customDocsPath、docsUrl、editUrl、enableUpdateBy、enableUpdateTime

**破壊的変更**: editUrlは、docsディレクトリではなく、（ウェブサイトの）Docusaurusプロジェクトを指す必要があります。

非推奨。代わりに@docusaurus/preset-classic docsのオプションとして渡してください。

docusaurus.config.js

module.exports = {
  // ...
  presets: [
    [
      '@docusaurus/preset-classic',
      {
        docs: {
          // Equivalent to `customDocsPath`.
          path: 'docs',
          // Equivalent to `editUrl` but should point to `website` dir instead of `website/docs`.
          editUrl: 'https://github.com/facebook/docusaurus/edit/main/website',
          // Equivalent to `docsUrl`.
          routeBasePath: 'docs',
          // Remark and Rehype plugins passed to MDX. Replaces `markdownOptions` and `markdownPlugins`.
          remarkPlugins: [],
          rehypePlugins: [],
          // Equivalent to `enableUpdateBy`.
          showLastUpdateAuthor: true,
          // Equivalent to `enableUpdateTime`.
          showLastUpdateTime: true,
        },
        // ...
      },
    ],
  ],
};

gaTrackingId

docusaurus.config.js

module.exports = {
  // ...
  presets: [
    [
      '@docusaurus/preset-classic',
      {
        // ...
        googleAnalytics: {
          trackingID: 'UA-141789564-1',
        },
      },
    ],
  ],
};

gaGtag

docusaurus.config.js

module.exports = {
  // ...
  presets: [
    [
      '@docusaurus/preset-classic',
      {
        // ...
        gtag: {
          trackingID: 'UA-141789564-1',
        },
      },
    ],
  ],
};

削除されたフィールド

以下のフィールドはすべて非推奨です。設定ファイルから削除できます。

• blogSidebarTitle
• cleanUrl - Clean URLは現在デフォルトで使用されています。
• defaultVersionShown - バージョニングはまだ移植されていません。バージョン管理を使用している場合、Docusaurus 2に移行することはできません。乞うご期待。
• disableHeaderTitle
• disableTitleTagline
• docsSideNavCollapsibleはdocsPluginOptions.sidebarCollapsibleで使用でき、現在はデフォルトで有効になっています。
• facebookAppId
• facebookComments
• facebookPixelId
• fonts
• highlight - 現在、highlight.jsの代わりにPrismを使用しています。
• markdownOptions - v2ではRemarkableの代わりにMDXを使用しています。MarkdownオプションはRemark/Rehypeプラグインに変換する必要があります。
• markdownPlugins - v2ではRemarkableの代わりにMDXを使用しています。MarkdownプラグインはRemark/Rehypeプラグインに変換する必要があります。
• manifest
• onPageNav - これは現在デフォルトで有効になっています。
• separateCss - 上記のcustom.cssと同じ方法でインポートできます。
• scrollToTop
• scrollToTopOptions
• translationRecruitingLink
• twitter
• twitterUsername
• useEnglishUrl
• users
• usePrism - 現在、highlight.jsの代わりにPrismを使用しています。
• wrapPagesHTML

将来的には、非推奨の多くの設定フィールドをプラグインとして実装する予定です。ご協力をお願いします！

URL

v1では、すべてのページは.html拡張子の有無にかかわらず利用可能でした。

たとえば、次の2つのページが存在します。

• https://v1.docusaurus.io/docs/en/installation
• https://v1.docusaurus.io/docs/en/installation.html

cleanUrlが

• trueの場合：リンクは/installationをターゲットにします
• falseの場合：リンクは/installation.htmlをターゲットにします

v2では、デフォルトで、正規ページは/installation.htmlではなく、/installationです。

v1でcleanUrl: falseを設定していた場合、/installation.htmlへのリンクが公開されている可能性があります。

SEO上の理由から、またリンク切れを避けるために、ホスティングプロバイダでサーバー側のリダイレクトルールを設定する必要があります。

緊急回避策として、@docusaurus/plugin-client-redirectsを使用して、/installation.htmlから/installationへのクライアント側リダイレクトを作成できます。

module.exports = {
  plugins: [
    [
      '@docusaurus/plugin-client-redirects',
      {
        fromExtensions: ['html'],
      },
    ],
  ],
};

.html拡張子をページの正規URLとして保持する場合、ドキュメントはslug: installation.htmlフロントマターを宣言できます。

コンポーネント

サイドバー

以前のバージョンでは、ネストされたサイドバーカテゴリは許可されておらず、サイドバーカテゴリにはドキュメントIDのみを含めることができました。ただし、v2では無限のネストされたサイドバーが許可されており、ドキュメント以外のサイドバーアイテムの種類が多数あります。

カテゴリタイプが含まれている場合は、サイドバーを移行する必要があります。 subcategoryをcategoryに、idsをitemsに名前変更します。

sidebars.json

{
- type: 'subcategory',
+ type: 'category',
  label: 'My Example Subcategory',
+ items: ['doc1'],
- ids: ['doc1']
},

フッター

website/core/Footer.jsは不要になりました。Docusaurusが提供するデフォルトのフッターを変更する場合は、swizzleしてください。

npm

npm run swizzle @docusaurus/theme-classic Footer

Yarn

yarn swizzle @docusaurus/theme-classic Footer

pnpm

pnpm run swizzle @docusaurus/theme-classic Footer

これにより、テーマで使用されている現在の<Footer />コンポーネントが、サイトのルートにあるsrc/theme/Footerディレクトリにコピーされます。その後、このコンポーネントを編集してカスタマイズできます。

左側にロゴを追加するためだけにフッターをswizzleしないでください。ロゴはv2で意図的に削除され、下部に移動されました。 docusaurus.config.jsでthemeConfig.footerを使用してフッターを設定するだけです。

module.exports = {
  themeConfig: {
    footer: {
      logo: {
        alt: 'Meta Open Source Logo',
        src: '/img/meta_oss_logo.png',
        href: 'https://opensource.facebook.com',
      },
    },
  },
};

ページ

Docusaurus 2ページの仕組みについては、ページの作成を参照してください。これを読んだ後、v1のpages/enファイルをsrc/pagesに移動する必要があることに注意してください。

Docusaurus v1では、ページは小道具としてsiteConfigオブジェクトを受け取りました。

Docusaurus v2では、代わりにuseDocusaurusContextからsiteConfigオブジェクトを取得します。

v2では、各ページにテーマレイアウトを適用する必要があります。レイアウトコンポーネントはメタデータの小道具を取ります。

CompLibraryはv2では非推奨です。独自のReactコンポーネントを作成するか、Infimaスタイルを使用する必要があります（ドキュメントはまもなく公開されます。申し訳ありません！その間、V2 Webサイトを調べてみるか、https://infima.dev/で利用可能なスタイルを確認してください）。

CommonJSをES6のインポート/エクスポートに移行できます。

典型的なDocusaurus v2ページは次のとおりです。

import React from 'react';
import Link from '@docusaurus/Link';
import useDocusaurusContext from '@docusaurus/useDocusaurusContext';
import Layout from '@theme/Layout';

const MyPage = () => {
  const {siteConfig} = useDocusaurusContext();
  return (
    <Layout title={siteConfig.title} description={siteConfig.tagline}>
      <div className="hero text--center">
        <div className="container ">
          <div className="padding-vert--md">
            <h1 className="hero__title">{siteConfig.title}</h1>
            <p className="hero__subtitle">{siteConfig.tagline}</p>
          </div>
          <div>
            <Link
              to="/docs/get-started"
              className="button button--lg button--outline button--primary">
              Get started
            </Link>
          </div>
        </div>
      </div>
    </Layout>
  );
};

export default MyPage;

次のコードは、さまざまなページの移行に役立つ場合があります。

• インデックスページ - Flux（推奨）、Docusaurus 2、Hermes
• ヘルプ/サポートページ - Docusaurus 2、Flux

コンテンツ

AUTOGENERATED_TABLE_OF_CONTENTSの置換

この機能は、インライン目次に置き換えられました。

Markdown構文をMDX互換に更新する

Docusaurus 2では、Markdown構文がMDXに変更されました。そのため、既存のドキュメントに壊れた構文がある可能性があり、更新する必要があります。一般的な例としては、HTMLでは有効な<img>や<br>などの自己終了タグは、明示的に閉じる必要があります（<img/>および<br/>）。MDXドキュメントのすべてのタグは、有効なJSXである必要があります。

フロントマターはgray-matterによって解析されます。フロントマターで:などの特殊文字を使用する場合は、引用符で囲む必要があります。title: Part 1: my part1 title → title: "Part 1: my part1 title"。

**ヒント**: HTML to JSXなどのオンラインツールを使用すると、移行が容易になる場合があります。

言語固有のコードタブ

複数言語対応コードブロックセクションを参照してください。

フロントマター

ブログのDocusaurusフロントマターフィールドは、ドキュメントとの整合性をとるために、camelCaseからsnake_caseに変更されました。

authorFBIDおよびauthorTwitterフィールドは非推奨になりました。これらは、authorsフィールドを介して実行できる作成者のプロファイル画像の生成にのみ使用されます。

デプロイメント

GitHub Pagesで使用されるCNAMEファイルは生成されなくなったため、カスタムドメインを使用する場合は、/static/CNAMEに作成されていることを確認してください。

ブログのRSSフィードは、/blog/feed.xmlではなく、/blog/rss.xmlでホストされるようになりました。ユーザーのサブスクリプションが引き続き機能するように、サーバー側のリダイレクトを設定することをお勧めします。

サイトのテスト

移行後、フォルダ構造は次のようになります。

my-project
├── docs
└── website
    ├── blog
    ├── src
    │   ├── css
    │   │   └── custom.css
    │   └── pages
    │       └── index.js
    ├── package.json
    ├── sidebars.json
    ├── .gitignore
    ├── docusaurus.config.js
    └── static

開発サーバーを起動し、エラーを修正します。

npm

cd website
npm start

Yarn

cd website
yarn start

pnpm

cd website
pnpm start

本番環境用にサイトをビルドすることもできます。

npm

npm run build

Yarn

yarn build

pnpm

pnpm run build