手動遷移

在進行 自動遷移程序 後，應該執行手動遷移程序，以完成遺漏的部分或針對遷移 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",
  }
}

小秘訣

請使用最新版本的 Docusaurus 2，可以在 這裡 查看 (使用 latest 標籤)。

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 deploy 腳本，而不是 yarn publish-gh-pages。

.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 的 Website 可能有現有的 README 檔案。你可以修改它以反映 D2 的變更，或是複製預設的 Docusaurus v2 README。

網站組態

docusaurus.config.js

將 siteConfig.js 重新命名為 docusaurus.config.js。

在 Docusaurus 2 中，我們將每個功能性 (網誌、文件、頁面) 分割成外掛以提高模組化。預設設定是外掛組合，為了向後相容性，我們建立了 @docusaurus/preset-classic 預設設定，組合了 Docusaurus 1 中存在的大部分必要外掛。

將以下預設設定組態加入你的 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 支援 開箱即用的 Docusaurus 專案部署，前提是 docs 目錄在 website 內。一般建議將文件放在網站內，讓文件與網站的其餘程式碼可以共存于同一 website 目錄。

如果要變更 Docusaurus v1 網站，而且還有待處理的文件化拉取要求，則可以暫時將 /docs 資料夾留在原位，以避免產生衝突。

請參閱下列變更指南，取得 siteConfig.js 中每個欄位的資訊。

更新的欄位

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

不需要執行任何動作，這些設定欄位未經修改。

colors

已棄用。我們已為 Docusaurus 2 撰寫了一個自訂 CSS 架構，稱為 Infima，它會使用 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 來尋找您選擇的主要顏色的各種色階。

或者，使用下列工具為您的網站產生各種色階，並將變數複製至 src/css/custom.css 中。

小秘訣

目標至少達到 WCAG-AA 對比率，以確保主要顏色具有可讀性。使用 Docusaurus 網站本身預覽您的調色盤會是什麼樣子。您可以在暗模式中使用其他調色盤，因為一種顏色通常無法同時適用於明暗模式。

主要顏色

背景

CSS 變數名稱	十六進位	調整	對比評級
--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、版權資訊等網站的 meta 資料。若要自訂它們，請在 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" },
],

現在，這兩個欄位都由主題處理

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應指向 (網站) Docusaurus 專案，而非docs目錄。

已棄用。改為傳遞給@docusaurus/preset-classic文件選項。

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 - 我們現在使用Prism取代highlight.js。
• markdownOptions - 我們在 v2 中使用 MDX，而非 Remarkable。你的 Markdown 選項必須轉換為 Remark/Rehype 外掛程式。
• markdownPlugins - 我們在 v2 中使用 MDX，而非 Remarkable。你的 Markdown 外掛程式必須轉換為 Remark/Rehype 外掛程式。
• manifest
• onPageNav - 從現在開始預設已開啟。
• separateCss - 它可以和上面提到的custom.css以相同方式導入。
• scrollToTop
• scrollToTopOptions
• translationRecruitingLink
• twitter
• twitterUsername
• useEnglishUrl
• users
• usePrism - 我們現在使用Prism取代highlight.js
• wrapPagesHTML

我們打算在未來實作許多已棄用的組態欄位為外掛程式。非常歡迎協助我們！

網址

在 v1 中，所有頁面都可以使用或不使用.html副檔名。

例如，這兩個頁面都存在

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

如果cleanUrl為

• true：連結會導向/installation
• false：連結會導向/installation.html

在 v2 中，預設的正規頁面為/installation，而非/installation.html。

如果你在 v1 中設定cleanUrl: false，其他人可能會發布連結到/installation.html。

出於 SEO 原因，且為了避免損壞連結，你應在你的 hosting 供應商上組態伺服器端重新導向規則。

您可以使用 @docusaurus/plugin-client-redirects 作為跳脫管道，建立從 /installation.html 重新導向到 /installation 的用戶端重新導向。

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

如果您希望將 .html 附檔名保留為頁面的標準網址，則文件檔可以宣告 slug: installation.html 的核心事項。

組件

側邊欄

在較早版本中，不允許嵌套側邊欄類別，且側邊欄類別只能包含文件識別碼。不過，v2 允許多級嵌套側邊欄，而且我們有許多類型的 側邊欄項目，而非文件。

如果您側邊欄的類型包含類別，則您必須進行轉移。將 次類別 重新命名為 類別，並將 ids 重新命名為 項目。

sidebars.json

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

頁尾

website/core/Footer.js 不再需要。如果您想修改由 Docusaurus 提供的預設頁尾，請對其 進行偽裝。

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 目錄，然後您就可以編輯這個組件以進行自訂。

請不要只為了在左側增加標誌就對頁尾進行偽裝。該標誌在 v2 中是刻意移除並移到底部的。只需使用 themeConfig.footer 在 docusaurus.config.js 中設定頁尾即可。

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 網站或檢視 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。因此現有的文件可能會產生一些語法錯誤，您必須更新這些語法。常見的範例是自閉合標籤，例如：<img>和 <br> 在 HTML 中有效，但現在必須明確地關閉它們（<img/>和 <br/>）。MDX 文件中的所有標籤都必須是有效的 JSX。

Front matter 由 gray-matter 解析。如果您的 Front matter 使用特殊字元，例如：:，現在您需要加上引號：title: Part 1: my part1 title → title: "Part 1: my part1 title"。

提示：建議您使用一些線上工具，例如：HTML to JSX 讓移轉更輕鬆。

與語言相關的程式碼標籤

請參閱 支援多語言的程式碼區塊。

Front matter

部落格的 Docusaurus Front matter 欄位已從 camelCase 變更為 snake_case，以與文件保持一致。

authorFBID 和 authorTwitter 欄位已棄用。它們只用於產生作者的個人資料圖片，現在可以使用 authors 欄位來完成這項工作。

部署

GitHub Pages 使用的 CNAME 檔案不再產生，所以如果您使用自訂網域，確定您已在 /static/CNAME 中建立它。

部落格 RSS feed 現在寄宿在 /blog/rss.xml，而不是 /blog/feed.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