Ir para o conteúdo principal
Version: 2.0.0-beta.10

Configuração

Docusaurus tem uma visão única das configurações. Nós o encorajamos a reunir as informações do seu site em um só lugar. Protegemos os campos desse arquivo e facilitamos o acesso a esse objeto de dados em seu site.

Manter um docusaurus.config.js bem mantido ajuda você, seus colaboradores e seus contribuidores de código aberto a se concentrarem na documentação e, ao mesmo tempo, personalizar o site.

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:

Para referência exata a cada um dos campos configuráveis, você pode se referir a docusaurus.config.js referência da API.

Metadados do site

Os metadados do site contém metadados globais essenciais, como title, url, baseUrl e favicon.

Eles são usados em vários lugares como o título e os cabeçalhos do seu site, o ícone da aba do navegador, compartilhamento social (Facebook, Twitter) informações ou até mesmo para gerar o caminho correto para servir os seus arquivos estáticos.

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

Lista o tema, plug-ins, e predefinições para o seu site nos temas, plugins e predefinições de campos, respectivamente. Estes são normalmente pacotes npm:

docusaurus.config.js
module.exports = {
// ...
plugins: [
'@docusaurus/plugin-content-blog',
'@docusaurus/plugin-content-pages',
],
themes: ['@docusaurus/theme-classic'],
};
tip

Docusaurus supports module shorthands, allowing you to simplify the above configuration as:

docusaurus.config.js
module.exports = {
// ...
plugins: ['content-blog', 'content-pages'],
themes: ['classic'],
};
How are shorthands resolved?

When it sees a plugin / theme / preset name, it tries to load one of the following, in that order:

  • {name}
  • @docusaurus/{type}-{name}
  • docusaurus-{type}-{name},

where type is one of 'preset', 'theme', 'plugin', depending on which field the module name is declared in. The first module name that's successfully found is loaded.

If the name is scoped (beginning with @), the name is first split into scope and package name by the first slash:

@scope
^----^
scope (no name!)

@scope/awesome
^----^ ^-----^
scope name

@scope/awesome/main
^----^ ^----------^
scope name

If the name is not specified, {scope}/docusaurus-{type} is loaded. Otherwise, the following are attempted:

  • {scope}/{name}
  • {scope}/docusaurus-{type}-{name}

Below are some examples, for a plugin registered in the plugins field. Note that unlike ESLint or Babel where a consistent naming convention for plugins is mandated, Docusaurus permits greater naming freedom, so the resolutions are not certain, but follows the priority defined above.

DeclarationMay be resolved as
awesomedocusaurus-plugin-awesome
sitemap@docusaurus/plugin-sitemap
@mycompany@mycompany/docusaurus-plugin (the only possible resolution!)
@mycompany/awesome@mycompany/docusaurus-plugin-awesome
@mycompany/awesome/web@mycompany/docusaurus-plugin-awesome/web

Eles também podem ser carregados a partir de diretórios locais:

docusaurus.config.js
const path = require('path');

module.exports = {
// ...
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:

docusaurus.config.js
module.exports = {
// ...
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.

docusaurus.config.js
module.exports = {
// ...
presets: [
[
'@docusaurus/preset-classic',
{
docs: {
sidebarPath: require.resolve('./sidebars.js'),
},
theme: {
customCss: [require.resolve('./src/css/custom.css')],
},
},
],
],
};
tip

The presets: [['classic', {...}]] shorthand works as well.

Para obter mais ajuda na configuração de temas, plug-ins e predefinições, consulte Usando temas, Usando plug-ins, e Usando predefinições.

Configurações personalizadas

Docusaurus guarda docusaurus.config.js de campos desconhecidos. Para adicionar campos personalizados, defina-os em customFields.

Exemplo:

docusaurus.config.js
module.exports = {
// ...
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>;
};
tip

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

Para novos projetos Docusaurus, geramos automaticamente um babel.config.js na raiz do projeto.

babel.config.js
module.exports = {
presets: [require.resolve('@docusaurus/core/lib/babel/preset')],
};

Na maioria das vezes, esta configuração funcionará bem. Se você deseja personalizá-lo, você pode editar este arquivo diretamente para personalizar a configuração do babel. Para que suas alterações tenham efeito, você precisa reiniciar o Docusaurus devserver.