Frontmatter

Todos os campos de frontmatter que uma página aceita, todos opcionais — title, description, sidebar, SEO, search e os demais, com o que cada um controla.

Toda página aceita o frontmatter a seguir. Todos os campos são opcionais.

O frontmatter é YAML, então coloque entre aspas um valor que contenha dois-pontos seguidos de espaço, como description: "Setup: the easy way". Sem aspas, o YAML interpreta o segundo sinal de dois-pontos como o início de uma chave aninhada, e o Blume aponta o arquivo e a linha com o erro BLUME_FRONTMATTER_INVALID.

Layout

mode define o que uma página mostra ao redor do conteúdo:

wide combina com uma página de tabelas largas ou diagramas, e center, com notas de versão ou um anúncio lido de cima a baixo. custom mantém só o cabeçalho, para uma landing page escrita em MDX, e frame mantém também a barra lateral, para uma ferramenta ou dashboard que fica dentro da navegação da documentação. Nenhum dos dois renderiza o título ou a descrição da página, então escreva seu próprio título. Todos os modos continuam na busca e mantêm sua cópia em Markdown.

title: Welcome
mode: custom

Os valores são os mesmos do Mintlify. O modo assistant dele, um chat de página inteira, não tem equivalente.

Páginas relacionadas

related lista páginas para sugerir no fim desta, como cards sob o título Páginas relacionadas:

related:
  - /guides/deployment
  - Search setup: /configuration/search
  - https://astro.build

Um caminho relativo à raiz aponta para outra página, que o card mostra com o título e a descrição dela. Em uma página traduzida, o link vai para a tradução, quando ela existir. Uma entrada Title: link define o título do próprio card, e uma URL absoluta leva para fora do site, exibida com o nome do host. Os caminhos são verificados como qualquer link da página, então o blume validate aponta um caminho que não corresponda a nenhuma página. A chave é a mesma do Mintlify, então páginas migradas a mantêm como está.

Barra lateral

sidebar:
  label: Install
  order: 2
  icon: download
  badge: New
  hidden: false
  display: page

hidden remove a página da barra lateral e da paginação anterior/próxima e, com isso, também do sitemap, da busca e do llms.txt (veja Páginas ocultas). Na página index de uma pasta, ele remove só a linha da própria página: a linha do grupo continua apontando para a página, então os links de anterior/próxima ainda passam por ela e a página continua no sitemap, na busca e no llms.txt. Na página inicial, a página index da raiz, ele também remove só a linha: a página continua no sitemap, na busca e no llms.txt.

display define o modo de renderização do grupo da pasta da página (substituições por grupo) e só faz sentido na página index de uma pasta dentro da barra lateral gerada. Em qualquer outro lugar (uma página que não é index, a própria página index da raiz do conteúdo ou qualquer página sob um navigation.sidebar explícito), não existe grupo para configurar, e o Blume emite o aviso BLUME_SIDEBAR_DISPLAY_IGNORED.

SEO

seo:
  title: Install Blume
  description: Install Blume and scaffold your first project.
  image: /og/install.png
  canonical: https://acme.com/install
  noindex: false
  x:
    creator: "@jane"

noindex emite um noindex para robôs, tira a página do sitemap e omite os dados estruturados dela. Um canonical que aponte para outra URL também tira a página do sitemap, já que o sitemap lista só URLs canônicas. x.creator atribui a página a uma conta do X (twitter:creator), como o autor de um post convidado, por exemplo. Veja Metadados para conhecer todos os campos.

Busca

search:
  exclude: false
  tags: [api]
  keywords: [install, setup]
  boost: 3

exclude deixa a página fora da busca, e tags rotula o registro dela para que um adaptador de busca hospedada possa filtrar por ele (veja Tags). keywords são termos extras pelos quais a página pode ser encontrada, além do próprio texto dela. boost multiplica a relevância da página: acima de 1, ela sobe no ranking; abaixo de 1, desce. Veja Classificação.

IA

ai:
  exclude: true

ai.exclude deixa a página fora do llms.txt e do llms-full.txt e do mapa de páginas da skill do seu site. A página continua sendo renderizada, segue disponível na busca, no servidor MCP e na API JSON e mantém seu lugar no sitemap.

Changelog

Entradas de changelog (type: changelog) aceitam um objeto changelog opcional para metadados mais completos de feed e de exibição:

type: changelog
changelog:
  version: 1.2.0
  date: 2026-06-20
  category: Features

date pode ficar aqui ou no nível superior. Os dois alimentam o feed RSS do changelog. Veja Changelog para saber mais sobre a página de linha do tempo gerada e o feed.

Chaves personalizadas

Qualquer chave que não esteja nesta referência faz o build falhar, então erros de digitação são detectados logo. Projetos com metadados próprios podem habilitar chaves extras com frontmatter.extend no blume.config.ts. Cada uma é validada por um schema fornecido pelo projeto:

import { defineConfig } from "blume";
import { z } from "zod";

export default defineConfig({
  frontmatter: {
    extend: {
      owner: z.string(),
      reviewedAt: z.coerce.date().optional(),
    },
  },
});

---
title: Install
owner: "@sam"
reviewedAt: 2026-06-20
---

Os schemas são aceitos pela interface Standard Schema, então Zod (em qualquer versão que seu projeto instalar), Valibot e ArkType funcionam. Toda chave declarada é validada em todas as páginas, inclusive nas que não têm essa chave. Por isso, um schema obrigatório exige a chave no site inteiro. Marque-o com .optional() para validar só onde a chave aparecer. Todas as outras chaves continuam com validação estrita, e os campos nativos não podem ser declarados de novo.

Chaves por tipo

Para exigir chaves só em um tipo de conteúdo, como o status de uma RFC ou a severity de um relatório de incidente, declare-as em content.types. Elas ficam agrupadas pelo type de frontmatter ao qual se aplicam:

import { defineConfig } from "blume";
import { z } from "zod";

export default defineConfig({
  content: {
    types: {
      rfc: {
        frontmatter: {
          domain: z.string(),
          status: z.enum(["draft", "review", "enforced"]),
        },
      },
    },
  },
});

---
title: OpenAPI request schemas
type: rfc
domain: architecture
status: enforced
---

As chaves por tipo seguem as mesmas regras de validação do extend, mas só valem para as páginas cujo type resolvido corresponde. Isso inclui páginas que não definem type, quando a declaração é para o content.defaultType. Cada chave pertence a uma única declaração, para o site inteiro ou por tipo, nunca às duas. Além disso, uma chave declarada só para outro tipo continua desconhecida no resto do site. Então um status esquecido em uma página de documentação comum ainda faz o build falhar.

Uma página que não passa na validação faz o blume build falhar com um diagnóstico que indica o arquivo e a chave. Com --no-strict, o build termina mesmo assim, e as páginas com falha ficam de fora da saída. O resumo do build informa quantas foram.

Os schemas são exportados de blume/schema para ferramentas de editor e de migração.