Pular para o conteúdo principal
Version: 3.0.0-rc.1

Configuração do tema

This configuration applies to all main themes.

Common​

Color mode​

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.

It is possible to customize the color mode support within the colorMode object.

Campos aceitos:

NomeTypePadrãoDescrição
defaultMode'light' | 'dark''light'The color mode when user first visits the site.
disableSwitchbooleanfalseHides the switch in the navbar. Useful if you want to support a single color mode.
respectPrefersColorSchemebooleanfalseWhether to use the prefers-color-scheme media-query, using user system preferences, instead of the hardcoded defaultMode.

Configuração de exemplo:

docusaurus.config.js
export default {
  themeConfig: {
    colorMode: {
      defaultMode: 'light',
      disableSwitch: false,
      respectPrefersColorScheme: false,
    },
  },
};
warning

With respectPrefersColorScheme: true, the defaultMode is overridden by user system preferences.

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

Meta image​

You can configure a default image that will be used for your meta tag, in particular og:image and twitter:image.

Campos aceitos:

NomeTypePadrãoDescrição
imagestringundefinedThe meta image URL for the site. Relative to your site's "static" directory. Cannot be SVGs. Também podem ser URLs externos.

Configuração de exemplo:

docusaurus.config.js
export default {
  themeConfig: {
    image: 'img/docusaurus.png',
  },
};

Metadata​

You can configure additional HTML metadata (and override existing ones).

Campos aceitos:

NomeTypePadrãoDescrição
metadataMetadata[][]Any field will be directly passed to the <meta /> tag. Possible fields include id, name, property, content, itemprop, etc.

Configuração de exemplo:

docusaurus.config.js
export default {
  themeConfig: {
    metadata: [{name: 'twitter:card', content: 'summary'}],
  },
};

Announcement bar​

Às vezes, você deseja anunciar algo em seu site. Apenas para esse caso, você pode adicionar uma barra de anúncios. This is a non-fixed and optionally dismissible panel above the navbar. All configuration are in the announcementBar object.

Campos aceitos:

NomeTypePadrãoDescrição
idstring'announcement-bar'Any value that will identify this message.
contentstring''The text content of the announcement. HTML will be interpolated.
backgroundColorstring'#fff'Background color of the entire bar.
textColorstring'#000'Announcement text color.
isCloseablebooleantrueWhether this announcement can be dismissed with a '×' button.

Configuração de exemplo:

docusaurus.config.js
export default {
  themeConfig: {
    announcementBar: {
      id: 'support_us',
      content:
        'We are looking to revamp our docs, please fill <a target="_blank" rel="noopener noreferrer" href="#">this survey</a>',
      backgroundColor: '#fafbfc',
      textColor: '#091E42',
      isCloseable: false,
    },
  },
};

Campos aceitos:

NomeTypePadrãoDescrição

The logo can be placed in static folder. 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.

Campos aceitos:

NomeTypePadrãoDescrição

Configuração de exemplo:

docusaurus.config.js
export default {
  themeConfig: {
    navbar: {
      title: 'Site Title',
      logo: {
        alt: 'Site Logo',
        src: 'img/logo.svg',
        srcDark: 'img/logo_dark.svg',
        href: 'https://docusaurus.io/',
        target: '_self',
        width: 32,
        height: 32,
        className: 'custom-navbar-logo-class',
        style: {border: 'solid red'},
      },
    },
  },
};

You can add items to the navbar via themeConfig.navbar.items.

docusaurus.config.js
export default {
  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',
        },
      ],
    },
  },
};

The items can have different behaviors based on the type field. As seções a seguir apresentarão a você todos os tipos de itens disponíveis na barra de navegação.

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

React Router should automatically apply active link styling to links, but you can use activeBasePath in edge cases. For cases in which a link should be active on several different paths (such as when you have multiple doc folders under the same sidebar), you can use activeBaseRegex. activeBaseRegex is a more flexible alternative to activeBasePath and takes precedence over it -- Docusaurus parses it into a regular expression that is tested against the current URL.

Outbound (external) links automatically get target="_blank" rel="noopener noreferrer" attributes.

Campos aceitos:

NomeTypePadrãoDescrição
note

In addition to the fields above, you can specify other arbitrary attributes that can be applied to a HTML link.

Configuração de exemplo:

docusaurus.config.js
export default {
  themeConfig: {
    navbar: {
      items: [
        {
          to: 'docs/introduction',
          // Only one of "to" or "href" should be used
          // href: 'https://www.facebook.com',
          label: 'Introduction',
          // Only one of "label" or "html" should be used
          // html: '<b>Introduction</b>'
          position: 'left',
          activeBaseRegex: 'docs/(next|v8)',
          target: '_blank',
        },
      ],
    },
  },
};

Navbar items of the type dropdown has the additional items field, an inner array of navbar items.

Navbar dropdown items only accept the following "link-like" item types:

Note that the dropdown base item is a clickable link as well, so this item can receive any of the props of a plain navbar link.

Campos aceitos:

NomeTypePadrãoDescrição

Configuração de exemplo:

docusaurus.config.js
export default {
  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
          ],
        },
      ],
    },
  },
};

If you want to link to a specific doc, this special navbar item type will render the link to the doc of the provided docId. It will get the class navbar__link--active as long as you browse a doc of the same sidebar.

Campos aceitos:

NomeTypePadrãoDescrição

Configuração de exemplo:

docusaurus.config.js
export default {
  themeConfig: {
    navbar: {
      items: [
        {
          type: 'doc',
          position: 'left',
          docId: 'introduction',
          label: 'Docs',
        },
      ],
    },
  },
};

You can link a navbar item to the first document link (which can be a doc link or a generated category index) of a given sidebar without having to hardcode a doc ID.

Campos aceitos:

NomeTypePadrãoDescrição
tip

Use this navbar item type if your sidebar is updated often and the order is not stable.

Configuração de exemplo:

docusaurus.config.js
export default {
  themeConfig: {
    navbar: {
      items: [
        {
          type: 'docSidebar',
          position: 'left',
          sidebarId: 'api',
          label: 'API',
        },
      ],
    },
  },
};
sidebars.js
export default {
  tutorial: [
    {
      type: 'autogenerated',
      dirName: 'guides',
    },
  ],
  api: [
    'cli', // The navbar item will be linking to this doc
    'docusaurus-core',
    {
      type: 'autogenerated',
      dirName: 'api',
    },
  ],
};

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.

The user will be able to switch from one version to another, while staying on the same doc (as long as the doc ID is constant across versions).

Campos aceitos:

NomeTypePadrãoDescrição

Configuração de exemplo:

docusaurus.config.js
export default {
  themeConfig: {
    navbar: {
      items: [
        {
          type: 'docsVersionDropdown',
          position: 'left',
          dropdownItemsAfter: [{to: '/versions', label: 'All versions'}],
          dropdownActiveClassDisabled: true,
        },
      ],
    },
  },
};

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:

NomeTypePadrãoDescrição

Configuração de exemplo:

docusaurus.config.js
export default {
  themeConfig: {
    navbar: {
      items: [
        {
          type: 'docsVersion',
          position: 'left',
          to: '/path',
          label: 'label',
        },
      ],
    },
  },
};

If you use the i18n feature, this special navbar item type will render a dropdown with all your site's available locales.

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

Campos aceitos:

NomeTypePadrãoDescrição

Configuração de exemplo:

docusaurus.config.js
export default {
  themeConfig: {
    navbar: {
      items: [
        {
          type: 'localeDropdown',
          position: 'left',
          dropdownItemsAfter: [
            {
              to: 'https://my-site.com/help-us-translate',
              label: 'Help us translate',
            },
          ],
        },
      ],
    },
  },
};

If you use the search, the search bar will be the rightmost element in the navbar.

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

NomeTypePadrãoDescrição
docusaurus.config.js
export default {
  themeConfig: {
    navbar: {
      items: [
        {
          type: 'search',
          position: 'right',
        },
      ],
    },
  },
};

You can also render your own HTML markup inside a navbar item using this navbar item type.

NomeTypePadrãoDescrição
docusaurus.config.js
export default {
  themeConfig: {
    navbar: {
      items: [
        {
          type: 'html',
          position: 'right',
          value: '<button>Give feedback</button>',
        },
      ],
    },
  },
};

Auto-hide sticky navbar​

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
export default {
  themeConfig: {
    navbar: {
      hideOnScroll: true,
    },
  },
};

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.

Currently, there are two possible style options: dark and primary (based on the --ifm-color-primary color). You can see the styles preview in the Infima documentation.

docusaurus.config.js
export default {
  themeConfig: {
    navbar: {
      style: 'primary',
    },
  },
};

CodeBlock​

Docusaurus uses Prism React Renderer to highlight code blocks. All configuration are in the prism object.

Campos aceitos:

NomeTypePadrãoDescrição
themePrismThemepalenightThe Prism theme to use for light-theme code blocks.
darkThemePrismThemepalenightThe Prism theme to use for dark-theme code blocks.
defaultLanguagestringundefinedThe default language to use for code blocks not declaring any explicit language.
magicCommentsMagicCommentConfig[]see belowThe list of magic comments.
type MagicCommentConfig = {
  className: string;
  line?: string;
  block?: {start: string; end: string};
};
const defaultMagicComments = [
  {
    className: 'theme-code-block-highlighted-line',
    line: 'highlight-next-line',
    block: {start: 'highlight-start', end: 'highlight-end'},
  },
];

Theme​

By default, we use Palenight as syntax highlighting theme. You can specify a custom theme from the list of available themes. You may also use a different syntax highlighting theme when the site is in dark mode.

Configuração de exemplo:

docusaurus.config.js
import {themes as prismThemes} from 'prism-react-renderer';

export default {
  themeConfig: {
    prism: {
      theme: prismThemes.github,
      darkTheme: prismThemes.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. Refer to the docs for guidance.

Default language​

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, ```). Note that a valid language name must be passed.

Configuração de exemplo:

docusaurus.config.js
export default {
  themeConfig: {
    prism: {
      defaultLanguage: 'javascript',
    },
  },
};

You can add logo and a copyright to the footer via themeConfig.footer. Logo can be placed in static folder. A URL do logotipo funciona da mesma maneira do logotipo da barra de navegação.

Campos aceitos:

NomeTypePadrãoDescrição

Configuração de exemplo:

docusaurus.config.js
export default {
  themeConfig: {
    footer: {
      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()} My Project, Inc. Built with Docusaurus.`,
    },
  },
};

You can add links to the footer via themeConfig.footer.links. There are two types of footer configurations: multi-column footers and simple footers.

Multi-column footer links have a title and a list of FooterItems for each column.

NomeTypePadrãoDescrição

Accepted fields of each FooterItem:

NomeTypePadrãoDescrição

Example multi-column configuration:

docusaurus.config.js
export default {
  footer: {
    links: [
      {
        title: 'Docs',
        items: [
          {
            label: 'Style Guide',
            to: 'docs/',
          },
          {
            label: 'Second Doc',
            to: 'docs/doc2/',
          },
        ],
      },
      {
        title: 'Community',
        items: [
          {
            label: 'Stack Overflow',
            href: 'https://stackoverflow.com/questions/tagged/docusaurus',
          },
          {
            label: 'Discord',
            href: 'https://discordapp.com/invite/docusaurus',
          },
          {
            label: 'Twitter',
            href: 'https://twitter.com/docusaurus',
          },
          {
            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" width="114" height="51" />
                </a>
              `,
          },
        ],
      },
    ],
  },
};

A simple footer just has a list of FooterItems displayed in a row.

Example simple configuration:

docusaurus.config.js
export default {
  footer: {
    links: [
      {
        label: 'Stack Overflow',
        href: 'https://stackoverflow.com/questions/tagged/docusaurus',
      },
      {
        label: 'Discord',
        href: 'https://discordapp.com/invite/docusaurus',
      },
      {
        label: 'Twitter',
        href: 'https://twitter.com/docusaurus',
      },
      {
        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" width="114" height="51" />
            </a>
          `,
      },
    ],
  },
};

Table of Contents​

You can adjust the default table of contents via themeConfig.tableOfContents.

NomeTypePadrãoDescrição
minHeadingLevelnumber2The minimum heading level shown in the table of contents. Must be between 2 and 6 and lower or equal to the max value.
maxHeadingLevelnumber3Max heading level displayed in the TOC. Should be an integer between 2 and 6.

Configuração de exemplo:

docusaurus.config.js
export default {
  themeConfig: {
    tableOfContents: {
      minHeadingLevel: 2,
      maxHeadingLevel: 5,
    },
  },
};

Hooks​

useColorMode​

A React hook to access the color context. 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 {useColorMode} from '@docusaurus/theme-common';

const Example = () => {
  const {colorMode, setColorMode} = useColorMode();

  return <h1>Dark mode is now {colorMode === 'dark' ? 'on' : 'off'}</h1>;
};
note

The component calling useColorMode must be a child of the Layout component.

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

i18n​

Read the i18n introduction first.

Translation files location​

  • Base path: website/i18n/[locale]/docusaurus-theme-[themeName]
  • Multi-instance path: N/A
  • JSON files: extracted with docusaurus write-translations
  • Markdown files: N/A

Example file-system structure​

website/i18n/[locale]/docusaurus-theme-classic
│
│ # translations for the theme
├── navbar.json
└── footer.json