組態
查看 docusaurus.config.js API 參考手冊 獲取完整選項清單。
Docusaurus 對組態有獨到見解。我們建議你將網站資訊集中在單一位置。我們保護此檔案的欄位，並協助讓這些資料物件在你的網站中都能存取。
妥善維護 docusaurus.config.js 有助於你、你的協作者以及你的開源貢獻者專注於文件編寫，同時也能自訂網站。
宣告 docusaurus.config.js 的語法
docusaurus.config.js 檔案會在 Node.js 中執行，並應該匯出
- config 物件
- 函式，用於建立 config 物件
docusaurus.config.js 檔案支援
約束
- 必要：請使用
export default /* your config*/（或module.exports）匯出你的 Docusaurus config - 選用：使用
import Lib from 'lib'（或require('lib')）來匯入 Node.js 套件
Docusaurus 提供我們以各種對等的途徑宣告其組態的能力，而所有下列的組態範例都會導向到完全相同的結果
export default {
title: 'Docusaurus',
url: 'https://docusaurus.dev.org.tw',
// your site config ...
};
module.exports = {
title: 'Docusaurus',
url: 'https://docusaurus.dev.org.tw',
// your site config ...
};
import type {Config} from '@docusaurus/types';
export default {
title: 'Docusaurus',
url: 'https://docusaurus.dev.org.tw',
// your site config ...
} satisfies Config;
const config = {
title: 'Docusaurus',
url: 'https://docusaurus.dev.org.tw',
// your site config ...
};
export default config;
export default function configCreator() {
return {
title: 'Docusaurus',
url: 'https://docusaurus.dev.org.tw',
// your site config ...
};
}
export default async function createConfigAsync() {
return {
title: 'Docusaurus',
url: 'https://docusaurus.dev.org.tw',
// your site config ...
};
}
使用非同步組態建立器可以匯入 ESM-only 模組（主要是大多數備註外掛程式）很有幫助。因為動態匯入，讓匯入這類模組變得可行
export default async function createConfigAsync() {
// Use a dynamic import instead of require('esm-lib')
const lib = await import('lib');
return {
title: 'Docusaurus',
url: 'https://docusaurus.dev.org.tw',
// rest of your site config...
};
}
docusaurus.config.js 有什麼內容？
即使您正在開發您的網站，您也不應該從頭開始撰寫您的 docusaurus.config.js。所有範本都附有包含常見選項預設值的 docusaurus.config.js。
不過，如果您對組態的設計與實作有高度的瞭解，會很有幫助。
Docusaurus 組態的概觀可以分類為
網站元資料
網站元資料包含必要的整體元資料，例如 標題、網址、基礎網址和網站圖示。
它們用於多個地方，例如您網站的標題和標頭、瀏覽器分頁圖示、社群分享（Facebook、Twitter）資訊，甚至用於產生正確的路徑以提供您的靜態檔案。
部署組態
當您使用 deploy 命令部署您的網站時，就會使用到部署組態，例如 專案名稱、組織名稱，和 deploy分支（選用）。
建議查看 部署文件 以取得更多資訊。
佈景主題、外掛程式和預設值組態
請在 themes、plugins 和 presets 欄位中為你的網站列出 佈景主題、外掛程式 和 預設值，這些通常是 npm 套件
export default {
// ...
plugins: [
'@docusaurus/plugin-content-blog',
'@docusaurus/plugin-content-pages',
],
themes: ['@docusaurus/theme-classic'],
};
Docusaurus 支援 模組簡寫，讓你簡化上述設定為
export default {
// ...
plugins: ['content-blog', 'content-pages'],
themes: ['classic'],
};
它們也可以從本機目錄載入
import path from 'path';
export default {
// ...
themes: [path.resolve(__dirname, '/path/to/docusaurus-local-theme')],
};
如需指定外掛程式的選項或佈景主題，請用一個包含外掛程式或佈景主題名稱和選項物件的陣列取代設定檔中的外掛程式或佈景主題名稱
export default {
// ...
plugins: [
[
'content-blog',
{
path: 'blog',
routeBasePath: 'blog',
include: ['*.md', '*.mdx'],
// ...
},
],
'content-pages',
],
};
如需指定已綑綁在預設值中的外掛程式或佈景主題的選項，請在 presets 欄位中提供選項。在此範例中，docs 指的是 @docusaurus/plugin-content-docs，而 theme 指的是 @docusaurus/theme-classic。
export default {
// ...
presets: [
[
'@docusaurus/preset-classic',
{
docs: {
sidebarPath: './sidebars.js',
},
theme: {
customCss: ['./src/css/custom.css'],
},
},
],
],
};
presets: [['classic', {...}]] 簡寫也可以使用。
如需進一步協助設定佈景主題、外掛程式和預設值，請參閱 使用外掛程式。
自訂設定
Docusaurus 會保護 docusaurus.config.js 不受未知欄位的侵擾。如需加入自訂欄位，請在 customFields 中定義。
範例
export default {
// ...
customFields: {
image: '',
keywords: [],
},
// ...
};
從元件存取設定
你的設定物件會提供給網站的所有元件。你可以透過 React 上下文存取它們，作為 siteConfig。
基本範例
import React from 'react';
import useDocusaurusContext from '@docusaurus/useDocusaurusContext';
const Hello = () => {
const {siteConfig} = useDocusaurusContext();
const {title, tagline} = siteConfig;
return <div>{`${title} · ${tagline}`}</div>;
};
如果你只想在客戶端使用這些欄位，你可以建立自己的 JS 檔案，再將它們作為 ES6 模組匯入，不需要放到 docusaurus.config.js 中。
自訂 Babel 設定
在新的 Docusaurus 專案中，我們會自動在專案根目錄產生一個 babel.config.js。
export default {
presets: ['@docusaurus/core/lib/babel/preset'],
};
大多時候，這個設定會執行得很好。如果你想自訂你的 Babel 設定（例如加入支援 Flow），你可以直接編輯這個檔案。要讓你的變更生效，你必須重新啟動 Docusaurus 開發伺服器。