---
title: Navegação
description: >-
  O Blume monta a barra lateral a partir dos seus arquivos e depois permite refiná-la com frontmatter, meta de pasta ou configuração — trilhas de navegação e sumários acompanham automaticamente.
---

O Blume monta sua barra lateral a partir do sistema de arquivos e depois permite refiná-la tanto — ou tão pouco — quanto você quiser: página por página, pasta por pasta ou com uma configuração explícita. Trilhas de navegação, links de anterior/próximo e o sumário da página derivam todos do mesmo modelo, sem nada para conectar manualmente.

## A barra lateral gerada [#the-generated-sidebar]

Por padrão, a barra lateral espelha a sua árvore de conteúdo:

- pastas viram **grupos**, arquivos viram **páginas**
- o rótulo de uma página é o `title` do seu frontmatter; o rótulo de um grupo é o nome humanizado da pasta
- os itens são ordenados por [prefixo numérico](/docs/content) e depois alfabeticamente, e a página `index` de uma pasta vem primeiro
- uma pasta com uma página `index` liga a linha do seu grupo a essa página, então clicar no nome da seção abre a página de destino da seção

Isso já basta para muitos sites — tudo abaixo é opcional.

## Rótulo, ícone e selo da página [#page-label-icon-and-badge]

Ajuste como uma única página aparece na barra lateral a partir do seu frontmatter, sob `sidebar`:

```yaml lineNumbers
sidebar:
  label: Quickstart # override the title in the sidebar
  icon: rocket # an icon from Blume's built-in set
  badge: New # a small label beside the entry
  order: 1 # sort position within its group
```

Veja [Frontmatter](/docs/reference/frontmatter) para o esquema completo da página.

## Grupos de pastas [#folder-groups]

Cada pasta vira um grupo na barra lateral. Coloque um [`meta.ts`](/docs/content/meta) junto às suas páginas para definir o título, o ícone, a ordem do grupo e a ordem dos seus filhos:

```ts meta.ts
import { defineMeta } from "blume";

export default defineMeta({
  title: "Guides",
  icon: "book-open",
  pages: ["configuration", "theming", "deployment"],
});
```

Veja [Meta de pasta](/docs/content/meta) para todos os campos e para computar meta no momento da varredura.

O `meta.title` de uma pasta e o `title` do frontmatter da sua própria página `index` são resolvidos de forma independente — traduzir um sob i18n e esquecer o outro renderiza uma barra lateral correta, mas com um `<title>`/título desatualizado na própria página de destino. O Blume emite um aviso `BLUME_NAV_INDEX_TITLE_MISMATCH` quando eles divergem. Páginas não traduzidas preenchidas a partir do idioma de fallback são isentas — o título delas pertence ao idioma de fallback, e a correção é traduzir a página, não editar o frontmatter dela.

Para agrupar páginas _sem_ adicionar um segmento de URL, use um nome de pasta entre parênteses — veja [Páginas](/docs/content#group-folders).

## Modos de exibição [#display-modes]

`navigation.sidebar.display` define como cada grupo da barra lateral é renderizado:

```ts blume.config.ts lineNumbers
navigation: {
  sidebar: {
    display: "flat", // "flat" | "group" | "page"
  },
}
```

- **`flat`** (padrão) — um cabeçalho não recolhível com suas páginas listadas abaixo. Páginas que não pertencem a nenhum grupo sempre aparecem primeiro, acima das seções de grupo, para que não sejam confundidas com filhos de um grupo.
- **`group`** — um bloco recolhível `<details>` por grupo. Os grupos começam recolhidos por padrão; um grupo que contém a página atual sempre começa aberto, de modo que apenas a seção em que você está fica expandida. Defina `collapsed: false` no [meta de pasta](/docs/content/meta) para forçar um grupo a ficar aberto independentemente disso.
- **`page`** — cada grupo é uma única linha que, ao ser clicada, desliza a barra lateral para um subpainel mostrando apenas os itens daquele grupo, com uma seta de voltar no topo. O painel reconhece a rota, então cair diretamente em uma página dentro do grupo abre direto nela.

:::tip
O modo `page` mantém seções profundas organizadas — use-o quando os grupos tiverem muitos filhos e você preferir navegar dentro deles a rolar por eles.
:::

Nos modos `group` e `page`, uma seção que não está aberta na página atual fica de fora do HTML dessa página e é buscada na primeira vez que é aberta (ela é pré-carregada assim que o ponteiro ou o foco chega à sua linha, então a abertura costuma ser instantânea, e uma seção buscada uma vez é mantida pelo resto da visita). Em um site grande, isso representa a maior parte do peso de uma página: apenas as linhas da seção aberta são enviadas com a página. As linhas são fragmentos pré-renderizados sob `/blume-nav/`, então não precisam de servidor. Leitores sem JavaScript veem a seção aberta e as linhas dos grupos; o sitemap, os links de anterior/próximo e a seção aberta mantêm todas as páginas acessíveis para os crawlers.

### Substituições por grupo [#per-group-overrides]

Qualquer grupo gerado pode abrir mão do modo global — sem precisar de uma barra lateral explícita. Defina `display` no [`meta.ts`](/docs/content/meta) da pasta ou — quando a pasta tem uma página `index` — sob `sidebar` no frontmatter dessa página, e apenas aquele grupo muda:

```ts meta.ts
import { defineMeta } from "blume";

export default defineMeta({
  title: "Client SDKs",
  display: "page",
});
```

```yaml index.mdx
---
title: Client SDKs
sidebar:
  display: page
---
```

O modo efetivo de um grupo gerado é resolvido da maior prioridade para a menor:

1. `sidebar.display` no frontmatter da própria página `index` do grupo
2. `display` no `meta.ts` da pasta
3. O `navigation.sidebar.display` global
4. O padrão do Blume (`flat`)

O `display` de um grupo se aplica somente àquele grupo — subgrupos aninhados resolvem seu próprio valor pela mesma cadeia. Um grupo em modo `page` com uma página de índice ainda navega para o seu subpainel: a página de índice aparece como o primeiro item do painel, e cair na URL dela abre o painel diretamente.

`sidebar.display` não significa nada em nenhum outro lugar — em uma página que não seja de índice, na própria página `index` da raiz do conteúdo (a raiz não é um grupo; use `navigation.sidebar.display`) ou em qualquer página quando uma [barra lateral explícita](#explicit-sidebar) estiver configurada (seus itens são donos do modo de cada grupo) — então o Blume emite um aviso `BLUME_SIDEBAR_DISPLAY_IGNORED` em vez de descartá-lo silenciosamente. `collapsed` continua específico do modo `group`; ele fica inerte quando um grupo resolve para `flat` ou `page`.

Um grupo em uma [barra lateral explícita](#explicit-sidebar) substitui o modo global com seu próprio `display`, exatamente como antes.

## Ordenação [#ordering]

Quando a barra lateral é gerada, a ordem é resolvida da maior prioridade para a menor:

1. **Barra lateral da configuração**

    Um `navigation.sidebar` explícito substitui inteiramente a árvore gerada.

2. **Meta de pasta**

    O array `pages` em `meta.ts` ordena um grupo.

3. **Frontmatter**

    `sidebar.order` em uma página.

4. **Sistema de arquivos**

    Uma página `index` primeiro, depois prefixos numéricos, depois em ordem
    alfabética por rótulo.

Dois irmãos que acabam com a mesma ordem explícita ou numérica recorrem à ordem alfabética entre si — o Blume emite um aviso `BLUME_DUPLICATE_SIDEBAR_ORDER` para que o empate não passe despercebido.

## Páginas ocultas [#hidden-pages]

Oculte uma página da barra lateral — e da paginação de anterior/próximo — mantendo-a construída e acessível pela sua URL:

```yaml
sidebar:
  hidden: true
```

A página `index` de uma pasta aparece tanto como o link da linha do grupo quanto como a primeira linha dentro do grupo. Oculte a página de índice para manter apenas o cabeçalho com link: a linha do grupo continua abrindo a página de destino, e os links de anterior/próximo continuam passando por ela.

## Abas [#tabs]

Renderize seções de nível superior como abas no cabeçalho, útil para dividir um site grande em áreas distintas — digamos, adaptadores, uma API e guias de IA. Uma aba fica destacada quando a rota atual está sob o seu `path`:

```ts blume.config.ts lineNumbers
navigation: {
  tabs: [
    { label: "Adapters", path: "/adapters", icon: "plug" },
    { label: "API", path: "/api", icon: "rocket" },
    { label: "AI", path: "/ai", icon: "sparkles" },
  ],
}
```

Uma [referência OpenAPI ou AsyncAPI](/docs/advanced/api-reference) habilitada é montada na sua rota, mas não adiciona uma aba por conta própria — aponte uma aba para essa rota para exibi-la no cabeçalho (e, para o renderizador nativo, para delimitar a barra lateral de operações), com o rótulo que você quiser:

```ts blume.config.ts
navigation: {
  tabs: [
    { label: "API", path: "/reference" },
  ],
}
```

O `path` de uma aba é o prefixo da sua seção, e ele também serve como destino do link. Uma seção cujo `path` não é uma página própria — uma pasta sem `index.mdx` — apontaria para um 404, então a aba recorre à primeira página da seção. Defina `href` quando quiser que ela leve a outro lugar:

```ts blume.config.ts
navigation: {
  tabs: [
    { label: "Changelog", path: "/changelog", href: "/changelog" },
  ],
}
```

Isso importa para rotas que não fazem parte da árvore de conteúdo, já que o fallback não as enxerga: o índice de [changelog](/docs/advanced/changelog) gerado, ou uma [página personalizada](/docs/advanced/custom-pages) que você adicionou sob `pages/`. Sem `href`, uma aba `/changelog` cai na entrada mais recente em vez do índice. Abas que não definem `href` não são afetadas.

Em um site com [i18n](/docs/content/i18n), o `label` de uma aba (e o de um item de dropdown) pode ser um mapa por idioma em vez de uma string — a entrada do idioma ativo prevalece, depois a do idioma padrão:

```ts blume.config.ts
navigation: {
  tabs: [
    { label: { en: "Docs", fr: "Documentation" }, path: "/docs" },
    { label: "CLI", path: "/cli" }, // a plain string renders as-is everywhere
  ],
}
```

As abas também **delimitam a barra lateral**: quando a rota atual está sob o `path` de uma aba, a barra lateral mostra apenas as páginas daquela seção — então `/adapters/*` lista os adaptadores e nada mais. A pasta no `path` de uma aba se torna a seção, então isso não requer nenhuma configuração além das próprias abas; estruture seu conteúdo em uma pasta por aba e aponte cada aba para ela.

Em uma rota que não está sob nenhuma aba (ou sob uma aba cujo `path` é `/`), a barra lateral mostra as páginas que _não_ pertencem a uma aba — a pasta de cada aba fica oculta dela, já que aquela seção já tem sua própria aba no cabeçalho. Assim, uma página inicial na raiz lista suas páginas soltas de nível superior enquanto o conteúdo seccionado permanece atrás da sua aba, espelhando as pastas raiz do Fumadocs. Se uma rota não tiver páginas próprias para mostrar dessa forma, a árvore completa é exibida em vez disso, de modo que a barra lateral nunca fica em branco.

## Seletores [#selectors]

Para alternar entre partições inteiras de um site — um produto, uma versão ou qualquer conjunto agrupado de destinos — adicione um `selector`. Cada um é renderizado como um dropdown no cabeçalho, mostrando a opção cujo `path` corresponde à rota atual:

```ts blume.config.ts lineNumbers
navigation: {
  selectors: [
    {
      kind: "version",
      label: "Version",
      items: [
        { label: "v2 (latest)", path: "/v2", icon: "rocket" },
        { label: "v1", path: "/v1" },
      ],
    },
  ],
}
```

Cada item recebe um `label`, um `path` e, opcionalmente, `icon`, `description` e `tag`. `kind` (`dropdown`, `product`, `version` ou `language`) é uma indicação de como o seletor é usado; todos renderizam o mesmo dropdown.

Com [versionamento](/docs/content/versioning) configurado, o Blume renderiza um seletor de versão automaticamente — declarar aqui o seu próprio seletor `kind: "version"` substitui o automático, então configurações feitas à mão continuam funcionando.

## Links em destaque [#featured-links]

Fixe links no topo da barra lateral, acima de todas as seções — um blog, um changelog, uma página de contato ou suporte que deva estar sempre a um clique de distância. Diferentemente da árvore gerada, os links em destaque **não são delimitados por aba**: eles aparecem em todas as rotas, em todos os breakpoints.

```ts blume.config.ts lineNumbers
navigation: {
  featured: [
    { label: "Blog", href: "https://example.com/blog", icon: "newspaper" },
    { label: "Contact", href: "/contact", icon: "headphones" },
  ],
}
```

Cada link recebe um `label`, um `href` e um `icon` opcional (um nome de [ícone integrado](/docs/content/components#icon), caminho/URL de imagem ou SVG inline — o mesmo que em qualquer outro lugar). Um `href` pode apontar para qualquer lugar: uma URL externa abre em uma nova aba, enquanto uma rota interna (`/contact`) é validada contra as suas páginas no momento da build, avisando você se nada corresponder.

## Barra lateral explícita [#explicit-sidebar]

Para controle total, liste itens explícitos em `navigation.sidebar` — um array simples é um atalho para `sidebar.items`, e a forma de objeto os combina com um [`display`](#display-modes) global. Quando os itens são definidos, o Blume os usa literalmente e pula a geração pelo sistema de arquivos:

```ts blume.config.ts lineNumbers
navigation: {
  sidebar: [
    "/", // a page, referenced by route
    {
      label: "Guides", // a group
      collapsed: false,
      items: ["/configuration", "/configuration/theming"],
    },
    { label: "GitHub", href: "https://github.com/owner/repo" }, // an external link
  ],
}
```

Cada item é uma rota de página (uma string), um grupo (`label` + `items`) ou um link (`label` + `href`). Grupos podem ser aninhados, substituir o [modo `display`](#display-modes) global e começar `collapsed`.

## Ações do cabeçalho [#header-actions]

`navigation.actions` coloca links simples no cabeçalho, à esquerda dos botões de ícone, e `navigation.cta` é o único botão preenchido:

```ts blume.config.ts lineNumbers
navigation: {
  actions: [{ href: "/changelog", label: "Changelog" }],
  cta: { href: "https://example.com/signup", label: "Start free" },
}
```

`cta` é singular de propósito — um cabeçalho de documentação tem espaço para exatamente uma coisa que se pede ao leitor que faça, e uma fileira de botões não pede nada. Links secundários pertencem a `actions`, ou a [`featured`](#featured-links) se devem ficar junto à barra lateral.

Um href `http(s)` ou relativo ao protocolo abre em uma nova aba; uma rota permanece na aba e é validada contra as suas páginas no momento da build, como um link `featured` — então uma página servida por outro app no mesmo host (`/signup` no produto, digamos) deve ser escrita como uma URL absoluta. As `actions` ficam ocultas abaixo do breakpoint `sm`, onde o cabeçalho tem espaço para o logo e o alternador de navegação e nada mais. O `cta` também se oculta ali, exceto em uma página sem alternador de navegação — uma landing page em `PageLayout` sem abas — onde ele permanece, já que nada mais pode exibi-lo em um celular.

## Link do repositório [#repository-link]

Quando você define [`github`](/docs/configuration) na sua configuração, o Blume mostra um ícone do GitHub no cabeçalho — ao lado do alternador de tema — que leva ao seu repositório. Ele vem ativado por padrão; oculte-o com `navigation.repo`:

```ts blume.config.ts lineNumbers
navigation: {
  repo: false, // hide the header GitHub link (default: true)
}
```

O link só aparece quando `github` está configurado, então projetos sem repositório não são afetados de nenhuma forma.

`repo` também aceita uma URL absoluta, que aponta a marca do cabeçalho para qualquer lugar no GitHub:

```ts blume.config.ts lineNumbers
navigation: {
  repo: "https://github.com/acme",
}
```

Isso é para um projeto cujo repositório de documentação é privado. O `github` controla junto o link de edição de cada página, a marca do cabeçalho e o repositório do [manifesto de agente](/docs/discoverability/agent-discovery), então um projeto assim precisa deixar `github` sem definir — e uma URL é o que permite que ele ainda exiba uma marca apontando para algo público. O ícone continua sendo a marca do GitHub, então um link para outro host pertence a [`actions`](#header-actions).

## Trilhas de navegação e paginação [#breadcrumbs-and-pagination]

Elas vêm de graça a partir da árvore da barra lateral — sem configuração:

- **Trilhas de navegação** mostram o grupo pai da página atual acima do título.
- **Links de anterior e próximo** no rodapé de cada página seguem a ordem da barra lateral, pulando páginas ocultas.

## Nesta página [#on-this-page]

Um sumário na coluna direita é gerado automaticamente a partir dos títulos `##` e `###` de cada página, para que páginas longas continuem fáceis de escanear. Em telas mais estreitas, onde a coluna direita fica oculta, ele se recolhe em um dropdown “Nesta página” acima do conteúdo.

## Ações da página [#page-actions]

Abaixo do sumário, toda página exibe um conjunto de ações rápidas:

- **Editar no GitHub** — leva direto ao arquivo-fonte. Aparece assim que você define [`github`](/docs/configuration) na sua configuração.
- **Voltar ao topo** — retorna suavemente ao topo de páginas longas.
- **Enviar feedback** — abre uma issue do GitHub pré-preenchida com uma reação e uma nota opcionais (também requer `github`).

Outras entregam a página a ferramentas de IA — **Copiar como Markdown** e **Abrir no chat** — abordadas em [IA](/docs/discoverability/markdown#copy-as-markdown).

Com [`export`](/docs/configuration/export) ativado, uma ação de **Exportar** também permite que os leitores baixem a página como PDF ou EPUB.