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:

• guides

  • Componentes
  • Internacionalização (i18n)
• reference

  • Referência de Configuração

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

Adicione links e grupos de links

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.

Links

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:

• CSS e Estilização
• Astro

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:

• Guias

  • Componentes
  • Internacionalização (i18n)
  • Estilização

    • CSS
    • Tailwind
    • Shiki

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:

• Guias

  • Componentes
  • Internacionalização (i18n)
  • advanced

    • Estrutura de Projetos

Customizando links auto-gerados no frontmatter

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:

• Guias

  • Uma página
  • Rótulo customizado para a barra lateral Novo
  • Outra página

Nota

A configuração sidebar do frontmatter é utilizada apenas para links auto-gerados e será ignorada por qualquer link definido manualmente.

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:

• Guias

  • Componentes Novo
• Referência Descontinuado

  • Referência da Configuração
  • Referência do Frontmatter
  • Referência de Substituição

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:

• Guias

  • Componentes Experimental

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:

• Guias

  • Astro Docs

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:

• Guides

  • Components
  • Internationalization (i18n)

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:

• Guias

  • Componentes
  • Internacionalização (i18n)

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:

• Guias

  • Componentes
  • Internacionalização (i18n)
  • advanced

    • Estrutura de Projetos

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:

• Guias

  • Componentes
  • Internacionalização (i18n)
  • advanced

    • Estrutura de Projetos