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

Barra Lateral

Criar uma barra lateral é útil para:

  • Agrupar vários documentos relacionados
  • Exibe uma barra lateral em cada um desses documentos
  • Forneça uma navegação paginada, com o botão seguinte/anterior

Para usar as barras laterais no seu site do Docusaurus:

  1. Define um arquivo que exporta um objeto da barra lateral.
  2. Passe esse objeto no plugin @docusaurus/plugin-docs diretamente ou via @docusaurus/preset-classic.
docusaurus.config.js
module.exports = {
presets: [
[
'@docusaurus/preset-classic',
{
docs: {
sidebarPath: require.resolve('./sidebars.js'),
},
},
],
],
};

Barra lateral padrão

Por padrão, o Docusaurus gera automaticamente uma barra lateral para você, usando a estrutura do sistema de arquivos da pasta docs:

sidebars.js
module.exports = {
mySidebar: [
{
type: 'autogenerated',
dirName: '.', // generate sidebar slice from the docs folder (or versioned_docs/<version>)
},
],
};

Você também pode definir suas barras laterais explicitamente.

Uma barra lateral é uma árvore de itens na barra lateral.

type Sidebar =
// Normal syntax
| SidebarItem[]

// Shorthand syntax
| Record<
string, // category label
SidebarItem[] // category items
>;

Um arquivo de barras laterais pode conter múltiplos objetos da barra lateral.

type SidebarsFile = Record<
string, // sidebar id
Sidebar
>;

Exemplo:

sidebars.js
module.exports = {
mySidebar: [
{
type: 'category',
label: 'Getting Started',
items: ['doc1'],
},
{
type: 'category',
label: 'Docusaurus',
items: ['doc2', 'doc3'],
},
],
};

Observe o seguinte:

  • Há uma única barra lateral mySidebar, contendo 5 itens de barra lateral
  • Primeiros passos e o Docusaurus são categorias de barra lateral
  • doc1, doc2 e doc3 são documentos de barra lateral
tip

Use a sintaxe curta **** para expressar essa barra lateral de forma mais concisa:

sidebars.js
module.exports = {
mySidebar: {
'Getting started': ['doc1'],
Docusaurus: ['doc2', 'doc3'],
},
};

Usando múltiplas barras laterais

Você pode criar uma barra lateral para cada conjunto de arquivos Markdown que você deseja agrupar todos.

tip

O site Docusaurus é um bom exemplo de como usar várias barras laterais:

Exemplo:

sidebars.js
module.exports = {
tutorialSidebar: {
'Category A': ['doc1', 'doc2'],
},
apiSidebar: ['doc3', 'doc4'],
};
note

As chaves tutorialSidebar e apiSidebar são barras laterais Ids técnicas e não importam muito.

Ao navegar:

  • doc1 ou doc2: o tutorialSidebar será exibido
  • doc3 ou doc4: a apiSidebar será exibida

Um paginado de navegação link dentro da mesma barra lateral com botões seguinte e anterior.

Entendendo itens da barra lateral

SidebarItem é um item definido em uma árvore lateral.

Existem diferentes tipos de itens na barra lateral:

  • Doc: link para uma página de documento, atribuindo-o à barra lateral
  • Ref: link para uma página de um documento sem atribuí-lo à barra lateral
  • Link: link para qualquer página interna ou externa
  • Categoria: crie uma hierarquia de itens da barra lateral
  • Gerada automaticamente: gerar um recorte de barra lateral automaticamente

Use o tipo doc para criar um link para uma página de documento e atribuir esse documento a uma barra lateral:

type SidebarItemDoc =
// Normal syntax
| {
type: 'doc';
id: string;
label: string; // Sidebar label text
className?: string; // Class name for sidebar label
}

// Shorthand syntax
| string; // docId shortcut

Exemplo:

sidebars.js
module.exports = {
mySidebar: [
// Normal syntax:
{
type: 'doc',
id: 'doc1', // document id
label: 'Getting started', // sidebar label
},

// Shorthand syntax:
'doc2', // document id
],
};

O frontmatter de markdown sidebar_label tem uma precedência mais alta sobre a chave label em SidebarItemDoc.

note

Não atribua o mesmo documento a várias barras laterais: use um ref.

Use o tipo ref para vincular a uma página de documento sem atribuí-lo a uma barra lateral.

type SidebarItemRef = {
type: 'ref';
id: string;
};

Exemplo:

sidebars.js
module.exports = {
mySidebar: [
{
type: 'ref',
id: 'doc1', // Document id (string).
},
],
};

Ao navegar pela doc1, o Docusaurus não mostrará a barra lateral mySidebar.

Use o tipo link para vincular qualquer página (interna ou externa) que não seja um doc.

type SidebarItemLink = {
type: 'link';
label: string;
href: string;
className?: string;
};

Exemplo:

sidebars.js
module.exports = {
myLinksSidebar: [
// External link
{
type: 'link',
label: 'Facebook', // The link label
href: 'https://facebook.com', // The external URL
},

// Internal link
{
type: 'link',
label: 'Home', // The link label
href: '/', // The internal path
},
],
};

Use o tipo categoria para criar uma hierarquia de itens da barra lateral.

type SidebarItemCategory = {
type: 'category';
label: string; // Sidebar label text.
items: SidebarItem[]; // Array of sidebar items.
className?: string;

// Category options:
collapsible: boolean; // Set the category to be collapsible
collapsed: boolean; // Set the category to be initially collapsed or open by default
};

Exemplo:

sidebars.js
module.exports = {
docs: [
{
type: 'category',
label: 'Guides',
collapsible: true,
collapsed: false,
items: [
'creating-pages',
{
type: 'category',
label: 'Docs',
items: ['introduction', 'sidebar', 'markdown-features', 'versioning'],
},
],
},
],
};
tip

Use a sintaxe abreviada quando não precisar das opções de categoria:

sidebars.js
module.exports = {
docs: {
Guides: [
'creating-pages',
{
Docs: ['introduction', 'sidebar', 'markdown-features', 'versioning'],
},
],
},
};

Categorias recolhíveis

Apoiamos a opção de expandir/recolher categorias. As categorias são recolhidas por padrão, mas você pode desabilitar a colapsão com collapsible: false.

sidebars.js
module.exports = {
docs: [
{
type: 'category',
label: 'Guides',
items: [
'creating-pages',
{
type: 'category',
collapsible: false,
label: 'Docs',
items: ['introduction', 'sidebar', 'markdown-features', 'versioning'],
},
],
},
],
};

Para tornar todas as categorias não recolhíveis por padrão, defina a opção sidebarCollapsible em plugin-docs como false:

docusaurus.config.js
module.exports = {
presets: [
[
'@docusaurus/preset-classic',
{
docs: {
sidebarCollapsible: false,
},
},
],
],
};
note

A opção em sidebars.js tem precedência sobre a configuração do plugin, então é possível tornar certas categorias recolhíveis quando sidebarCollapsible é definido como false globalmente.

Categorias expandidas por padrão

As categorias recolhíveis são recolhidas por padrão. Se quiser que eles sejam expandidos na primeira renderização, você pode definir collapsed como false:

sidebars.js
module.exports = {
docs: {
Guides: [
'creating-pages',
{
type: 'category',
label: 'Docs',
collapsed: false,
items: ['markdown-features', 'sidebar', 'versioning'],
},
],
},
};

Semelhante a collapsible, você também pode definir a configuração global options.sidebarCollapsed como false. As opções individuais collapsed em sidebars.js ainda terão precedência sobre esta configuração.

docusaurus.config.js
module.exports = {
presets: [
[
'@docusaurus/preset-classic',
{
docs: {
sidebarCollapsed: false,
},
},
],
],
};
caution

Quando uma categoria tem collapsed: verdadeiro, mas collapsible: falso (seja por meio de sidebars.js ou por meio da configuração do plug-in), o último tem precedência e o a categoria ainda é processada como expandida.

Docusaurus pode criar uma barra lateral automaticamente a partir de sua estrutura do sistema de arquivos: cada pasta cria uma categoria da barra lateral.

Um item autogenerated é convertido pelo Docusaurus em uma fatia da barra lateral : uma lista de itens do tipo doc e categoria.

type SidebarItemAutogenerated = {
type: 'autogenerated';
dirName: string; // Source folder to generate the sidebar slice from (relative to docs)
};

O Docusaurus pode gerar uma barra lateral a partir da sua pasta de documentação:

sidebars.js
module.exports = {
myAutogeneratedSidebar: [
{
type: 'autogenerated',
dirName: '.', // '.' means the current docs folder
},
],
};

Você também pode usar vários itens gerados automaticamente em uma barra lateral, e entrelaçá-los com itens da barra lateral regular:

sidebars.js
module.exports = {
mySidebar: [
'intro',
{
type: 'category',
label: 'Tutorials',
items: [
'tutorial-intro',
{
type: 'autogenerated',
dirName: 'tutorials/easy', // Generate sidebar slice from docs/tutorials/easy
},
'tutorial-medium',
{
type: 'autogenerated',
dirName: 'tutorials/advanced', // Generate sidebar slice from docs/tutorials/hard
},
'tutorial-end',
],
},
{
type: 'autogenerated',
dirName: 'guides', // Generate sidebar slice from docs/guides
},
{
type: 'category',
label: 'Community',
items: ['team', 'chat'],
},
],
};

Metadados da barra lateral gerados automaticamente

Por padrão, a fatia da barra lateral será gerada em ordem alfabética (usando arquivos e nomes de pastas).

Se a barra lateral gerada não parecer boa, você pode atribuir metadados adicionais a documentos e categorias.

Para documentos: use outros frontmatter:

docs/tutorials/tutorial-easy.md
---
sidebar_label: Easy
sidebar_position: 2
---

# Easy Tutorial

This is the easy tutorial!

Para categorias: adicione um arquivo _category_.json ou _category_.yml na pasta apropriada:

docs/tutorials/_category_.json
{
"label": "Tutorial",
"position": 3,
"className": "red"
}
docs/tutorials/_category_.yml
label: 'Tutorial'
position: 2.5 # posição flutuante é suportada
collapsible: true # tornar a categoria recolhível
collapsed: false # mantenha a categoria aberta por padrão
info

Os metadados de posição são usados apenas dentro de uma fatia da barra lateral: o Docusaurus não reordena outros itens da sua barra lateral.

Usando prefixos numéricos

Uma maneira simples de ordenar uma barra lateral gerada automaticamente é prefixar arquivos e documentos por prefixos numéricos:

docs
├── 01-Intro.md
├── 02-Tutorial Easy
│   ├── 01-First Part.md
│   ├── 02-Second Part.md
│   └── 03-End.md
├── 03-Tutorial Hard
│   ├── 01-First Part.md
│   ├── 02-Second Part.md
│   ├── 03-Third Part.md
│   └── 04-End.md
└── 04-End.md

Para torná-lo mais fácil de adotar, o Docusaurus oferece suporte a vários padrões de prefixo de número.

Por padrão, o Docusaurus removerá o prefixo do id do documento, título, label e caminhos de URL.

caution

Prefira usar metadados adicionais.

Atualizar um prefixo de número pode ser irritante, pois pode exigir a atualização de vários links de marcação existentes:

docs/02-Tutorial Easy/01-First Part.md
- Verifique o [fim de tutorial](../04-End.md);
+ Verifique o [fim de tutorial](../05-End.md);

Personalizar o gerador de itens da barra lateral

Você pode fornecer uma função personalizada de sidebarItemsGenerator na configuração do plugin da documentação (ou predefinição):

docusaurus.config.js
module.exports = {
plugins: [
[
'@docusaurus/plugin-content-docs',
{
sidebarItemsGenerator: async function ({
defaultSidebarItemsGenerator,
numberPrefixParser,
item,
version,
docs,
}) {
// Example: return an hardcoded list of static sidebar items
return [
{type: 'doc', id: 'doc1'},
{type: 'doc', id: 'doc2'},
];
},
},
],
],
};
tip

Reutilizar e aprimorar o gerador padrão em vez de escrever um gerador do zero.

Adicione, atualize, filtre os itens da barra lateral de acordo com seu caso de uso:

docusaurus.config.js
// Reverse the sidebar items ordering (including nested category items)
function reverseSidebarItems(items) {
// Reverse items in categories
const result = items.map((item) => {
if (item.type === 'category') {
return {...item, items: reverseSidebarItems(item.items)};
}
return item;
});
// Reverse items at current level
result.reverse();
return result;
}

module.exports = {
plugins: [
[
'@docusaurus/plugin-content-docs',
{
sidebarItemsGenerator: async function ({
defaultSidebarItemsGenerator,
...args
}) {
const sidebarItems = await defaultSidebarItemsGenerator(args);
return reverseSidebarItems(sidebarItems);
},
},
],
],
};

Barra lateral ocultável

Usando a opção themeConfig.hideableSidebar habilitada, você pode ocultar toda a barra lateral, permitindo que você concentre melhor seus usuários no conteúdo. Isso é especialmente útil quando o consumo de conteúdo em telas médias (por exemplo, em tablets).

docusaurus.config.js
module.exports = {
themeConfig: {
hideableSidebar: true,
},
};

Passando propriedades personalizadas

Para passar props personalizados para um item da barra lateral alternada, adicione o objeto customProps opcional a qualquer um dos itens:

{
type: 'doc',
id: 'doc1',
customProps: {
/* props */
}
}

Exemplo de barras laterais complexas

Exemplo do mundo real no site Docusaurus:

sidebars.js
// @ts-check
const sidebars = {
docs: [
'introduction',
{
type: 'category',
label: 'Getting Started',
collapsed: false,
items: [
'installation',
'configuration',
'playground',
'typescript-support',
],
},
{
type: 'category',
label: 'Guides',
items: [
'guides/creating-pages',
{
Docs: [
'guides/docs/introduction',
'guides/docs/create-doc',
'guides/docs/sidebar',
'guides/docs/versioning',
'guides/docs/markdown-features',
'guides/docs/multi-instance',
],
},
'blog',
{
type: 'category',
label: 'Markdown Features',
items: [
'guides/markdown-features/introduction',
'guides/markdown-features/react',
'guides/markdown-features/tabs',
'guides/markdown-features/code-blocks',
'guides/markdown-features/admonitions',
'guides/markdown-features/headings',
'guides/markdown-features/inline-toc',
'guides/markdown-features/assets',
'guides/markdown-features/plugins',
'guides/markdown-features/math-equations',
'guides/markdown-features/head-metadata',
],
},
'styling-layout',
'static-assets',
'search',
'browser-support',
'seo',
'deployment',
{
type: 'category',
label: 'Internationalization',
items: [
{
type: 'doc',
id: 'i18n/introduction',
label: 'Introduction',
},
{
type: 'doc',
id: 'i18n/tutorial',
label: 'Tutorial',
},
{
type: 'doc',
id: 'i18n/git',
label: 'Using Git',
},
{
type: 'doc',
id: 'i18n/crowdin',
label: 'Using Crowdin',
},
],
},
],
},
{
type: 'category',
label: 'Advanced Guides',
items: ['using-plugins', 'using-themes', 'presets'],
},
{
type: 'category',
label: 'Migrating from v1 to v2',
items: [
'migration/migration-overview',
'migration/migration-automated',
'migration/migration-manual',
'migration/migration-versioned-sites',
'migration/migration-translated-sites',
],
},
],
api: [
'cli',
'docusaurus-core',
{
type: 'autogenerated',
dirName: 'api',
},
],
};
module.exports = sidebars;