Configuração
Check the docusaurus.config.js
API reference for an exhaustive list of options.
Docusaurus tem uma visão única das configurações. We encourage you to congregate information about your site into one place. We guard the fields of this file and facilitate making this data object accessible across your site.
Keeping a well-maintained docusaurus.config.js
helps you, your collaborators, and your open source contributors to be able to focus on documentation while still being able to customize the site.
Syntax to declare docusaurus.config.js
The docusaurus.config.js
file is run in Node.js and should export either:
- a config object
- a function that creates the config object
The docusaurus.config.js
file supports:
Constraints:
- Required: use
export default /* your config*/
(ormodule.exports
) to export your Docusaurus config - Optional: use
import Lib from 'lib'
(orrequire('lib')
) to import Node.js packages
Docusaurus gives us the ability to declare its configuration in various equivalent ways, and all the following config examples lead to the exact same result:
export default {
title: 'Docusaurus',
url: 'https://docusaurus.io',
// your site config ...
};
module.exports = {
title: 'Docusaurus',
url: 'https://docusaurus.io',
// your site config ...
};
import type {Config} from '@docusaurus/types';
export default {
title: 'Docusaurus',
url: 'https://docusaurus.io',
// your site config ...
} satisfies Config;
const config = {
title: 'Docusaurus',
url: 'https://docusaurus.io',
// your site config ...
};
export default config;
export default function configCreator() {
return {
title: 'Docusaurus',
url: 'https://docusaurus.io',
// your site config ...
};
}
export default async function createConfigAsync() {
return {
title: 'Docusaurus',
url: 'https://docusaurus.io',
// your site config ...
};
}
Using an async config creator can be useful to import ESM-only modules (notably most Remark plugins). It is possible to import such modules thanks to dynamic imports:
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.io',
// rest of your site config...
};
}
O que vai para no docusaurus.config.js
?
Você não deve precisar escrever o seu docusaurus.config.js
do zero, mesmo que você esteja desenvolvendo seu site. Todos os modelos vêm com um docusaurus.config.js
que inclui o padrão para as opções comuns.
No entanto, pode ser útil se você tiver um alto nível de compreensão de como as configurações são projetadas e implementadas.
A visão geral de alto nível da configuração do Docusaurus pode ser categorizada em:
Metadados do site
Site metadata contains the essential global metadata such as title
, url
, baseUrl
, and favicon
.
They are used in several places such as your site's title and headings, browser tab icon, social sharing (Facebook, X) information or even to generate the correct path to serve your static files.
Configurações de implantação
Deployment configurations such as projectName
, organizationName
, and optionally deploymentBranch
are used when you deploy your site with the deploy
command.
É recomendável verificar a documentação de implantação para obter mais informações.
Configurações de tema, plugin e predefinição
List the themes, plugins, and presets for your site in the themes
, plugins
, and presets
fields, respectively. Estes são normalmente pacotes npm:
export default {
// ...
plugins: [
'@docusaurus/plugin-content-blog',
'@docusaurus/plugin-content-pages',
],
themes: ['@docusaurus/theme-classic'],
};
Docusaurus supports module shorthands, allowing you to simplify the above configuration as:
export default {
// ...
plugins: ['content-blog', 'content-pages'],
themes: ['classic'],
};
Eles também podem ser carregados a partir de diretórios locais:
import path from 'path';
export default {
// ...
themes: [path.resolve(__dirname, '/path/to/docusaurus-local-theme')],
};
Para especificar opções para um plugin ou tema, substitua o nome do plugin ou tema no arquivo de configuração por uma matriz contendo o nome e um objeto de opções:
export default {
// ...
plugins: [
[
'content-blog',
{
path: 'blog',
routeBasePath: 'blog',
include: ['*.md', '*.mdx'],
// ...
},
],
'content-pages',
],
};
Para especificar opções para um plugin ou tema que está incluído em uma predefinição, passe as opções por meio do campo presets
. Neste exemplo, docs
refere-se a @docusaurus/plugin-content-docs
e theme
refere-se ao @docusaurus/theme-classic
.
export default {
// ...
presets: [
[
'@docusaurus/preset-classic',
{
docs: {
sidebarPath: './sidebars.js',
},
theme: {
customCss: ['./src/css/custom.css'],
},
},
],
],
};
The presets: [['classic', {...}]]
shorthand works as well.
For further help configuring themes, plugins, and presets, see Using Plugins.
Configurações personalizadas
Docusaurus guards docusaurus.config.js
from unknown fields. Para adicionar campos personalizados, defina-os em customFields
.
Exemplo:
export default {
// ...
customFields: {
image: '',
keywords: [],
},
// ...
};
Acessando configuração de componentes
Seu objeto de configuração será disponibilizado para todos os componentes do seu site. E você pode acessá-los via contexto React como siteConfig
.
Exemplo básico:
import React from 'react';
import useDocusaurusContext from '@docusaurus/useDocusaurusContext';
const Hello = () => {
const {siteConfig} = useDocusaurusContext();
const {title, tagline} = siteConfig;
return <div>{`${title} · ${tagline}`}</div>;
};
Se você deseja apenas usar esses campos no lado do cliente, pode criar seus próprios arquivos JS e importá-los como módulos ES6, não há necessidade de colocá-los em docusaurus.config.js
.
Personalização da configuração do Babel
Docusaurus transpiles your site's source code using Babel by default. If you want to customize the Babel configuration, you can do so by creating a babel.config.js
file in your project root.
To use the built-in preset as a base configuration, install the following package and use it
- npm
- Yarn
- pnpm
npm install --save @docusaurus/theme-live-codeblock
yarn add @docusaurus/theme-live-codeblock
pnpm add @docusaurus/theme-live-codeblock
Then use the preset in your babel.config.js
file:
export default {
presets: ['@docusaurus/babel/preset'],
};
Most of the time, the default preset configuration will work just fine. If you want to customize your Babel configuration (e.g. to add support for Flow), you can directly edit this file. For your changes to take effect, you need to restart the Docusaurus dev server.