Version: 2.0.0-beta.4

Configuração do tema

Esta configuração se aplica a todos os temas principais.

Comum#

Modo de cor - modo escuro#

O tema clássico fornece, por padrão, suporte ao modo claro e escuro, com um botão de navegação para o usuário.

É possível personalizar o suporte ao modo de cores com a seguinte configuração:

docusaurus.config.js

module.exports = {  // ...  themeConfig: {    // ...    colorMode: {      // "light" | "dark"      defaultMode: 'light',
      // Hides the switch in the navbar      // Useful if you want to support a single color mode      disableSwitch: false,
      // Should we use the prefers-color-scheme media-query,      // using user system preferences, instead of the hardcoded defaultMode      respectPrefersColorScheme: false,
      // Dark/light switch icon options      switchConfig: {        // Icon for the switch while in dark mode        darkIcon: '🌙',
        // CSS to apply to dark icon,        // React inline style object        // see https://reactjs.org/docs/dom-elements.html#style        darkIconStyle: {          marginLeft: '2px',        },
        // Unicode icons such as '\u2600' will work        // Unicode with 5 chars require brackets: '\u{1F602}'        lightIcon: '\u{1F602}',
        lightIconStyle: {          marginLeft: '1px',        },      },    },    // ...  },  // ...};

caution

Com respectPrefersColorScheme: true, o defaultMode é substituído pelas preferências do sistema do usuário.

Se você deseja oferecer suporte a apenas um modo de cor, provavelmente deseja ignorar as preferências do sistema do usuário.

Meta imagem#

Você pode configurar uma imagem padrão que será usada para sua meta tag, em particular og:image e twitter:image.

docusaurus.config.js

module.exports = {  // ...  themeConfig: {    // Relative to your site's "static" directory.    // Não pode ser SVGs. Também podem ser URLs externos.    image: 'img/docusaurus.png',    // ...  },};

Metadados#

Você pode configurar metadados html adicionais (e substituir os existentes).

docusaurus.config.js

module.exports = {  // ...  themeConfig: {    metadados: [{name: 'twitter:card', content: 'summary'}],    // ...  },};

Barra de Anúncios#

Às vezes, você deseja anunciar algo em seu site. Apenas para esse caso, você pode adicionar uma barra de anúncios. Este é um painel não fixo e opcionalmente descartável acima da barra de navegação.

docusaurus.config.js

module.exports = {  // ...  themeConfig: {    announcementBar: {      id: 'support_us', // Qualquer valor que irá identificar esta mensagem.      content:        'Estamos procurando renovar nossos documentos, por favor, preencha <a target="_blank" rel="noopener noreferrer" href="#">esta pesquisa</a>',      backgroundColor: '#fafbfc', // Defaults to `#fff`.      textColor: '#091E42', // Padrão é `#000`.      isCloseable: false, // Padrão é 'true'.    },    // ...  },};

i18n#

Leia a introdução i18n primeiro.

Localização dos arquivos de tradução#

Caminho base: website/i18n/<locale>/docusaurus-theme-<themeName>
Caminho de multi-instância: N/A
Arquivos JSON: extraídos com docusaurus escreveu-traduções
Arquivos Markdown: N/A

Exemplo de estrutura de sistema de arquivos#

website/i18n/<locale>/docusaurus-theme-classic├├# traduções para o tema── navbar.json── footer.json

Ganchos#

`useThemeContext`#

React hook para acessar o contexto do tema. Este contexto contém funções para definir o modo claro e escuro e expõe a variável booleana, indicando qual modo está em uso no momento.

Exemplo de uso:

import React from 'react';import useThemeContext from '@theme/hooks/useThemeContext';
const Example = () => {  const {isDarkTheme, setLightTheme, setDarkTheme} = useThemeContext();
  retornar <h1>Modo escuro agora é {isDarkTheme ? 'on' : 'off'}</h1>;};

note

O componente que chama useThemeContext deve ser filho do componente Layout.

function ExamplePage() {  return (    <Layout>      <Example />    </Layout>  );}

Barra de navegação#

Título da barra de navegação & logotipo#

Você pode adicionar o logotipo e título à barra de navegação através do themeConfig.navbar. O logotipo pode ser colocado na pasta estática. O URL do logotipo é definido como base para o URL do seu site por padrão. Embora você possa especificar sua própria URL para o logotipo, se for um link externo, ele será aberto em uma nova guia. Além disso, você pode substituir um valor para o atributo alvo do link do logotipo, ele pode ser útil se você estiver hospedando documentos em um subdiretório do seu site principal, e nesse caso você provavelmente não precisa de um link no logotipo para o site principal será aberto em uma nova guia.

Para melhorar o suporte ao modo escuro, você também pode definir um logotipo diferente para este modo.

docusaurus.config.js

module.exports = {  // ...  themeConfig: {    navbar: {      title: 'Site Title',      logo: {        alt: 'Site Logo',        src: 'img/logo.svg',        srcDark: 'img/logo_dark.svg', // Por padrão, `logo.src`.        href: 'https://docusaurus.io/', // Pro padrão, `siteConfig.baseUrl`.        target: '_self', // Por padrão, este valor é calculado com base no atributo `href` (o link externo será aberto em uma nova aba, todos os outros na atual).      },    },    // ...  },};

Itens da barra de navegação#

Você pode adicionar itens à barra de navegação por meio de themeConfig.navbar.items.

docusaurus.config.js

module.exports = {  // ...  themeConfig: {    navbar: {      items: [        {          type: 'doc',          position: 'left',          docId: 'introduction',          label: 'Docs',        },        {to: 'blog', label: 'Blog', position: 'left'},        {          type: 'docsVersionDropdown',          position: 'right',        },        {          type: 'localeDropdown',          position: 'right',        },        {          href: 'https://github.com/facebook/docusaurus',          position: 'right',          className: 'header-github-link',          'aria-label': 'GitHub repository',        },      ],    },    // ...  },};

Os itens podem ter comportamentos diferentes com base no campo type. As seções a seguir apresentarão a você todos os tipos de itens disponíveis na barra de navegação.

Link da barra de navegação#

Por padrão, os itens da barra de navegação são links regulares (interno ou externo).

O React Router deve aplicar automaticamente o estilo do link ativo aos links, mas você pode usar activeBasePath em casos extremos. Para casos em que um link deve estar ativo em vários caminhos diferentes (como quando você tem várias pastas de documentos na mesma barra lateral), você pode usar activeBaseRegex. activeBaseRegex é uma alternativa mais flexível para activeBasePath e tem precedência sobre ele -- o Docusaurus analisa em uma expressão regular que é testada contra a URL atual.

Os links externos (externos) obtêm atributos target="_blank" rel="noopener noreferrer" automaticamente.

Campos aceitos:

Campo	Valor	Explicação	Obrigatório	Padrão
`label`	`string`	O nome a ser mostrado para este item.	Sim
`to`	`string`	Roteamento do lado do cliente, usado para navegar no site. O baseUrl será adicionado automaticamente a este valor.	Sim
`href`	`string`	Uma navegação de página inteira, usada para navegar fora do site. Apenas um `to` ou `href` deve ser usado.	Sim
`prependBaseUrlToHref`	`boolean`	Prepara os valores baseUrl para `href`.	Não	`false`
`position`	`'left' \| 'right'`	O lado da barra de navegação em que este item deve aparecer.	Não	`'left'`
`activeBasePath`	`string`	Para aplicar o estilo de classe ativo em todas as rotas que começam com este caminho. Isto geralmente não é necessário.	Não	`to` / `href`
`activeBaseRegex`	`string`	Alternativa para `activeBasePath` se necessário.	Não	`undefined`
`className`	`string`	Classe CSS personalizada (para definir o estilo de qualquer item).	Não	`''`

Configuração de exemplo:

docusaurus.config.js

module.exports = {  themeConfig: {    navbar: {      items: [        {          to: 'docs/introduction',          // Apenas um "to" ou "href" deve ser usado          // href: 'https://www.facebook.com',          label: 'Introduction',          position: 'left',          activeBaseRegex: 'docs/(next|v8)',        },      ],    },  },};

Lista suspensa da barra de navegação#

Os itens da barra de navegação do tipo dropdown têm o campo itens adicional, uma matriz interna de itens da barra de navegação.

Itens suspensos da barra de navegação só aceitam os seguintes tipos de itens "link-like":

Link da barra de navegação
Link de doc na barra de navegação
Versão do documento Navbar

Note que o item de base suspenso também é um link clicável para que este item possa receber qualquer uma das propriedades de um link simples da barra de navegação.

Campos aceitos:

Campo	Valor	Explicação	Obrigatório	Padrão
`label`	`string`	O nome a ser mostrado para este item.	Sim
`items`	`LinkLikeItem[]`	Os itens a serem contidos na lista suspensa.	Sim
`position`	`'left' \| 'right'`	O lado da barra de navegação em que este item deve aparecer.	Não	`'left'`

Configuração de exemplo:

docusaurus.config.js

module.exports = {  themeConfig: {    navbar: {      items: [        {          type: 'dropdown',          label: 'Community',          position: 'left',          items: [            {              label: 'Facebook',              href: 'https://www.facebook.com',            },            {              type: 'doc',              label: 'Social',              docId: 'social',            },            // ... more items          ],        },      ],    },  },};

Link de doc na barra de navegação#

Se você deseja vincular a uma documentação específica, esse tipo especial de item da barra de navegação irá renderizar o link para o documento do docId fornecido. Ele obterá a classe navbar__link--active contanto que você navegue em um documento da mesma barra lateral.

Campos aceitos:

Campo	Valor	Explicação	Obrigatório	Padrão
`docId`	`string`	O ID do documento ao qual este item está vinculado.	Sim
`label`	`string`	O nome a ser mostrado para este item.	Não	`docId`
`position`	`'left' \| 'right'`	O lado da barra de navegação em que este item deve aparecer.	Não	`'left'`
`activeSidebarClassName`	`string`	O nome da classe CSS a ser aplicada quando a barra lateral deste documento estiver ativa.	Não	`'navbar__link--active'`
`docsPluginId`	`string`	O ID do plugin do docs ao qual o doc pertence.	Não	`'default'`

Configuração de exemplo:

docusaurus.config.js

módulo xports = {  themeConfig: {    navbar: {      items: [        {          type: 'doc',          posição: 'esquerda',          docId: 'Introdução',          rótulo: 'Documentos',        },        // realçar-fim      ],    },  },};

Lista suspensa de versões de documentos da Navbar#

Se você usa documentos com versões, este tipo de item especial da barra de navegação que irá exibir todas as versões disponíveis do seu site.

O usuário poderá mudar de uma versão para outra enquanto ficar no mesmo documento (desde que o id do documento seja constante entre versões).

Campos aceitos:

Campo	Valor	Explicação	Obrigatório	Padrão
`position`	`'left' \| 'right'`	O lado da barra de navegação em que este item deve aparecer.	Não	`'left'`
`dropdownItemsBefore`	`LinkLikeItem[]`	Adicione outros itens suspensos no início da lista suspensa.	Não	`[]`
`dropdownItemsAfter`	`LinkLikeItem[]`	Adicione outros itens suspensos no final da lista suspensa.	Não	`[]`
`docsPluginId`	`string`	O ID do plugin docs ao qual pertence o controle de versão.	Não	`'default'`
`dropdownActiveClassDisabled`	`boolean`	Não adicionar o link da classe ativa ao navegar pela documentação.	Não	`false`

Configuração de exemplo:

docusaurus.config.js

module.exports = {  themeConfig: {    navbar: {      items: [        {          type: 'docsVersionDropdown',          position: 'left',          dropdownItemsAfter: [{to: '/versions', label: 'All versions'}],          dropdownActiveClassDisabled: true,        },      ],    },  },};

Versão dos docs da Navbar#

Se você usar documentos com versão, esse tipo de item especial da barra de navegação irá vincular com a versão ativa/navegada do seu documento (depende da URL atual), e voltar para a versão mais recente.

Campos aceitos:

Campo	Valor	Explicação	Obrigatório	Padrão
`label`	`string`	O nome a ser mostrado para este item.	Não	O rótulo de versão ativa/mais recente.
`to`	`string`	O link interno para o qual este item aponta.	Não	A versão ativa/mais recente.
`position`	`'left' \| 'right'`	O lado da barra de navegação em que este item deve aparecer.	Não	`'left'`
`docsPluginId`	`string`	O ID do plugin docs ao qual pertence o controle de versão.	Não	`'default'`

Configuração de exemplo:

docusaurus.config.js

module.exports = {  themeConfig: {    navbar: {      items: [        {          type: 'docsVersion',          position: 'left',          to: '/path',          label: 'label',        },      ],    },  },};

Menu suspenso de localidade da Navbar#

Se você usar o i18n feature, este tipo de item especial da barra de navegação irá renderizar um menu suspenso com todas as localidades disponíveis do seu site.

O usuário poderá mudar de uma localidade para outra, enquanto permanece na mesma página.

Campos aceitos:

Campo	Valor	Explicação	Obrigatório	Padrão
`position`	`'left' \| 'right'`	O lado da barra de navegação em que este item deve aparecer.	Não	`'left'`
`dropdownItemsBefore`	`LinkLikeItem[]`	Adicione outros itens suspensos no início da lista suspensa.	Não	`[]`
`dropdownItemsAfter`	`LinkLikeItem[]`	Adicione outros itens suspensos no final da lista suspensa.	Não	`[]`

Configuração de exemplo:

docusaurus.config.js

module.exports = {  themeConfig: {    navbar: {      items: [        {          type: 'localeDropdown',          position: 'left',          dropdownItemsAfter: [            {              to: 'https://my-site.com/help-us-translate',              label: 'Help us translate',            },          ],        },      ],    },  },};

Pesquisa na Navbar#

Se você usar a pesquisa, a barra de pesquisa será o elemento mais à direita na barra de navegação.

No entanto, com este tipo de item especial da barra de navegação, você pode mudar o local padrão.

Campo	Valor	Explicação	Obrigatório	Padrão
`position`	`'left' \| 'right'`	O lado da barra de navegação em que este item deve aparecer.	Não	`'left'`

docusaurus.config.js

module.exports = {  themeConfig: {    navbar: {      items: [        {          type: 'search',          position: 'right',        },      ],    },  },};

Auto-ocultar a barra de navegação#

Você pode ativar esta interface de usuário legal que automaticamente oculta a barra de navegação quando um usuário começa a rolar para baixo a página, e mostrar novamente quando o usuário rola para cima.

docusaurus.config.js

module.exports = {  // ...  themeConfig: {    navbar: {      hideOnScroll: true,    },    // ...  },};

Estilo barra de navegação#

Você pode definir o estilo estático da barra de navegação sem desativar a habilidade de mudar de tema. O estilo selecionado sempre será aplicado, não importa qual usuário de tema tenha selecionado.

Atualmente, existem duas possíveis opções de estilo: dark e primary (baseado na cor --ifm-color-primary). Você pode ver a pré-visualização de estilos na documentação da Infima.

docusaurus.config.js

module.exports = {  // ...  themeConfig: {    navbar: {      style: 'primary',    },    // ...  },};

CodeBlock#

O Docusaurus usa Prism React Renderer para destacar blocos de código.

Tema#

Por padrão, usamos Palenight como tema de destaque de sintaxe. É possível especificar um tema personalizado da lista de temas disponíveis. Se você quiser usar um tema de destaque de sintaxe diferente quando o site estiver no modo escuro, você também pode fazer isso.

docusaurus.config.js

module.exports = {  // ...  themeConfig: {    prism: {      theme: require('prism-react-renderer/themes/github'),      darkTheme: require('prism-react-renderer/themes/dracula'),    },    // ...  },};

note

Se você usar a linha que destaca a sintaxe Markdown, talvez seja necessário especificar uma cor de destaque diferente para o tema de destaque do modo escuro. Consulte a documentação para obter orientação.

Idioma padrão#

Você pode definir uma linguagem padrão para blocos de código se nenhuma língua for adicionada após a tripla quantidade de backticks de abertura (ou seja, ```). Observe que um nome de idioma válido deve ser passado, por exemplo.:

docusaurus.config.js

module.exports = {  // ...  themeConfig: {    prism: {      defaultLanguage: 'javascript',    },    // ...  },};

Rodapé#

Pode adicionar o logotipo e um direito autoral ao rodapé através do themeConfig.footer. O logotipo pode ser colocado na pasta estática. A URL do logotipo funciona da mesma maneira do logotipo da barra de navegação.

docusaurus.config.js

  // ...  footer: {    logo: {      alt: 'Facebook Open Source Logo',      src: 'img/oss_logo.png',      href: 'https://opensource.facebook.com',    },    copyright: `Copyright © ${new Date().getFullYear()} My Project, Inc. Built with Docusaurus.`,  }

Links do rodapé#

Você pode adicionar links ao rodapé através do themeConfig.footer.links:

docusaurus.config.js

module.exports = {  // ...  footer: {    links: [      {        // Label of the section of these links        title: 'Docs',        items: [          {            // Label of the link            label: 'Style Guide',            // Client-side routing, used for navigating within the website.            // The baseUrl will be automatically prepended to this value.            to: 'docs/',          },          {            label: 'Second Doc',            to: 'docs/doc2/',          },        ],      },      {        title: 'Community',        items: [          {            label: 'Stack Overflow',            // A full-page navigation, used for navigating outside of the website.            href: 'https://stackoverflow.com/questions/tagged/docusaurus',          },          {            label: 'Discord',            href: 'https://discordapp.com/invite/docusaurus',          },          {            label: 'Twitter',            href: 'https://twitter.com/docusaurus',          },          {            //Renders the html pass-through instead of a simple link            html: `                <a href="https://www.netlify.com" target="_blank" rel="noreferrer noopener" aria-label="Deploys by Netlify">                  <img src="https://www.netlify.com/img/global/badges/netlify-color-accent.svg" alt="Deploys by Netlify" />                </a>              `,          },        ],      },    ],  },};

Comum#

Modo de cor - modo escuro#

caution

Meta imagem#

Metadados#

Barra de Anúncios#

i18n#

Localização dos arquivos de tradução#

Exemplo de estrutura de sistema de arquivos#

Ganchos#

useThemeContext#

note

Barra de navegação#

Título da barra de navegação & logotipo#

Itens da barra de navegação#

Link da barra de navegação#

Lista suspensa da barra de navegação#

Link de doc na barra de navegação#

Lista suspensa de versões de documentos da Navbar#

Versão dos docs da Navbar#

Menu suspenso de localidade da Navbar#

Pesquisa na Navbar#

Auto-ocultar a barra de navegação#

Estilo barra de navegação#

CodeBlock#

Tema#

note

Idioma padrão#

Rodapé#

Links do rodapé#

`useThemeContext`#