docusaurus.config.js
Refer to the Getting Started Configuration for examples.
Overview
docusaurus.config.js
contains configurations for your site and is placed in the root directory of your site.
With a TypeScript Docusaurus codebase your config file may be called docusaurus.config.ts
. The syntax is broadly identical to the js
config file with the addition of types. You can see an example on the Docusaurus Website itself.
该文件在 Node.js 中运行,应该导出一个站点配置对象或创建该对象的函数。
The docusaurus.config.js
file supports:
示例:
export default {
title: 'Docusaurus',
url: 'https://docusaurus.io',
// your site config ...
};
export default async function createConfigAsync() {
return {
title: 'Docusaurus',
url: 'https://docusaurus.io',
// your site config ...
};
}
Refer to Syntax to declare docusaurus.config.js
for a more exhaustive list of examples and explanations.
Required fields
title
- Type:
string
网站标题。 会用于页面元数据中,以及浏览器选项卡标题。
export default {
title: 'Docusaurus',
};
url
- Type:
string
网站网址。 你可以把它看作是顶级主机名。 For example, https://facebook.github.io
is the URL of https://facebook.github.io/metro/, and https://docusaurus.io
is the URL for https://docusaurus.io. This field is related to the baseUrl
field.
export default {
url: 'https://docusaurus.io',
};
baseUrl
- Type:
string
站点的 base URL。 可以被看作是主机名后的路径。 For example, /metro/
is the base URL of https://facebook.github.io/metro/. For URLs that have no path, the baseUrl should be set to /
. This field is related to the url
field. 开头和末尾始终要包含斜杠。
export default {
baseUrl: '/',
};
Optional fields
favicon
- Type:
string | undefined
你的网站图标的路径;必须是可以用于链接 href 的 URL。 For example, if your favicon is in static/img/favicon.ico
:
export default {
favicon: '/img/favicon.ico',
};
trailingSlash
- Type:
boolean | undefined
这个选项允许你自定义 URL/链接后是否添加末尾斜杠,以及静态 HTML 会如何被生成。
undefined
(default): keeps URLs untouched, and emit/docs/myDoc/index.html
for/docs/myDoc.md
true
: add trailing slashes to URLs/links, and emit/docs/myDoc/index.html
for/docs/myDoc.md
false
: remove trailing slashes from URLs/links, and emit/docs/myDoc.html
for/docs/myDoc.md
每个静态托管服务商在提供静态文件时的表现都有不同(甚至可能随着时间的推移而改变)。
Refer to the deployment guide and slorber/trailing-slash-guide to choose the appropriate setting.
i18n
- Type:
Object
The i18n configuration object to localize your site.
示例:
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
: The locale that (1) does not have its name in the base URL (2) gets started withdocusaurus start
without--locale
option (3) will be used for the<link hrefLang="x-default">
taglocales
: List of locales deployed on your site. Must containdefaultLocale
.path
: Root folder which all locale folders are relative to. 路径可以是绝对的,或者相对于配置文件。 Defaults toi18n
.localeConfigs
: Individual options for each locale.label
: The label displayed for this locale in the locales dropdown.direction
:ltr
(default) orrtl
(for right-to-left languages like Farsi, Arabic, Hebrew, etc.). 用于选择语言的 CSS 和 HTML 元属性。htmlLang
: BCP 47 language tag to use in<html lang="...">
(or any other DOM tag name) and in<link ... hreflang="...">
calendar
: the calendar used to calculate the date era. Note that it doesn't control the actual string displayed:MM/DD/YYYY
andDD/MM/YYYY
are bothgregory
. To choose the format (DD/MM/YYYY
orMM/DD/YYYY
), set your locale name toen-GB
oren-US
(en
meansen-US
).path
: Root folder that all plugin localization folders of this locale are relative to. Will be resolved againsti18n.path
. 默认为语言的名称。 Note: this has no effect on the locale'sbaseUrl
—customization of base URL is a work-in-progress.
future
- Type:
Object
The future
configuration object permits to opt-in for upcoming/unstable/experimental Docusaurus features that are not ready for prime time.
它也是一种选择即将到来的重大版本中的重大变更的方法,使你可以在保持当前版本的同时为下一个版本做好准备。 The Remix Future Flags blog post greatly explains this idea.
Features prefixed by experimental_
or unstable_
are subject to changes in minor versions, and not considered as Semantic Versioning breaking changes.
Features prefixed by v<MajorVersion>_
(v6_
v7_
, etc.) are future flags that are expected to be turned on by default in the next major versions. These are less likely to change, but we keep the possibility to do so.
future
API breaking changes should be easy to handle, and will be documented in minor/major version blog posts.
示例:
export default {
future: {
experimental_storage: {
type: 'localStorage',
namespace: true,
},
experimental_router: 'hash',
},
};
experimental_storage
: Site-wide browser storage options that theme authors should strive to respect.type
: The browser storage theme authors should use. Possible values arelocalStorage
andsessionStorage
. Defaults tolocalStorage
.namespace
: Whether to namespace the browser storage keys to avoid storage key conflicts when Docusaurus sites are hosted under the same domain, or on localhost. Possible values arestring | boolean
. The namespace is appended at the end of the storage keyskey-namespace
. Usetrue
to automatically generate a random namespace from your siteurl + baseUrl
. Defaults tofalse
(no namespace, historical behavior).
experimental_router
: The router type to use. Possible values arebrowser
andhash
. Defaults tobrowser
. Thehash
router is only useful for rare cases where you want to opt-out of static site generation, have a fully client-side app with a singleindex.html
entrypoint file. This can be useful to distribute a Docusaurus site as a.zip
archive that you can browse locally without running a web server.
noIndex
- Type:
boolean
This option adds <meta name="robots" content="noindex, nofollow">
to every page to tell search engines to avoid indexing your site (more information here).
示例:
export default {
noIndex: true, // 默认为 `false`
};
onBrokenLinks
- Type:
'ignore' | 'log' | 'warn' | 'throw'
Docusaurus 在检测到无效链接时的行为。
By default, it throws an error, to ensure you never ship any broken link.
The broken links detection is only available for a production build (docusaurus build
).