Configuração do tema
This configuration applies to all main themes.
Comum
Modo de cor
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 modo de cor no objeto colorMode
.
Campos aceitos:
Nome | Type | Padrão | Descrição |
---|---|---|---|
defaultMode | 'light' | 'dark' | 'light' | The color mode when user first visits the site. |
disableSwitch | boolean | false | Hides the switch in the navbar. Useful if you want to support a single color mode. |
respectPrefersColorScheme | boolean | false | Whether to use the prefers-color-scheme media-query, using user system preferences, instead of the hardcoded defaultMode . |
Configuração de exemplo:
export default {
themeConfig: {
colorMode: {
defaultMode: 'light',
disableSwitch: false,
respectPrefersColorScheme: false,
},
},
};
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
.
Campos aceitos:
Nome | Type | Padrão | Descrição |
---|---|---|---|
image | string | undefined | The 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:
export default {
themeConfig: {
image: 'img/docusaurus.png',
},
};
Metadata
You can configure additional HTML metadata (and override existing ones).
Campos aceitos:
Nome | Type | Padrão | Descrição |
---|---|---|---|
metadata | Metadata[] | [] | Any field will be directly passed to the <meta /> tag. Possible fields include id , name , property , content , itemprop , etc. |
Configuração de exemplo:
export default {
themeConfig: {
metadata: [{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. This is a non-fixed and optionally dismissible panel above the navbar. Todas as configurações estão no objeto announcementBar
.
Campos aceitos:
Nome | Type | Padrão | Descrição |
---|---|---|---|
id | string | 'announcement-bar' | Any value that will identify this message. |
content | string | '' | The text content of the announcement. HTML will be interpolated. |
backgroundColor | string | '#fff' | Background color of the entire bar. |
textColor | string | '#000' | Announcement text color. |
isCloseable | boolean | true | Whether this announcement can be dismissed with a '×' button. |
Configuração de exemplo:
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,
},
},
};
Plugins
Our main themes offer additional theme configuration options for Docusaurus core content plugins.
Documentação
Nome | Type | Padrão | Descrição |
---|---|---|---|
versionPersistence | 'localStorage' | 'none' | undefined | Defines the browser persistence of the preferred docs version. |
sidebar.hideable | boolean | false | Show a hide button at the bottom of the sidebar. |
sidebar.autoCollapseCategories | boolean | false | Automatically collapse all sibling categories of the one you navigate to. |
Configuração de exemplo:
export default {
themeConfig: {
docs: {
versionPersistence: 'localStorage',
sidebar: {
hideable: false,
autoCollapseCategories: false,
},
},
},
};
Blog
Nome | Type | Padrão | Descrição |
---|---|---|---|
sidebar.groupByYear | boolean | true | Group sidebar blog posts by years. |
Configuração de exemplo:
export default {
themeConfig: {
blog: {
sidebar: {
groupByYear: true,
},
},
},
};
Barra de navegação
Campos aceitos:
Nome | Type | Padrão | Descrição |
---|---|---|---|
título | string | undefined | Title for the navbar. |
logo | See below | undefined | Customization of the logo object. |
items | NavbarItem[] | [] | A list of navbar items. See specification below. |
hideOnScroll | boolean | false | Whether the navbar is hidden when the user scrolls down. |
style | 'primary' | 'dark' | Same as theme | Sets the navbar style, ignoring the dark/light theme. |
Logotipo Navbar
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:
Nome | Type | Padrão | Descrição |
---|---|---|---|
alt | string | undefined | Alt tag for the logo image. |
src | string | Required | URL to the logo image. Base URL is appended by default. |
srcDark | string | logo.src | An alternative image URL to use in dark mode. |
href | string | siteConfig.baseUrl | Link to navigate to when the logo is clicked. |
width | string | number | undefined | Specifies the width attribute. |
height | string | number | undefined | Specifies the height attribute. |
target | string | Calculated based on href (external links will open in a new tab, all others in the current one). | The target attribute of the link; controls whether the link is opened in a new tab, the current one, or otherwise. |
className | string | undefined | CSS class applied to the image. |
style | object | undefined | CSS inline style object. React/JSX flavor, using camelCase properties. |
Configuração de exemplo:
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'},
},
},
},
};
Itens da barra de navegação
Você pode adicionar itens à barra de navegação por meio de themeConfig.navbar.items
.
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',
},
],
},
},
};
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:
Nome | Type | Padrão | Descrição |
---|---|---|---|
type | 'default' | Optional | Sets the type of this item to a link. |
label | string | Required | The name to be shown for this item. |
html | string | Optional | Same as label , but renders pure HTML instead of text content. |
to | string | Required | Client-side routing, used for navigating within the website. O baseUrl será adicionado automaticamente a este valor. |
href | string | Required | A full-page navigation, used for navigating outside of the website. Only one of to or href should be used. |
prependBaseUrlToHref | boolean | false | Prepends the baseUrl to href values. |
position | 'left' | 'right' | 'left' | The side of the navbar this item should appear on. |
activeBasePath | string | to / href | To apply the active class styling on all routes starting with this path. Isto geralmente não é necessário. |
activeBaseRegex | string | undefined | Alternative to activeBasePath if required. |
className | string | '' | Custom CSS class (for styling any item). |
In addition to the fields above, you can specify other arbitrary attributes that can be applied to a HTML link.
Configuração de exemplo:
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',
},
],
},
},
};
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 dos docs da Navbar
- Navbar doc sidebar
- Navbar with custom HTML
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:
Nome | Type | Padrão | Descrição |
---|---|---|---|
type | 'dropdown' | Optional | Sets the type of this item to a dropdown. |
label | string | Required | The name to be shown for this item. |
items | LinkLikeItem[] | Required | The items to be contained in the dropdown. |
position | 'left' | 'right' | 'left' | The side of the navbar this item should appear on. |
Configuração de exemplo:
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
],
},
],
},
},
};
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:
Nome | Type | Padrão | Descrição |
---|---|---|---|
type | 'doc' | Required | Sets the type of this item to a doc link. |
docId | string | Required | The ID of the doc that this item links to. |
label | string | docId | The name to be shown for this item. |
position | 'left' | 'right' | 'left' | The side of the navbar this item should appear on. |
docsPluginId | string | 'default' | The ID of the docs plugin that the doc belongs to. |
Configuração de exemplo:
export default {
themeConfig: {
navbar: {
items: [
{
type: 'doc',
position: 'left',
docId: 'introduction',
label: 'Docs',
},
],
},
},
};
Navbar linked to a sidebar
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:
Nome | Type | Padrão | Descrição |
---|---|---|---|
type | 'docSidebar' | Required | Sets the type of this navbar item to a sidebar's first document. |
sidebarId | string | Required | The ID of the sidebar that this item is linked to. |
label | string | First document link's sidebar label | The name to be shown for this item. |
position | 'left' | 'right' | 'left' | The side of the navbar this item should appear on. |
docsPluginId | string | 'default' | The ID of the docs plugin that the sidebar belongs to. |
Use this navbar item type if your sidebar is updated often and the order is not stable.
Configuração de exemplo:
export default {
themeConfig: {
navbar: {
items: [
{
type: 'docSidebar',
position: 'left',
sidebarId: 'api',
label: 'API',
},
],
},
},
};
export default {
tutorial: [
{
type: 'autogenerated',
dirName: 'guides',
},
],
api: [
'cli', // The navbar item will be linking to this doc
'docusaurus-core',
{
type: 'autogenerated',
dirName: 'api',
},
],
};
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.
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:
Nome | Type | Padrão | Descrição |
---|---|---|---|
type | 'docsVersionDropdown' | Required | Sets the type of this item to a docs version dropdown. |
position | 'left' | 'right' | 'left' | The side of the navbar this item should appear on. |
dropdownItemsBefore | LinkLikeItem[] | [] | Add additional dropdown items at the beginning of the dropdown. |
dropdownItemsAfter | LinkLikeItem[] | [] | Add additional dropdown items at the end of the dropdown. |
docsPluginId | string | 'default' | The ID of the docs plugin that the doc versioning belongs to. |
dropdownActiveClassDisabled | boolean | false | Do not add the link active class when browsing docs. |
Configuração de exemplo:
export default {
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:
Nome | Type | Padrão | Descrição |
---|---|---|---|
type | 'docsVersion' | Required | Sets the type of this item to a doc version link. |
label | string | The active/latest version label. | The name to be shown for this item. |
to | string | The active/latest version. | The internal link that this item points to. |
position | 'left' | 'right' | 'left' | The side of the navbar this item should appear on. |
docsPluginId | string | 'default' | The ID of the docs plugin that the doc versioning belongs to. |
Configuração de exemplo:
export default {
themeConfig: {
navbar: {
items: [
{
type: 'docsVersion',
position: 'left',
to: '/path',
label: 'label',
},
],
},
},
};
Menu suspenso de localidade da Navbar
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:
Nome | Type | Padrão | Descrição |
---|---|---|---|
type | 'localeDropdown' | Required | Sets the type of this item to a locale dropdown. |
position | 'left' | 'right' | 'left' | The side of the navbar this item should appear on. |
dropdownItemsBefore | LinkLikeItem[] | [] | Add additional dropdown items at the beginning of the dropdown. |
dropdownItemsAfter | LinkLikeItem[] | [] | Add additional dropdown items at the end of the dropdown. |
queryString | string | undefined | The query string to be appended to the URL. |
Configuração de exemplo:
export default {
themeConfig: {
navbar: {
items: [
{
type: 'localeDropdown',
position: 'left',
dropdownItemsAfter: [
{
to: 'https://my-site.com/help-us-translate',
label: 'Help us translate',
},
],
},
],
},
},
};
Pesquisa na Navbar
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.
Nome | Type | Padrão | Descrição |
---|---|---|---|
type | 'search' | Required | Sets the type of this item to a search bar. |
position | 'left' | 'right' | 'left' | The side of the navbar this item should appear on. |
className | string | / | Custom CSS class for this navbar item. |
export default {
themeConfig: {
navbar: {
items: [
{
type: 'search',
position: 'right',
},
],
},
},
};
Navbar with custom HTML
You can also render your own HTML markup inside a navbar item using this navbar item type.
Nome | Type | Padrão | Descrição |
---|---|---|---|
type | 'html' | Required | Sets the type of this item to a HTML element. |
position | 'left' | 'right' | 'left' | The side of the navbar this item should appear on. |
className | string | '' | Custom CSS class for this navbar item. |
value | string | '' | Custom HTML to be rendered inside this navbar item. |
export default {
themeConfig: {
navbar: {
items: [
{
type: 'html',
position: 'right',
value: '<button>Give feedback</button>',
},
],
},
},
};
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.
export default {
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.
export default {
themeConfig: {
navbar: {
style: 'primary',
},
},
};
CodeBlock
O Docusaurus usa Prism React Renderer para destacar blocos de código. All configuration are in the prism
object.
Campos aceitos:
Nome | Type | Padrão | Descrição |
---|---|---|---|
theme | PrismTheme | palenight | The Prism theme to use for light-theme code blocks. |
darkTheme | PrismTheme | palenight | The Prism theme to use for dark-theme code blocks. |
defaultLanguage | string | undefined | The default language to use for code blocks not declaring any explicit language. |
magicComments | MagicCommentConfig[] | see below | The 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'},
},
];
Tema
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:
import {themes as prismThemes} from 'prism-react-renderer';
export default {
themeConfig: {
prism: {
theme: prismThemes.github,
darkTheme: prismThemes.dracula,
},
},
};
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, ```). Note that a valid language name must be passed.
Configuração de exemplo:
export default {
themeConfig: {
prism: {
defaultLanguage: 'javascript',
},
},
};
Rodapé
Pode adicionar o logotipo e um direito autoral ao rodapé através do 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:
Nome | Type | Padrão | Descrição |
---|---|---|---|
logo | Logo | undefined | Customization of the logo object. See Navbar logo for details. |
copyright | string | undefined | The copyright message to be displayed at the bottom, also supports custom HTML. |
style | 'dark' | 'light' | 'light' | The color theme of the footer component. |
links | (Column | FooterLink)[] | [] | The link groups to be present. |
Configuração de exemplo:
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.`,
},
},
};
Links do rodapé
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 FooterItem
s for each column.
Nome | Type | Padrão | Descrição |
---|---|---|---|
título | string | undefined | Label of the section of these links. |
items | FooterItem[] | [] | Links in this section. |
Accepted fields of each FooterItem
:
Nome | Type | Padrão | Descrição |
---|---|---|---|
label | string | Required | Text to be displayed for this link. |
to | string | Required | Client-side routing, used for navigating within the website. O baseUrl será adicionado automaticamente a este valor. |
href | string | Required | A full-page navigation, used for navigating outside of the website. Only one of to or href should be used. |
html | string | undefined | Renders the HTML pass-through instead of a simple link. In case html is used, no other options should be provided. |
Example multi-column configuration:
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: 'X',
href: 'https://x.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 FooterItem
s displayed in a row.
Example simple configuration:
export default {
footer: {
links: [
{
label: 'Stack Overflow',
href: 'https://stackoverflow.com/questions/tagged/docusaurus',
},
{
label: 'Discord',
href: 'https://discordapp.com/invite/docusaurus',
},
{
label: 'X',
href: 'https://x.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
.
Nome | Type | Padrão | Descrição |
---|---|---|---|
minHeadingLevel | number | 2 | The minimum heading level shown in the table of contents. Must be between 2 and 6 and lower or equal to the max value. |
maxHeadingLevel | number | 3 | Max heading level displayed in the TOC. Should be an integer between 2 and 6. |
Configuração de exemplo:
export default {
themeConfig: {
tableOfContents: {
minHeadingLevel: 2,
maxHeadingLevel: 5,
},
},
};
Ganchos
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>;
};
The component calling useColorMode
must be a child of the Layout
component.
function ExamplePage() {
return (
<Layout>
<Example />
</Layout>
);
}
i18n
Read the i18n introduction first.
Localização dos arquivos de tradução
- Base path:
website/i18n/[locale]/docusaurus-theme-[themeName]
- Caminho de multi-instância: N/A
- JSON files: extracted with
docusaurus write-translations
- Arquivos Markdown: N/A
Exemplo de estrutura de sistema de arquivos
website/i18n/[locale]/docusaurus-theme-classic
│
│ # translations for the theme
├── navbar.json
└── footer.json