Navegação

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.

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, com siglas comuns como API, CLI e SDK em maiúsculas (api-reference vira “API Reference”)
os itens são ordenados por prefixo numérico 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

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

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 para o esquema completo da página.

Grupos de pastas

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

import { defineMeta } from "blume";

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

Veja Meta de pasta 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 título desatualizado na própria página de destino. O Blume emite um aviso BLUME_NAV_INDEX_TITLE_MISMATCH quando eles divergem em uma página de índice que oculta a própria linha na barra lateral (sidebar.hidden: true), caso em que o título da pasta é o único rótulo que a página tem na barra lateral. A verificação lê o title, que é o que o título da página exibe; o seo.title substitui apenas o <title>, então não conta. 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.

Como todo aviso, ele faz o blume validate --strict falhar. Qualquer uma destas opções o resolve:

Altere o title da página ou o meta.title da pasta para que os dois coincidam.
Mantenha o título da página de propósito definindo o sidebar.label dela como o título da pasta, do mesmo jeito que qualquer página define um rótulo na barra lateral diferente do seu título.
Mostre a linha do índice de novo. A barra lateral passa a mostrar os dois títulos, então combinar um título de pasta com um título de página diferente (“CLI” acima de “Overview”) não tem problema.

Para agrupar páginas sem adicionar um segmento de URL, use um nome de pasta entre parênteses — veja Páginas.

Modos de exibição

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

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. Um grupo que é a única linha no topo da barra lateral, como uma pasta que envolve todas as páginas, também começa aberto, para que a barra lateral nunca mostre uma única linha fechada. Defina collapsed: false no meta de pasta para forçar um grupo a ficar aberto independentemente disso, ou collapsed: true para manter esse grupo solitário fechado.
page — cada grupo é uma única linha cujo chevron desliza a barra lateral para um subpainel mostrando apenas os itens daquele grupo, com uma seta de voltar no topo. Um grupo com uma página de índice liga o nome da linha a essa página, e um grupo sem ela faz o painel deslizar a partir de qualquer ponto da linha. O painel reconhece a rota, então cair diretamente em uma página dentro do grupo abre direto nela. Depois de usar a seta de voltar, a linha da seção em que você está continua destacada.

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

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

import { defineMeta } from "blume";

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

---
title: Client SDKs
sidebar:
  display: page
---

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

sidebar.display no frontmatter da própria página index do grupo
display no meta.ts da pasta
O navigation.sidebar.display global
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 liga o nome da sua linha a essa página, então clicar no nome abre a página de destino com o subpainel já aberto, enquanto o chevron ao lado faz o painel deslizar sem sair da página atual. O título do painel leva de volta à página de destino, e a página de índice aparece como o primeiro item do painel, a menos que esteja oculta. Um grupo em modo page sem página de índice não tem o que abrir, então a linha inteira faz o painel deslizar.

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 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 substitui o modo global com seu próprio display, exatamente como antes.

Listagens de diretório

A página própria de um grupo pode listar as outras páginas do grupo abaixo do seu conteúdo, de modo que a página de destino de uma seção também serve como o seu sumário. Defina directory no meta.ts da pasta:

import { defineMeta } from "blume";

export default defineMeta({
  directory: "card",
});

card mostra cada página e subgrupo como um card com o seu ícone e a sua descrição.
accordion lista as páginas como linhas, e cada subgrupo como uma seção que se abre para mostrar as suas páginas.
none não lista nada. Esse é o padrão.

Só um grupo com página própria tem onde mostrar a listagem: a página index de uma pasta ou o root de um grupo explícito. A configuração é herdada pelas pastas aninhadas, então um único directory no meta.ts da raiz do conteúdo dá uma listagem a todas as seções, e uma pasta pode definir o seu próprio valor (inclusive none) para substituir o que herda. Uma barra lateral explícita define directory nos seus grupos da mesma forma.

Ordenação

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

Barra lateral da configuração

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

Meta de pasta

O array pages em meta.ts ordena um grupo.

Frontmatter

sidebar.order em uma página.

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

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:

sidebar:
  hidden: true

Uma página oculta também fica de fora do sitemap e do llms.txt, e também da busca do site, a menos que search.indexing.includeHiddenPages esteja ativado.

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. Como a navegação continua apontando para a página, ela não é tratada como oculta em nenhum outro lugar: continua no sitemap, na busca do site e no llms.txt. O mesmo vale para a página inicial do site, a página index da raiz: ocultá-la remove a linha dela da barra lateral, mas ela continua sendo servida na URL raiz do site, então também continua listada.

Abas

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:

navigation: {
  tabs: [
    { label: "Adapters", path: "/adapters", icon: "plug" },
    { label: "API", path: "/api", icon: "rocket" },
    { label: "AI", path: "/ai", icon: "sparkles" },
  ],
}

O icon opcional de uma aba (um nome de ícone integrado, caminho/URL de imagem ou SVG inline) aparece ao lado do seu rótulo, no cabeçalho e na gaveta de navegação móvel.

Uma referência OpenAPI, AsyncAPI ou GraphQL 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:

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. Isso inclui uma aba em path: "/" em um site sem index.mdx na raiz: ela aponta para a primeira página da barra lateral. Uma página personalizada estática no path da aba conta como a página própria da seção: com pages/guides.astro, uma aba /guides cai nessa página enquanto a pasta guides/ preenche a sua barra lateral. O mesmo vale para o índice de changelog gerado, então uma aba /changelog abre a linha do tempo em vez da entrada mais recente.

Defina href quando quiser que uma aba leve a outro lugar — uma página específica da seção, digamos:

navigation: {
  tabs: [
    { label: "Guides", path: "/guides", href: "/guides/getting-started" },
  ],
}

Abas que não definem href mantêm a resolução descrita acima.

Dê items a uma aba para transformá-la em um dropdown. A aba deixa de ser um link por si só: ela abre um menu com os seus itens no cabeçalho e os expande no lugar na gaveta de navegação móvel. O seu path continua delimitando a barra lateral e marcando a aba como atual, e href não se aplica. Cada item recebe um label e um path, além de icon, description e tag opcionais, como um item de seletor:

navigation: {
  tabs: [
    { label: "Guides", path: "/guides" },
    {
      label: "SDKs",
      path: "/sdks",
      items: [
        { label: "JavaScript", path: "/sdks/javascript", description: "Node and the browser" },
        { label: "Python", path: "/sdks/python", tag: "Beta" },
      ],
    },
  ],
}

Em um site com 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:

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

Os rótulos de um seletor não aceitam um mapa: o seu label e os rótulos de cada um dos seus itens são strings simples.

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

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:

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 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.

Em telas estreitas demais para a barra lateral do desktop, os seletores, o seletor de versão e o alternador de idioma saem do cabeçalho e vão para o topo da gaveta de navegação móvel, onde cada um ocupa toda a largura da gaveta.

Links em destaque

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.

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, 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 e pelo blume doctor, avisando você se nada corresponder. Um caminho para um arquivo em public/ (/spec.pdf) ou para um que o Blume gera (/llms.txt) também corresponde.

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 global. Quando os itens são definidos, o Blume os usa literalmente e pula a geração pelo sistema de arquivos:

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 global, começar collapsed e vincular uma página root, que pode listar as páginas do grupo com um directory.

O Blume emite um aviso sobre um item que não consegue renderizar como foi escrito: uma rota que não corresponde a nenhuma página (o item fica de fora), um root que não corresponde a nenhuma página (o link dele levaria a um 404) ou um item sem rota, href, root ou items (fica de fora).

Ações do cabeçalho

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

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

Assim como os rótulos das abas, um label aqui pode ser um mapa de código de idioma para texto em um site multilíngue.

Uma ação é apenas um link, então um changelog vinculado dessa forma continua listando as suas entradas na barra lateral. Vincule-o com uma aba para mantê-las fora.

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 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

Quando você define github na sua configuração, o Blume mostra um ícone do GitHub no rodapé, antes dos seus perfis sociais, que leva ao seu repositório. Ele vem ativado por padrão; oculte-o com navigation.repo:

navigation: {
  repo: false, // hide the footer's 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 GitHub para qualquer lugar no GitHub:

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 GitHub e o repositório do manifesto de agente, 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. Uma URL em footer.socials.github toma o lugar da marca, e um link para outro host pertence aos links do rodapé ou a actions.

Trilhas de navegação e paginação

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. Defina pagination: false no frontmatter de uma página para removê-los dessa página.

Nesta página

Um sumário na coluna direita é gerado automaticamente a partir dos títulos de cada página — ## e ### por padrão — para que páginas longas continuem fáceis de escanear. Defina toc para mudar o intervalo de títulos ou desativar o sumário. Em telas mais estreitas, onde a coluna direita fica oculta, ele se recolhe em um dropdown “Nesta página” acima do conteúdo, que também reúne as ações da página.

Ações da página

Abaixo do sumário, toda página exibe um conjunto de ações rápidas. Em janelas com pelo menos 1.280px de largura, elas ficam na coluna da direita junto com o sumário. Em janelas mais estreitas e em celulares, elas ficam na parte de baixo do dropdown “Nesta página” acima do conteúdo, que aparece também em páginas sem títulos:

Editar no GitHub — leva direto ao arquivo-fonte. Aparece assim que você define github na sua configuração, em toda página cujo arquivo está no repositório: um arquivo que o git ignora, como uma referência de API gerada escrita em uma pasta ignorada pelo git, não ganha link de edição, já que o GitHub não tem arquivo para abrir.
Voltar ao topo — retorna suavemente ao topo de páginas longas. Fica apenas na coluna da direita, já que o dropdown já está no topo da página.

Outras entregam a página a ferramentas de IA — Copiar como Markdown e Abrir no chat — abordadas em Markdown para agentes.

Já o feedback fica no rodapé da página: uma avaliação de sim/não “Esta página foi útil?” que envia um evento de analytics feedback e não precisa de github — veja Feedback da página.

Com export ativado, uma ação de Exportar também permite que os leitores baixem a página como PDF ou EPUB.