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.
This file is run in Node.js using the CommonJS module system, and should export a site configuration object, or a function that creates it.
Examples:
module.exports = {
title: 'Docusaurus',
url: 'https://docusaurus.io',
// your site config ...
};
module.exports = 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
Title for your website. Will be used in metadata and as browser tab title.
module.exports = {
title: 'Docusaurus',
};
url
β
- Type:
string
URL for your website. This can also be considered the top-level hostname. 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.
module.exports = {
url: 'https://docusaurus.io',
};
baseUrl
β
- Type:
string
Base URL for your site. Can be considered as the path after the host. 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. Always has both leading and trailing slash.
module.exports = {
baseUrl: '/',
};
Optional fieldsβ
favicon
β
- Type:
string | undefined
Path to your site favicon; must be a URL that can be used in link's href. For example, if your favicon is in static/img/favicon.ico
:
module.exports = {
favicon: '/img/favicon.ico',
};
trailingSlash
β
- Type:
boolean | undefined
Allow to customize the presence/absence of a trailing slash at the end of URLs/links, and how static HTML files are generated:
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
Each static hosting provider serves static files differently (this behavior may even change over time).
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.
Example:
module.exports = {
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. Can be absolute or relative to the config file. 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.). Used to select the locale's CSS and HTML meta attribute.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
. Defaults to the locale's name. Note: this has no effect on the locale'sbaseUrl
βcustomization of base URL is a work-in-progress.
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).
Example:
module.exports = {
noIndex: true, // Defaults to `false`
};
onBrokenLinks
β
- Type:
'ignore' | 'log' | 'warn' | 'throw'
The behavior of Docusaurus when it detects any broken link.
By default, it throws an error, to ensure you never ship any broken link, but you can lower this security if needed.
The broken links detection is only available for a production build (docusaurus build
).