docusaurus.config.js
Refer to the Getting Started Configuration for examples.
Visão Geral
docusaurus.config.js
contém configurações para o seu site e é colocado no diretório raiz do seu 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.
This file is run in Node.js and should export a site configuration object, or a function that creates it.
The docusaurus.config.js
file supports:
Examples:
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.
Campos obrigatórios
título
- Tipo:
string
Título para o seu site. Will be used in metadata and as browser tab title.
export default {
title: 'Docusaurus',
};
url
- Tipo:
string
URL para o seu site. Isso também pode ser considerado o hostname de nível superior. Por exemplo, https://facebook.github.io
é a URL de https://facebook.github.io/metro/, e https://docusaurus.io
é a URL de https://docusaurus.io. This field is related to the baseUrl
field.
export default {
url: 'https://docusaurus.io',
};
baseUrl
- Tipo:
string
URL base do seu site. Can be considered as the path after the host. For example, /metro/
is the base URL of https://facebook.github.io/metro/. Para URLs que não possuem caminho, a baseUrl deve ser definida como /
. This field is related to the url
field. Always has both leading and trailing slash.
export default {
baseUrl: '/',
};
Campos opcionais
favicon
- Tipo:
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
:
export default {
favicon: '/img/favicon.ico',
};
trailingSlash
- Tipo:
boolean | undefined
Permite personalizar a presença/ausência de uma barra no final das URLs/links e como os arquivos HTML estáticos são gerados:
undefined
(padrão): mantém os URLs inalterados e emite/docs/myDoc/index.html
para/docs/myDoc.md
true
: adiciona barras finais a URLs/links e emite/docs/myDoc/index.html
para/docs/myDoc.md
false
: remove barras finais de URLs/links e emite/docs/myDoc.html
para/docs/myDoc.md
Each static hosting provider serves static files differently (this behavior may even change over time).
Consulte o guia de implantação e slorber/trailing-slash-guide para escolher a configuração apropriada.
i18n
- Tipo:
Objeto
The i18n configuration object to localize your site.
Exemplo:
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. 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.
future
- Tipo:
Objeto
The future
configuration object permits to opt-in for upcoming/unstable/experimental Docusaurus features that are not ready for prime time.
It is also a way to opt-in for upcoming breaking changes coming in the next major versions, enabling you to prepare your site for the next version while staying on the previous one. 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.
Exemplo:
export default {
future: {
experimental_faster: {
swcJsLoader: true,
swcJsMinimizer: true,
},
experimental_storage: {
type: 'localStorage',
namespace: true,
},
experimental_router: 'hash',
},
};
experimental_faster
: An object containing feature flags to make the Docusaurus build faster. This requires adding the@docusaurus/faster
package to your site's dependencies. Usetrue
as a shorthand to enable all flags.swcJsLoader
: Usetrue
to replace the default Babel JS loader by the SWC JS loader to speed up the bundling phase.swcJsMinimizer
: Usetrue
to replace the defaultterser-webpack-plugin
JS minimizer (Terser) by the SWC JS minimizer to speed up the bundling minification phase.
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
- Tipo:
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).
Exemplo:
export default {
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.
A detecção quebrada de links só está disponível para uma compilação de produção (docusaurus build
).
onBrokenAnchors
- Type:
'ignore' | 'log' | 'warn' | 'throw'
The behavior of Docusaurus when it detects any broken anchor declared with the Heading
component of Docusaurus.
By default, it prints a warning, to let you know about your broken anchors.
onBrokenMarkdownLinks
- Type:
'ignore' | 'log' | 'warn' | 'throw'
The behavior of Docusaurus when it detects any broken Markdown link.
By default, it prints a warning, to let you know about your broken Markdown link.
onDuplicateRoutes
- Type:
'ignore' | 'log' | 'warn' | 'throw'
The behavior of Docusaurus when it detects any duplicate routes.
Por padrão, ele exibe um aviso após você executar yarn start
ou yarn build
.
tagline
- Tipo:
string
A tagline para o seu site.
export default {
tagline:
'Docusaurus makes it easy to maintain Open Source documentation websites.',
};
organizationName
- Tipo:
string
O usuário ou organização proprietária do repositório. You don't need this if you are not using the docusaurus deploy
command.
export default {
// Docusaurus' organization is facebook
organizationName: 'facebook',
};
projectName
- Tipo:
string
O nome do repositório do GitHub. You don't need this if you are not using the docusaurus deploy
command.
export default {
projectName: 'docusaurus',
};
deploymentBranch
- Tipo:
string
The name of the branch to deploy the static files to. You don't need this if you are not using the docusaurus deploy
command.
export default {
deploymentBranch: 'gh-pages',
};
githubHost
- Tipo:
string
O hostname do seu servidor. Útil se você estiver usando o GitHub Enterprise. You don't need this if you are not using the docusaurus deploy
command.
export default {
githubHost: 'github.com',
};
githubPort
- Tipo:
string
A porta do seu servidor. Útil se você estiver usando o GitHub Enterprise. You don't need this if you are not using the docusaurus deploy
command.
export default {
githubPort: '22',
};
themeConfig
- Tipo:
Objeto
The theme configuration object to customize your site UI like navbar and footer.
Exemplo:
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
- Type:
PluginConfig[]
type PluginConfig = string | [string, any] | PluginModule | [PluginModule, any];
See plugin method references for the shape of a PluginModule
.
export default {
plugins: [
'docusaurus-plugin-awesome',
['docusuarus-plugin-confetti', {fancy: false}],
() => ({
postBuild() {
console.log('Build finished');
},
}),
],
};
themes
- Type:
PluginConfig[]
export default {
themes: ['@docusaurus/theme-classic'],
};
presets
- Type:
PresetConfig[]
type PresetConfig = string | [string, any];
export default {
presets: [],
};
markdown
The global Docusaurus Markdown config.
- Type:
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;
};
Exemplo:
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,
},
},
};
Nome | Type | Padrão | Descrição |
---|---|---|---|
format | 'mdx' | 'md' | 'detect' | 'mdx' | The default parser format to use for Markdown content. Using 'detect' will select the appropriate format automatically based on file extensions: .md vs .mdx . |
mermaid | boolean | false | When true , allows Docusaurus to render Markdown code blocks with mermaid language as Mermaid diagrams. |
preprocessor | MarkdownPreprocessor | undefined | Gives you the ability to alter the Markdown content string before parsing. Use it as a last-resort escape hatch or workaround: it is almost always better to implement a Remark/Rehype plugin. |
parseFrontMatter | ParseFrontMatter | undefined | Gives you the ability to provide your own front matter parser, or to enhance the default parser. Read our front matter guide for details. |
mdx1Compat | MDX1CompatOptions | {comments: true, admonitions: true, headingIds: true} | Compatibility options to make it easier to upgrade to Docusaurus v3+. |
anchors | MarkdownAnchorsConfig | {maintainCase: false} | Options to control the behavior of anchors generated from Markdown headings |
remarkRehypeOptions | object | undefined | Makes it possible to pass custom remark-rehype options. |
customFields
Docusaurus guards docusaurus.config.js
from unknown fields. To add a custom field, define it on customFields
.
- Tipo:
Objeto
export default {
customFields: {
admin: 'endi',
superman: 'lol',
},
};
Attempting to add unknown fields in the config will lead to errors during build time:
Error: The field(s) 'foo', 'bar' are not recognized in docusaurus.config.js
staticDirectories
An array of paths, relative to the site's directory or absolute. Files under these paths will be copied to the build output as-is.
- Type:
string[]
Exemplo:
export default {
staticDirectories: ['static'],
};
headTags
An array of tags that will be inserted in the HTML <head>
. The values must be objects that contain two properties; tagName
and attributes
. tagName
must be a string that determines the tag being created; eg "link"
. attributes
must be an attribute-value map.
- Type:
{ tagName: string; attributes: Object; }[]
Exemplo:
export default {
headTags: [
{
tagName: 'link',
attributes: {
rel: 'icon',
href: '/img/docusaurus.png',
},
},
],
};
This would become <link rel="icon" href="img/docusaurus.png" />
in the generated HTML.
scripts
Uma array de scripts para carregar. The values can be either strings or plain objects of attribute-value maps. Os <script>
marcadores serão inseridos no HTML <head>
. If you use a plain object, the only required attribute is src
, and any other attributes are permitted (each one should have boolean/string values).
Note that <script>
added here are render-blocking, so you might want to add async: true
/defer: true
to the objects.
- Type:
(string | Object)[]
Exemplo:
export default {
scripts: [
// String format.
'https://docusaurus.io/script.js',
// Object format.
{
src: 'https://cdnjs.cloudflare.com/ajax/libs/clipboard.js/2.0.0/clipboard.min.js',
async: true,
},
],
};
stylesheets
Uma matriz de fontes CSS a carregar. The values can be either strings or plain objects of attribute-value maps. Os <link>
marcadores serão inseridos no HTML <head>
. If you use an object, the only required attribute is href
, and any other attributes are permitted (each one should have boolean/string values).
- Type:
(string | Object)[]
Exemplo:
export default {
stylesheets: [
// String format.
'https://docusaurus.io/style.css',
// Object format.
{
href: 'http://mydomain.com/style.css',
},
],
};
By default, the <link>
tags will have rel="stylesheet"
, but you can explicitly add a custom rel
value to inject any kind of <link>
tag, not necessarily stylesheets.
clientModules
An array of client modules to load globally on your site.
Exemplo:
export default {
clientModules: ['./mySiteGlobalJs.js', './mySiteGlobalCss.css'],
};
ssrTemplate
Um template HTML escrito na sintaxe Eta que será usado para renderizar sua aplicação. Isto pode ser usado para definir atributos personalizados nas tags body
tags, additional meta
personalizar a viewport
, etc. Please note that Docusaurus will rely on the template to be correctly structured in order to function properly, once you do customize it, you will have to make sure that your template is compliant with the requirements from upstream.
- Tipo:
string
Exemplo:
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>`,
};
titleDelimiter
- Tipo:
string
Will be used as title delimiter in the generated <title>
tag.
Exemplo:
export default {
titleDelimiter: '🦖', // Defaults to `|`
};
baseUrlIssueBanner
- Tipo:
boolean
Quando ativado, irá mostrar um banner caso seu site não consiga carregar seus arquivos CSS ou JavaScript. que é um problema muito comum, geralmente relacionado a um baseUrl
errado na configuração do site.
Exemplo:
export default {
baseUrlIssueBanner: true, // Defaults to `true`
};
This banner needs to inline CSS / JS in case all asset loading fails due to wrong base URL.
Se você tiver uma Política de Segurança de Conteúdorigorosa, você deve desativá-la.