跳到主要內容
版本：3.5.2

docusaurus.config.js

資訊

有關範例，請參閱入門指南的設定檔。

概觀​

docusaurus.config.js 含有您的站台設定檔，並放置在站台的根目錄中。

備註

使用TypeScript Docusaurus 程式碼庫時，您的設定檔檔案可能會稱為 docusaurus.config.ts。語法大致上與 js 設定檔相同，但增加了類型。您可以在Docusaurus 網站本身上看到範例。

這個檔案會在 Node.js 中執行，並輸出站台設定檔物件，或用來建立站台設定檔物件的

docusaurus.config.js 檔案支援

範例

docusaurus.config.js
export default {
  title: 'Docusaurus',
  url: 'https://docusaurus.dev.org.tw',
  // your site config ...
};
docusaurus.config.js
export default async function createConfigAsync() {
  return {
    title: 'Docusaurus',
    url: 'https://docusaurus.dev.org.tw',
    // your site config ...
  };
}
提示

請參閱 宣告 docusaurus.config.js 的語法 以取得更詳盡的範例和說明。

必填欄位​

title​

  • 類型：string

網站的標題。將會用於標籤資料和作為瀏覽器標籤標題。

docusaurus.config.js
export default {
  title: 'Docusaurus',
};

url​

  • 類型：string

網站的網址。這也可以看作是頂層主機的名稱。例如，https://facebook.github.io 是 https://facebook.github.io/metro/ 的網址，而 https://docusaurus.dev.org.tw 是 https://docusaurus.dev.org.tw 的網址。這個欄位與 baseUrl 欄位有關。

docusaurus.config.js
export default {
  url: 'https://docusaurus.dev.org.tw',
};

baseUrl​

  • 類型：string

網站的基礎網址。可以視為主機後的路徑。例如，/metro/ 是 https://facebook.github.io/metro/ 的基礎網址。對於沒有路徑的網址，baseUrl 應該設定為 /。這個欄位與 url 欄位有關。始終會有前導和尾隨斜線。

docusaurus.config.js
export default {
  baseUrl: '/',
};

選填欄位​

favicon​

  • 類型：string | undefined

網站標誌的路徑；必須是一個可以於連結的 href 中使用的網址。例如，假設你的標誌在 static/img/favicon.ico

docusaurus.config.js
export default {
  favicon: '/img/favicon.ico',
};

trailingSlash​

  • 類型：boolean | undefined

允許自定義網址/連結末端是否有尾隨斜線，以及靜態 HTML 檔案如何產生

  • undefined（預設）：維持網址不變，並為 /docs/myDoc.md 產生 /docs/myDoc/index.html
  • true：為 URL/連結新增尾隨斜線，並為 /docs/myDoc.md 放送 /docs/myDoc/index.html
  • false：從 URL/連結中移除尾隨斜線，並為 /docs/myDoc.md 放送 /docs/myDoc.html
提示

每個靜態代管供應商都會以不同方式提供靜態檔案（這種行為甚至隨著時間而改變）。

請參閱部署指南和slorber/trailing-slash-guide，以選擇適當的設定。

i18n ​

  • 類型：Object

要 將你的網站本地化 的 i18n 組態物件。

範例

docusaurus.config.js
export default {
  i18n: {
    defaultLocale: 'en',
    locales: ['en', 'fa'],
    path: 'i18n',
    localeConfigs: {
      en: {
        label: 'English',
        direction: 'ltr',
        htmlLang: 'en-US',
        calendar: 'gregory',
        path: 'en',
      },
      fa: {
        label: 'فارسی',
        direction: 'rtl',
        htmlLang: 'fa-IR',
        calendar: 'persian',
        path: 'fa',
      },
    },
  },
};
  • defaultLocale：不會在基本 URL 中顯示名稱的語言環境 (2) 使用 docusaurus start 而未設定 --locale 選項時啟動的語言環境 (3) 會用於 <link hrefLang="x-default"> 標籤
  • locales：在你的網站上已部署語言環境清單。必須包含 defaultLocale。
  • path：所有語言環境資料夾的相對位置的根資料夾。可以是絕對路徑或相對於設定檔的路徑。預設為 i18n。
  • localeConfigs：每個語言環境的個別選項。
    • label：語言環境下拉式選單中顯示此語言環境的標籤。
    • direction：ltr（預設）或 rtl（用於從右到左書寫的語言，例如波斯語、阿拉伯語、希伯來語等）。用於選擇語言環境的 CSS 和 HTML meta 屬性。
    • htmlLang：在 <html lang="...">（或任何其他 DOM 標籤名稱）和 <link ... hreflang="..."> 中使用的 BCP 47 語言標籤
    • calendar：用來計算日期時代的日期時間格式。請注意，這不會控制實際顯示的字串：MM/DD/YYYY 和 DD/MM/YYYY 都是 gregory。若要選擇格式（DD/MM/YYYY 或 MM/DD/YYYY），請將你的語言環境名稱設定為 en-GB 或 en-US（en 表示 en-US）。
    • path：此語言環境所有外掛程式在地化資料夾的相對位置的根資料夾。會針對 i18n.path 解析。預設為語言環境名稱。注意：這不會影響語言環境的 baseUrl，自訂基本 URL 目前仍進行中。

future​

  • 類型：Object

future 組態物件允許選擇尚未準備好正式推出的一系列 Docusaurus 即將推出/不穩定/測試階段中的功能。

這也是選擇即將在未來重大版本中發布的重大變動的一種方式，可以在繼續使用前一版本的情況下為下一個版本準備你的網站。Remix Future Flags 部落格文章 深入說明了這個概念。

次要版本中的破壞性變更

以 experimental_ 或 unstable_ 為字首的功能可能會在次要版本中變更，且不被視為 語意化版本控管的破壞性變更。

以 v<MajorVersion>_（v6_、v7_ 等）為字首的功能是預計在下次的主要版本中預設開啟的未來旗標。這些比較不會變更，但我們保留變更的可能性。

future API 破壞性變更應該很容易處理，而且會在次要/主要版本的部落格文章中記錄下來。

範例

docusaurus.config.js
export default {
  future: {
    experimental_storage: {
      type: 'localStorage',
      namespace: true,
    },
    experimental_router: 'hash',
  },
};
  • experimental_storage：網站範圍的瀏覽器儲存選項，主題作者應該盡量遵守。
    • type：主題作者應該使用的瀏覽器儲存。可能的數值為 localStorage 和 sessionStorage。預設為 localStorage。
    • namespace：當 Docusaurus 網站寄存於同一個網域或 localhost 上時，是否將瀏覽器儲存鍵命名空間化以避免儲存鍵衝突。可能的數值為 字串 | 布林值。命名空間附加在儲存鍵 key-namespace 的最後。使用 true 自動從您的網站 url + baseUrl 產生隨機命名空間。預設為 false（不使用命名空間，以往的行為）。
  • experimental_router：要使用的路由器類型。可能的數值為 browser 和 hash。預設為 browser。hash 路由器僅適用於您想要退出靜態網站產生並使用單一 index.html 入口點檔案的罕見情況。這樣可以將 Docusaurus 網站分發為 .zip 檔案，您可以 在本地瀏覽而不執行網路伺服器。

noIndex​

  • 類型：布林值

此選項會將 <meta name="robots" content="noindex, nofollow"> 新增到每個頁面，以告訴搜尋引擎避免將您的網站建立索引（可以在 這裡 找到更多資訊）。

範例

docusaurus.config.js
export default {
  noIndex: true, // Defaults to `false`
};
  • 類型：'ignore' | 'log' | 'warn' | 'throw'

當 Docusaurus 偵測到任何失效連結時的行為。

預設情況下，它會擲回錯誤，以確保您永遠不會傳送任何失效連結。

備註

失效連結偵測僅提供給製作組建（docusaurus build）。

onBrokenAnchors​

  • 類型：'ignore' | 'log' | 'warn' | 'throw'

當 Docusaurus 偵測到使用 Docusaurus 的 Heading 元件所宣告的錨點毀損時的行為。

預設值為列印警告，讓你得知錨點毀損。

  • 類型：'ignore' | 'log' | 'warn' | 'throw'

當 Docusaurus 偵測到任何毀損的 Markdown 連結時的行為。

預設值為列印警告，讓你得知毀損的 Markdown 連結。

onDuplicateRoutes​

  • 類型：'ignore' | 'log' | 'warn' | 'throw'

當 Docusaurus 偵測到任何重複路由時的行為。

預設值是你執行 yarn start 或 yarn build 後會顯示警告。

tagline​

  • 類型：string

網站的標語。

docusaurus.config.js
export default {
  tagline:
    'Docusaurus makes it easy to maintain Open Source documentation websites.',
};

organizationName​

  • 類型：string

擁有存放庫的 GitHub 使用者或組織。若沒有使用 docusaurus deploy 指令則不需要此設定。

docusaurus.config.js
export default {
  // Docusaurus' organization is facebook
  organizationName: 'facebook',
};

projectName​

  • 類型：string

GitHub 存放庫名稱。若沒有使用 docusaurus deploy 指令則不需要此設定。

docusaurus.config.js
export default {
  projectName: 'docusaurus',
};

deploymentBranch​

  • 類型：string

部署靜態檔案之分支名稱。若沒有使用 docusaurus deploy 指令則不需要此設定。

docusaurus.config.js
export default {
  deploymentBranch: 'gh-pages',
};

githubHost​

  • 類型：string

伺服器的主機名稱。若使用 GitHub Enterprise 會用到。若沒有使用 docusaurus deploy 指令則不需要此設定。

docusaurus.config.js
export default {
  githubHost: 'github.com',
};

githubPort​

  • 類型：string

伺服器的連接埠。若使用 GitHub Enterprise 會用到。若沒有使用 docusaurus deploy 指令則不需要此設定。

docusaurus.config.js
export default {
  githubPort: '22',
};

themeConfig​

  • 類型：Object

客製化網站介面（如導覽列和頁尾）的佈景主題配置物件。

範例

docusaurus.config.js
export default {
  themeConfig: {
    docs: {
      sidebar: {
        hideable: false,
        autoCollapseCategories: false,
      },
    },
    colorMode: {
      defaultMode: 'light',
      disableSwitch: false,
      respectPrefersColorScheme: true,
    },
    navbar: {
      title: 'Site Title',
      logo: {
        alt: 'Site Logo',
        src: 'img/logo.svg',
        width: 32,
        height: 32,
      },
      items: [
        {
          to: 'docs/docusaurus.config.js',
          activeBasePath: 'docs',
          label: 'docusaurus.config.js',
          position: 'left',
        },
        // ... other links
      ],
    },
    footer: {
      style: 'dark',
      links: [
        {
          title: 'Docs',
          items: [
            {
              label: 'Docs',
              to: 'docs/doc1',
            },
          ],
        },
        // ... other links
      ],
      logo: {
        alt: 'Meta Open Source Logo',
        src: 'img/meta_oss_logo.png',
        href: 'https://opensource.fb.com',
        width: 160,
        height: 51,
      },
      copyright: `Copyright © ${new Date().getFullYear()} Facebook, Inc.`, // You can also put own HTML here
    },
  },
};

plugins​

  • 類型：PluginConfig[]
type PluginConfig = string | [string, any] | PluginModule | [PluginModule, any];

請參閱外掛方法參考，以了解 PluginModule 的形狀。

docusaurus.config.js
export default {
  plugins: [
    'docusaurus-plugin-awesome',
    ['docusuarus-plugin-confetti', {fancy: false}],
    () => ({
      postBuild() {
        console.log('Build finished');
      },
    }),
  ],
};

themes​

  • 類型：PluginConfig[]
docusaurus.config.js
export default {
  themes: ['@docusaurus/theme-classic'],
};

presets​

  • 類型：PresetConfig[]
type PresetConfig = string | [string, any];
docusaurus.config.js
export default {
  presets: [],
};

markdown​

Docusaurus Markdown 全域設定。

  • 類型：MarkdownConfig
type MarkdownPreprocessor = (args: {
  filePath: string;
  fileContent: string;
}) => string;

type MDX1CompatOptions =
  | boolean
  | {
      comments: boolean;
      admonitions: boolean;
      headingIds: boolean;
    };

export type ParseFrontMatter = (params: {
  filePath: string;
  fileContent: string;
  defaultParseFrontMatter: ParseFrontMatter;
}) => Promise<{
  frontMatter: {[key: string]: unknown};
  content: string;
}>;

type MarkdownAnchorsConfig = {
  maintainCase: boolean;
};

type MarkdownConfig = {
  format: 'mdx' | 'md' | 'detect';
  mermaid: boolean;
  preprocessor?: MarkdownPreprocessor;
  parseFrontMatter?: ParseFrontMatter;
  mdx1Compat: MDX1CompatOptions;
  remarkRehypeOptions: object; // see https://github.com/remarkjs/remark-rehype#options
  anchors: MarkdownAnchorsConfig;
};

範例

docusaurus.config.js
export default {
  markdown: {
    format: 'mdx',
    mermaid: true,
    preprocessor: ({filePath, fileContent}) => {
      return fileContent.replaceAll('{{MY_VAR}}', 'MY_VALUE');
    },
    parseFrontMatter: async (params) => {
      const result = await params.defaultParseFrontMatter(params);
      result.frontMatter.description =
        result.frontMatter.description?.replaceAll('{{MY_VAR}}', 'MY_VALUE');
      return result;
    },
    mdx1Compat: {
      comments: true,
      admonitions: true,
      headingIds: true,
    },
    anchors: {
      maintainCase: true,
    },
  },
};
名稱類型預設值說明
formart'mdx' | 'md' | 'detect''mdx'用於 Markdown 內容的預設解析器格式。使用「detect」會自動根據檔案副檔名 (.md 與 .mdx) 選擇適當格式。
mermaid布林值false當為 true 時，允許 Docusaurus 將使用 mermaid 語言的 Markdown 程式區塊轉換為 Mermaid 圖表。
preprocessorMarkdownPreprocessor未定義讓你可以在分析之前修改 Markdown 內容字串。視為最後的手段或解決方法：幾乎總是最好實作 Remark/Rehype 外掛程式。
parseFrontMatterParseFrontMatter未定義讓你能夠提供你自己的前置事項剖析器，或加強預設剖析器的功能。閱讀我們的 前置事項指南 以取得詳細資料。
mdx1CompatMDX1CompatOptions{comments: true, admonitions: true, headingIds: true}相容性選項，讓升級至 Docusaurus v3+ 時更加容易。
anchorsMarkdownAnchorsConfig{maintainCase: false}用於控制從 Markdown 標題產生的錨點的選項。
remarkRehypeOptions物件未定義讓你可以傳遞自訂的 remark-rehype 選項。

customFields​

Docusaurus 保護 docusaurus.config.js 不受不明欄位影響。若要新增自訂欄位，請在 customFields 中定義。

  • 類型：Object
docusaurus.config.js
export default {
  customFields: {
    admin: 'endi',
    superman: 'lol',
  },
};

嘗試在設定中新增不明欄位，將會在建置時導致錯誤。

Error: The field(s) 'foo', 'bar' are not recognized in docusaurus.config.js

staticDirectories​

一個相對或絕對路徑陣列。此路徑下的檔案將會直接複製到建置輸出中。

  • 類型：string[]

範例

docusaurus.config.js
export default {
  staticDirectories: ['static'],
};

headTags​

一個標籤陣列，將會插入在 HTML <head> 中。這些值必須是包含兩個屬性的物件：tagName 和 attributes。tagName 必須為決定要建立哪個標籤的字串；例如 link。attributes 必須是屬性值對應。

  • 類型：{ tagName: string; attributes: Object; }[]

範例

docusaurus.config.js
export default {
  headTags: [
    {
      tagName: 'link',
      attributes: {
        rel: 'icon',
        href: '/img/docusaurus.png',
      },
    },
  ],
};

這將在產生的 HTML 中變成 <link rel="icon" href="img/docusaurus.png" />。

腳本​

要載入的腳本陣列。值可以是字串或純粹屬性值對應的物件。<script> 標籤將會插入 HTML <head> 中。如果你使用純粹物件，唯一的必要屬性是 src，並且允許任何其他屬性（每個屬性都應該有布林值或字串值）。

請注意，在此加入的 <script> 是 render 阻擋，所以你可能需要將 async: true/defer: true 加入物件中。

  • 類型：(字串 | 物件)[]

範例

docusaurus.config.js
export default {
  scripts: [
    // String format.
    'https://docusaurus.dev.org.tw/script.js',
    // Object format.
    {
      src: 'https://cdnjs.cloudflare.com/ajax/libs/clipboard.js/2.0.0/clipboard.min.js',
      async: true,
    },
  ],
};

樣式表​

要載入的 CSS 來源陣列。值可以是字串或純粹屬性值對應的物件。<link> 標籤將會插入 HTML <head> 中。如果你使用物件，唯一的必要屬性是 href，並且允許任何其他屬性（每個屬性都應該有布林值或字串值）。

  • 類型：(字串 | 物件)[]

範例

docusaurus.config.js
export default {
  stylesheets: [
    // String format.
    'https://docusaurus.dev.org.tw/style.css',
    // Object format.
    {
      href: 'http://mydomain.com/style.css',
    },
  ],
};
資訊

預設情況下，<link> 標籤將會有 rel="stylesheet"，但你可以明確加入客製的 rel 值來注入任何類型的 <link> 標籤，不一定是樣式表。

客戶端模組​

一個要在你網站上載入的 客戶端模組 陣列。

範例

docusaurus.config.js
export default {
  clientModules: ['./mySiteGlobalJs.js', './mySiteGlobalCss.css'],
};

ssrTemplate​

使用 Eta 語法 編寫的 HTML 範本，將用於呈現你的應用程式。這可以設定 body 標籤中的自訂屬性、額外的 meta 標籤、客製化 viewport 等。請注意，Docusaurus 會依賴範本結構正確執行，一旦你進行客製化，你必須確認你的範本符合上游提供的需求。

  • 類型：string

範例

docusaurus.config.js
export default {
  ssrTemplate: `<!DOCTYPE html>
<html <%~ it.htmlAttributes %>>
  <head>
    <meta charset="UTF-8">
    <meta name="generator" content="Docusaurus v<%= it.version %>">
    <% it.metaAttributes.forEach((metaAttribute) => { %>
      <%~ metaAttribute %>
    <% }); %>
    <%~ it.headTags %>
    <% it.stylesheets.forEach((stylesheet) => { %>
      <link rel="stylesheet" href="<%= it.baseUrl %><%= stylesheet %>" />
    <% }); %>
    <% it.scripts.forEach((script) => { %>
      <link rel="preload" href="<%= it.baseUrl %><%= script %>" as="script">
    <% }); %>
  </head>
  <body <%~ it.bodyAttributes %>>
    <%~ it.preBodyTags %>
    <div id="__docusaurus">
      <%~ it.appHtml %>
    </div>
    <% it.scripts.forEach((script) => { %>
      <script src="<%= it.baseUrl %><%= script %>"></script>
    <% }); %>
    <%~ it.postBodyTags %>
  </body>
</html>`,
};

標題分隔符​

  • 類型：string

將用在產生的 <title> 標籤中當作標題分隔符。

範例

docusaurus.config.js
export default {
  titleDelimiter: '🦖', // Defaults to `|`
};

baseUrlIssueBanner​

  • 類型：布林值

當啟用時，如果你的網站無法載入 CSS 或 JavaScript 檔案，它將顯示一個視窗，這是個常見問題，通常與網站設定中的錯誤 baseUrl 有關。

範例

docusaurus.config.js
export default {
  baseUrlIssueBanner: true, // Defaults to `true`
};

A sample base URL issue banner. The style is very raw since the stylesheets failed to load. The text says &quot;Your Docusaurus site did not load properly... Current configured baseUrl = / (default value); We suggest trying baseUrl = /build/

警告

如果由於基礎網址錯誤導致所有資源載入失敗，此橫幅需要內嵌 CSS / JS。

如果你有嚴謹的 內容安全政策，你應該將它禁用。

編輯此頁面
上次更新時間 by Sébastien Lorber