擴充基礎架構

Docusaurus 具備一些基礎架構，例如熱重載、CLI、轉化，且可藉由外部外掛擴充。

getPathsToWatch()

指定供外掛和佈景主題觀看的路徑。開發伺服器會監控路徑，以便在受監控路徑中的內容變更時重新載入外掛生命週期。請注意，外掛和佈景主題模組最初會從 Node 的 context 和 options 開始呼叫，您可使用它來尋找關於網站的必要資料夾資訊。

將其用於伺服器端消耗的檔案，因為 Webpack 開發伺服器會自動監控佈景主題檔案。

範例

docusaurus-plugin/src/index.js

import path from 'path';

export default function (context, options) {
  return {
    name: 'docusaurus-plugin',
    getPathsToWatch() {
      const contentPath = path.resolve(context.siteDir, options.path);
      return [`${contentPath}/**/*.{ts,tsx}`];
    },
  };
}

extendCli(cli)

註冊額外指令來增強 Docusaurus 的 CLI。cli 是 commander 物件。

警告

指令版本很重要！我們使用 commander v5，請確認您參照的是正確版本的文件取得可用的 API。

範例

docusaurus-plugin/src/index.js

export default function (context, options) {
  return {
    name: 'docusaurus-plugin',
    extendCli(cli) {
      cli
        .command('roll')
        .description('Roll a random number between 1 and 1000')
        .action(() => {
          console.log(Math.floor(Math.random() * 1000 + 1));
        });
    },
  };
}

getThemePath()

傳回可以找到佈景主題組件的目錄路徑。當您的使用者呼叫 swizzle 時，會呼叫 getThemePath，並使用其所傳回的路徑來尋找佈景主題組件。相對路徑是解析為包含輸入點的資料夾。

例如，您的 getThemePath 可以是

my-theme/src/index.js

export default function (context, options) {
  return {
    name: 'my-theme',
    getThemePath() {
      return './theme';
    },
  };
}

getTypeScriptThemePath()

類似於 getThemePath()，它應該傳回 TypeScript 佈景主題組件的原始碼可以找到的目錄路徑。這個路徑專門用於交換 TypeScript 佈景主題組件，而此路徑下的佈景主題組件將不會由 Webpack 解析。因此，它無法取代 getThemePath()。通常，您可以讓 getTypeScriptThemePath() 傳回的路徑為您的原始碼目錄，並讓 getThemePath() 傳回的路徑為編譯的 JavaScript 輸出。

提示

針對 TypeScript 佈景主題作者：強烈建議您讓您的編譯輸出盡可能具有可讀性。只移除類型註解，不要轉譯任何語法，因為這些語法會根據目標瀏覽器版本由 Webpack 的 Babel 載入器處理。

您也應該使用 Prettier 格式化這些檔案。請記住，JS 檔案可以且可能會直接供您的使用者使用。

範例

my-theme/src/index.js

export default function (context, options) {
  return {
    name: 'my-theme',
    getThemePath() {
      // Where compiled JavaScript output lives
      return '../lib/theme';
    },
    getTypeScriptThemePath() {
      // Where TypeScript source code lives
      return '../src/theme';
    },
  };
}

getSwizzleComponentList()

這是一個靜態方法，未附加至任何外掛實體。

傳回一個穩定且被認為可以安全交換的組件清單。這些組件可在不使用 --danger 的情況下交換。預設所有組件都視為不穩定。如果傳回一個空的陣列，所有組件都視為不穩定。如果傳回 undefined，則所有組件都視為穩定。

my-theme/src/index.js

export function getSwizzleComponentList() {
  return [
    'CodeBlock',
    'DocSidebar',
    'Footer',
    'NotFound',
    'SearchBar',
    'hooks/useTheme',
    'prism-include-languages',
  ];
}