Meta de pasta

Configure um grupo da barra lateral com um arquivo meta.ts junto às suas páginas — defina o título, o ícone e a ordem do grupo, além da ordem das páginas aninhadas dentro dele.

Toda pasta na sua árvore de conteúdo se torna um grupo da barra lateral. Coloque um meta.ts junto às suas páginas para controlar a aparência desse grupo e a ordenação de seus filhos. É totalmente opcional: sem ele, o rótulo do grupo é o nome da pasta humanizado e suas páginas são ordenadas por índice, prefixo numérico e, então, alfabeticamente.

Definindo o meta

Exporte um objeto defineMeta para obter uma configuração totalmente tipada. Coloque o arquivo na raiz da pasta que ele configura — guides/meta.ts configura o grupo Guias:

import { defineMeta } from "blume";

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

Todos os campos são opcionais — defina apenas o que você quiser sobrescrever.

O Blume só lê arquivos meta.ts de pastas que o seu conteúdo abrange: um arquivo em uma pasta ignorada pelos globs de exclude do seu conteúdo, ou fora de todos os globs de include, nunca é importado. Com root: "." e exclude: ["src/**"], um src/lib/meta.ts não relacionado é deixado de lado.

Um meta.ts fora de todos os globs de include continua sendo ignorado mesmo quando a pasta dele é um grupo da barra lateral, como a pasta de tag de uma referência em um site cujo include lista apenas guides/**. O Blume emite um aviso sobre esse caso como BLUME_META_OUTSIDE_INCLUDE: adicione um glob de include que alcance a pasta, como "api/**/*.{md,mdx}", para que o Blume o leia.

Campos

O array pages lista os filhos por slug — o nome da pasta ou do arquivo com o prefixo numérico e quaisquer parênteses removidos (portanto 01-quickstart.mdx é "quickstart"). Cada filho listado recebe sua posição no array como ordem (0, 1, 2, …). Os filhos que você deixar de fora ainda aparecem, ordenados pela própria ordem: uma página index continua em primeiro lugar, um filho com sidebar.order, prefixo numérico ou um order no próprio meta.ts é posicionado por esse número entre os listados, e um filho sem nenhum deles vai depois deles. Liste todos os filhos quando o array tiver que definir a ordem completa. Uma entrada que não corresponde a nenhuma página ou pasta do grupo não ordena nada, então o Blume emite um aviso sobre ela como BLUME_META_UNKNOWN_PAGE, na linha dela no meta.ts, e sugere o slug a que ela mais provavelmente se refere.

O array ordena páginas entre páginas e grupos entre grupos, mas não intercala os dois onde as páginas soltas são listadas acima dos grupos: no topo da barra lateral (e de cada seção de aba) e em qualquer grupo com um subgrupo flat, cujo cabeçalho, de outra forma, pareceria englobar as páginas que vêm depois dele. Nesses casos, pages: ["advanced", "intro"] ainda lista a página intro acima do grupo advanced.

Como os grupos são renderizados — cabeçalhos planos, blocos recolhíveis ou painéis de navegação em profundidade — o padrão é o navigation.sidebar.display de toda a barra lateral; defina display aqui para sobrescrevê-lo apenas para este grupo. A página index de uma pasta também pode defini-lo pelo frontmatter, o que tem precedência sobre o meta.ts — veja sobrescritas por grupo.

Grupos gerados

Uma referência OpenAPI, AsyncAPI ou GraphQL nomeia e ordena seus grupos de tags a partir da especificação. Para alterar um deles, adicione um meta.ts na pasta sob a qual as páginas da tag são publicadas: com a referência em /api, um api/pets/meta.ts na sua pasta de conteúdo configura o grupo Pets. Os campos que ele define substituem os gerados, e os demais mantêm os valores gerados, então um meta.ts que define apenas title mantém a posição da tag na ordem da especificação.

Meta computado

Como meta.ts é um módulo de verdade, você pode computar o meta — passe uma função (síncrona ou async) em vez de um objeto para construí-lo no momento da varredura. Prático para ordenar páginas a partir de uma fonte externa:

import { defineMeta } from "blume";

export default defineMeta(async () => ({
  title: "Guides",
  pages: await orderFromCms(),
}));

Ordenação dentro de um grupo

O array pages define a ordem dos filhos de um grupo e tem precedência sobre o sidebar.order de uma página listada ou o order de uma subpasta listada. Tudo que ele omitir recorre ao sidebar.order do frontmatter de cada página e, em seguida, ao sistema de arquivos (uma página index primeiro, depois os prefixos numéricos e então a ordem alfabética). Para a precedência completa da barra lateral — incluindo uma barra lateral explícita na configuração — veja Navegação › Ordenação.

Para agrupar páginas sem adicionar um segmento de URL, você não precisa de um meta.ts: use um nome de pasta entre parênteses — veja Páginas › Pastas de grupo.

Internacionalização

Sob o i18n, o meta de pasta é resolvido por locale: coloque um meta.ts em fr/guides/ para ordenar o grupo em francês de forma independente. Sem ele (ou sem um meta.$.ts compartilhado, veja abaixo), o grupo em francês espelha o meta.ts do locale de fallback.

Para um meta de pasta idêntico em todos os idiomas, adicione um marcador $ para que um único arquivo sirva a todos os locales sem duplicação:

docs/guides/meta.$.ts   (folder meta applied to every locale)

Um meta.ts específico de locale ainda sobrescreve o meta.$.ts compartilhado para aquele idioma.

Para onde ir agora