Pular para o conteúdo

Navegação da barra lateral

Uma barra lateral bem organizada é essencial para uma boa documentação por ser uma das principais maneiras que usuários vão navegar pelo seu site. Starlight provê um conjunto completo de opções para customizar o layout e conteúdo de sua barra lateral.

Barra lateral padrão

Por padrão, Starlight vai gerar automaticamente uma barra lateral baseada na estrutura dos arquivos da sua documentação, utilizando a propriedade title de cada arquivos como entrada na barra lateral.

Por exemplo, dada a seguinte estrutura de arquivos:

  • Directorysrc/
    • Directorycontent/
      • Directorydocs/
        • Directoryguides/
          • components.md
          • i18n.md
        • Directoryreference/
          • configuration.md

Esta barra lateral será gerada automaticamente:

Aprenda mais sobre barras laterais auto-geradas na seção grupos auto-gerados.

Para configurar os links e grupos de links (dentro de um cabeçalho colapsável) de sua barra lateral, use a propriedade starlight.sidebar em astro.config.mjs.

Combinando os links e grupos você pode criar uma grande variedade de layouts de barrra lateral.

Adicione um link para uma página interna ou externa utilizando um objeto com as propriedades label e link.

starlight({
sidebar: [
// Um link para o guia de CSS e Estilização.
{ label: 'CSS e Estilização', link: '/pt-br/guides/css-and-tailwind/' },
// Um link externo para o website do Astro.
{ label: 'Astro', link: 'https://astro.build/' },
],
});

A configuração acima gera a seguinte barra lateral:

Grupos

Você pode adicionar estrutura para a sua barra lateral agrupando links relacionados dentro de um título colapsável. Grupos podem conter tanto links quanto outros sub-grupos.

Adicione um grupo utilizando um objeto com as propriedades label e items. A label será utilizada como o título do grupo. Adicione links e sub-grupos ao array items.

starlight({
sidebar: [
// Um grupo de links nomeado "Guias".
{
label: 'Guias',
items: [
{ label: 'Componentes', link: '/guides/components/' },
{ label: 'Internacionalização (i18n)', link: '/guides/i18n/' },
// Um grupo aninhado de links.
{
label: 'Estilização',
items: [
{ label: 'CSS', link: '/guides/css-and-tailwind/' },
{ label: 'Tailwind', link: '/guides/css-and-tailwind/' },
{ label: 'Shiki', link: '/guides/css-and-tailwind/' },
],
},
],
},
],
});

A configuração acima gera a seguinte barra lateral:

Grupos auto-gerados

Starlight pode gerar automaticamente um grupo em sua barra lateral baseado em um diretório de sua docs. Isso é útil quando você não quer especificar manualmente cada item em um grupo da barra lateral. Por padrão, páginas são ordenadas alfabeticamente por nome do arquivo.

Adicione um grupo auto-gerado utilizando um objeto com as propriedades label e autogenerate. Sua configuração em autogenerate deve especificar o diretório (directory) a ser usado para as entradas da barra lateral. Por exemplo, com a seguinte configuração:

starlight({
sidebar: [
{
label: 'Guias',
// Gera automaticamente um grupo com os links para o diretório 'guias'.
autogenerate: { directory: 'guias' },
},
],
});

E esta estrutura de arquivos:

  • Directorysrc/
    • Directorycontent/
      • Directorydocs/
        • Directoryguides/
          • components.md
          • i18n.md
          • Directoryadvanced/
            • project-structure.md

A barra lateral gerada seria esta:

Use o campo sidebar do frontmatter em páginas individuais para customizar os links auto-gerados.

As opções de barra lateral do frontmatter lhe permitem configurar um rótulo customizado ou adicionar um emblema a um link, ocultar um link da barra lateral, ou definir um peso de ordenação customizado.

src/content/docs/exemplo.md
---
title: Minha página
sidebar:
# Define um rótulo customizado para o link
label: Rótulo customizado para a barra lateral
# Define uma ordem customizada para o link (números menores são exibidos acima)
order: 2
# Adiciona um emblema ao link
badge:
text: Novo
variant: tip
---

Um grupo auto-gerado incluindo uma página com o frontmatter acima resultará nesta barra lateral:

Emblemas

Links, grupos, e grupos auto-gerados podem incluir uma propriedade badge para exibir um emblema ao lado de seu rótulo.

starlight({
sidebar: [
{
label: 'Guias',
items: [
// Um link com um emblema "Novo".
{
label: 'Componentes',
link: '/guides/components/',
badge: 'Novo',
},
],
},
// Um grupo auto-gerado com um emblema "Descontinuado".
{
label: 'Referência',
badge: 'Descontinuado',
autogenerate: { directory: 'reference' },
},
],
});

A configuração acima gera a seguinte barra lateral:

Variações de emblemas

Customize o estilo do emblema utilizando um objeto com as propriedades text e variant.

O texto (text) representa o conteúdo a ser exibido (e.g. “Novo”). Sobrescreva o estilo padrão (default), que usa a cor de destaque do seu site, definindo a propriedade variant para um dos seguintes valores: note, tip, danger, caution ou success.

starlight({
sidebar: [
{
label: 'Guias',
items: [
// Um link com um emblema amarelo "Experimental".
{
label: 'Componentes',
link: '/guides/components/',
badge: { text: 'Experimental', variant: 'caution' },
},
],
},
],
});

A configuração acima gera a seguinte barra lateral:

Atributos HTML customizados

Links também podem incluir uma propriedade attrs para adicionar atributos HTML customizados ao elemento do link.

No exemplo abaixo, attrs é utilizado para adicionar um atributo target="_blank", de forma que o link abra em uma nova aba, e para aplicar um atributo style para exibir o rótulo do link em itálico.

starlight({
sidebar: [
{
label: 'Guias',
items: [
// Um link externo para a documentação do Astro que abre em uma nova aba.
{
label: 'Astro Docs',
link: 'https://docs.astro.build/',
attrs: { target: '_blank', style: 'font-style: italic' },
},
],
},
],
});

A configuração acima gera esta barra lateral:

Internacionalização

Use a propriedade translations em entradas de link e grupo para traduzir o rótulo do link ou grupo para cada linguagem suportada especificando uma tag de língua BCP-47, e.g. "en", "ar", ou "zh-CN", como a chave e o rótulo traduzido como o valor. A propriedade label será usada para a língua padrão e para línguas sem uma tradução.

starlight({
sidebar: [
{
label: 'Guias',
translations: {
'en-US': 'Guides',
},
items: [
{
label: 'Componentes',
translations: {
'en-US': 'Components',
},
link: '/guides/components/',
},
{
label: 'Internacionalização (i18n)',
translations: {
'en-US': 'Internationalization (i18n)',
},
link: '/guides/i18n/',
},
],
},
],
});

Navegar pela documentação em inglês americano gerará esta barra lateral:

Grupos colapsáveis

Grupos de links podem ser colapsados por padrão definindo a propriedade collapsed como true.

starlight({
sidebar: [
{
label: 'Guias',
// Colapse o grupo por padrão.
collapsed: true,
items: [
{ label: 'Componentes', link: '/guides/components/' },
{ label: 'Internacionalização (i18n)', link: '/guides/i18n/' },
],
},
],
});

The configuration above generates the following sidebar:

Grupos auto-gerados respeitam o valor collapsed do grupo pai:

starlight({
sidebar: [
{
label: 'Guias',
// Colapse o grupo e seus sub-grupos auto-gerados por padrão.
collapsed: true,
autogenerate: { directory: 'guides' },
},
],
});

A configração acima gera esta barra lateral:

Esse comportamento pode ser sobrescrito definindo a propriedade autogenerate.collapsed.

starlight({
sidebar: [
{
label: 'Guias',
// Não colapse o grupo "Guias", mas colapse seus
// sub-grupos auto-gerados.
collapsed: false,
autogenerate: { directory: 'guides', collapsed: true },
},
],
});

The configuration above generates the following sidebar: