Arquivo de configuração

Todas as opções em blume.config.ts, desde os metadados do site e as fontes de conteúdo até os links que levam a cada guia individual de configuração de funcionalidade.

O Blume lê o blume.config.ts a partir da raiz do seu projeto. Envolva sua configuração em defineConfig para ter preenchimento automático e verificação de tipos — todos os campos são opcionais, com um valor padrão sensato.

import { defineConfig } from "blume";

export default defineConfig({
  title: "My Docs",
  description: "Documentation for my project.",
});

Um exemplo completo

Um exemplo mais abrangente que aborda as opções mais comuns (consulte o guia de cada funcionalidade para as demais):

import partytown from "@astrojs/partytown";
import { defineConfig } from "blume";
import { orama } from "blume/search";

export default defineConfig({
  // Site
  title: "My Docs",
  description: "Documentation for my project.",
  logo: "/logo.svg",

  // Astro integrations — installed and versioned by this site
  integrations: [partytown()],

  // Content
  content: {
    root: "docs",
  },

  // Theme — see the Theming guide
  theme: {
    accent: "teal",
    radius: "md",
    mode: "system",
  },

  // Search — an adapter from "blume/search"; see the Search guide
  search: orama(),

  // Markdown features
  markdown: {
    imageZoom: true,
    externalLinks: false, // open https:// links in a new tab
    code: {
      icons: true, // language icon in the code-block header
      wrap: false, // wrap long lines instead of scrolling
      theme: {
        light: "github-light", // bundled name or custom Shiki theme object
        dark: "github-dark",
      },
    },
  },

  // Agents — llms.txt, MCP, the AI catalog; see the Discoverability section
  agents: {
    llmsTxt: true,
    // AI Catalog / ARD manifest at /.well-known/ai-catalog.json (needs deployment.site)
    catalog: true,
    // Your site's agent skill at /skill.md (needs deployment.site)
    skillMd: true,
    // MCP server (needs server output)
    mcp: {
      enabled: false,
      route: "/mcp",
    },
  },

  // SEO — OG images, feeds, sitemap, structured data; see the Discoverability section
  seo: {
    og: { enabled: true },
    rss: { enabled: true, types: ["blog", "changelog"] },
    sitemap: true,
    robots: true,
    structuredData: true,
  },

  // Deployment — a static build here; see the Deployment guide for host adapters
  deployment: {
    site: "https://docs.example.com",
  },
});

Site

Logotipo

Aponte o logo para um SVG e o Blume o incorpora inline, para que um logotipo com currentColor acompanhe automaticamente o tema claro e escuro:

logo: "/logo.svg",

O SVG pode ficar na raiz do seu projeto ou em public/. A marca é composta por um símbolo (image) mais um logotipo textual (text); a forma de objeto permite defini-los de forma independente:

logo: {
  image: "/logo.svg", // string, or { light, dark, alt } for themed raster art
  text: "Acme",       // wordmark beside the mark
  href: "/",          // overrides the brand link (defaults to "/")
},

image aceita o mesmo valor que a forma abreviada — um único caminho, ou { light, dark, alt } para artes separadas para claro/escuro (as imagens raster precisam ficar em public/).

href é um caminho do locale padrão, assim como o caminho de uma aba: em um site com vários locales, o link da marca passa para o locale do leitor (/ vira /en em /en/…) sempre que esse locale serve a rota, então clicar no logotipo não tira o leitor do idioma em que estava lendo. Uma rota que só o locale padrão serve — uma página personalizada ou o índice de changelog gerado — mantém o próprio caminho em vez de apontar para uma URL localizada que daria 404. Uma URL absoluta é usada sem alterações.

text controla o logotipo textual independentemente do símbolo:

• Omita text e a marca usa o title do seu site (o padrão).
• Defina text: "" para mostrar apenas o símbolo — útil quando a imagem do logotipo já inclui o logotipo textual. Nesse caso, os leitores de tela anunciam o link da marca pelo alt da imagem ou, quando ela não tiver um, pelo title do seu site.
• Defina text sem image para um logotipo apenas de texto.

Favicon

Não existe uma opção de favicon — o Blume detecta um automaticamente pelo nome do arquivo, como o Next.js faz. Coloque um arquivo icon ou favicon (.svg, .png ou .ico) na raiz do seu projeto ou no diretório public/ e ele vira o ícone da aba do navegador:

my-docs/
├─ blume.config.ts
├─ icon.png          ← picked up automatically
└─ docs/

O SVG prevalece sobre o PNG, que prevalece sobre o ICO quando há vários, e um arquivo em public/ é preferido a um na raiz. Se o Blume não encontrar nenhum ícone, ele recorre à sua própria marca.

Uma marca escura desaparece contra a interface escura do navegador, então você pode fornecer um segundo arquivo para o modo escuro. Adicione um arquivo irmão -dark ao seu arquivo de ícone — o mesmo nome e o mesmo diretório, com -dark antes da extensão (icon.png → icon-dark.png) — e o Blume emite os dois ícones atrás de uma media query prefers-color-scheme, além de uma tag clara simples para navegadores e crawlers que ignoram media queries em ícones:

my-docs/
├─ blume.config.ts
├─ icon.png          ← light mode
├─ icon-dark.png     ← dark mode
└─ docs/

Só o irmão do ícone que o Blume escolheu é usado — um arquivo -dark com um nome diferente continua ignorado, então um arquivo sem relação não pode se emparelhar com a sua marca por acidente. O arquivo escuro é opcional; com apenas um ícone, o Blume emite uma única tag como antes. A marca de fallback do próprio Blume inclui as duas variantes.

Ícone Apple touch

O ícone que o iOS usa quando alguém adiciona seu site à tela de início é detectado da mesma forma. Coloque um arquivo apple-icon (.png, .jpg ou .jpeg) — ou um apple-touch-icon.png, o nome que a maioria dos geradores de favicons produz — na raiz do seu projeto ou no diretório public/ e o Blume cuida de configurar <link rel="apple-touch-icon"> para você. Não há padrão; se nenhum arquivo for encontrado, nenhuma tag é emitida.

my-docs/
├─ blume.config.ts
├─ apple-icon.png     ← picked up automatically
└─ docs/

Coloque o arquivo em public/ em vez da raiz do projeto: o iOS ignora o URI de dados incorporado que o Blume usa para um ícone no nível da raiz, então só um arquivo em public/ (servido em /apple-icon.png) chega de forma confiável à tela de início. Diferentemente do favicon, aqui não existe um irmão -dark — o iOS ignora media queries nos ícones da tela de início, então uma variante escura nunca poderia ser servida.

Faixa

Mostre uma barra de anúncios para todo o site acima do cabeçalho. Passe uma string, ou um objeto com um link e um botão para dispensar:

banner: "Docs are in beta — expect changes.",

banner: {
  content: "Version 2.0 is here!",
  link: { text: "Read the release notes", href: "/changelog" },
  dismissible: true,
  id: "v2",
},

Quando dismissible está ativo, a barra mostra um botão de fechar e permanece oculta para aquele visitante daí em diante. A chave de dispensa assume por padrão o texto do conteúdo, então editar a mensagem faz a faixa reaparecer; defina um id estável para mantê-la dispensada entre edições.

Em um site multilíngue, content e o text do link também aceitam um mapa de código de locale para texto. Cada página mostra a entrada do próprio locale, recorrendo à do locale padrão, e o link passa para o locale do leitor sempre que esse locale serve a página:

banner: {
  content: { en: "Version 2.0 is here!", fr: "La version 2.0 est là !" },
  link: {
    text: { en: "Read the release notes", fr: "Lire les notes de version" },
    href: "/changelog",
  },
},

Uma faixa traduzida usa o texto do locale padrão como chave de dispensa, então dispensá-la uma vez a oculta em todos os idiomas.

Rodapé

Toda página termina com um rodapé: uma única linha, da mesma altura do cabeçalho, com seus links de um lado, ícones de perfis sociais do outro e um aviso de copyright centralizado entre eles. O rodapé é o único lugar onde o Blume coloca links para seus perfis sociais e seu repositório, então o repositório do github vem primeiro entre os ícones sempre que estiver definido. O footer adiciona o resto:

footer: {
  copyright: "© 2026 Acme, Inc.",
  links: [
    { label: "Pricing", href: "https://acme.dev/pricing" },
    { label: "Changelog", href: "/changelog" },
    { label: "Blog", href: "https://acme.dev/blog" },
  ],
  socials: {
    x: "https://x.com/acme",
    discord: "https://discord.gg/acme",
  },
},

copyright é texto simples, então escreva o próprio © em vez de ©. Para que o ano se mantenha sempre atualizado, use um template literal: `© ${new Date().getFullYear()} Acme, Inc.`. Os links aparecem na ordem em que você os escreve. Escreva os links internos como se o site estivesse montado na raiz; um link externo abre em uma nova aba. Em um site multilíngue, tanto o copyright quanto um label podem ser um mapa de código de locale para texto, e um link interno passa para o locale do leitor sempre que esse locale serve a página. socials associa cada plataforma à URL do seu perfil, e os ícones aparecem na ordem em que você os escreve. As plataformas são bluesky, discord, facebook, github, hacker-news, instagram, linkedin, medium, podcast, reddit, slack, telegram, threads, website, x e youtube. Uma entrada github em socials substitui o link para o repositório; oculte esse link com navigation.repo.

Um site sem copyright, links, perfis ou repositório não tem rodapé. As páginas personalizadas construídas sobre o PageLayout também o exibem, a menos que preencham o próprio slot footer do layout. Para substituí-lo por completo, sobrescreva o slot de layout Footer.

Conteúdo

Onde seu conteúdo fica e como o Blume o descobre. Consulte Páginas para saber como os arquivos viram rotas.

content: {
  root: "docs",
}

Os recursos estáticos ficam em public/ — um arquivo em public/logo.png é servido em /logo.png, então uma referência como ![](/images/create.png) é resolvida a partir de public/images/create.png. As imagens referenciadas por caminho relativo (![](./diagram.png)) ficam junto ao seu conteúdo e são otimizadas no momento da build.

Imagens

As imagens locais referenciadas por caminho relativo são otimizadas automaticamente no momento da build — comprimidas, convertidas para WebP e com atributos width/height intrínsecos, para que o layout não se desloque enquanto elas carregam. Não há nada a configurar; consulte Links e imagens para orientações de escrita.

As imagens remotas são servidas sem alterações por padrão. Para que o Blume também as baixe e otimize no momento da build, autorize seus hosts:

image: {
  domains: ["cdn.example.com"],
  remotePatterns: [{ protocol: "https", hostname: "**.example.com" }],
}

Frontmatter

O frontmatter das páginas é validado de forma estrita — uma chave desconhecida faz a build falhar, então os erros de digitação são detectados cedo. Para levar metadados específicos do projeto (um responsável, uma data de revisão), declare as chaves adicionais em frontmatter.extend, cada uma mapeada para um schema que você fornece:

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

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

Funciona com qualquer biblioteca Standard Schema — Zod (qualquer que seja a versão que seu projeto instale), Valibot, ArkType. As chaves fora da extensão continuam validadas de forma estrita, então a detecção de erros de digitação segue inalterada. Consulte Chaves personalizadas para a semântica de validação.

As chaves em extend valem para todo o site. Para exigir chaves apenas em páginas de um tipo de conteúdo — o status de um RFC, o service de um runbook — declare-as por tipo em content.types:

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

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

Uma chave pode ser declarada para todo o site ou por tipo, não os dois. Consulte Chaves por tipo para saber como o escopo é resolvido.

facets indica as chaves personalizadas cujos valores viram metadados filtráveis: elas acompanham os documentos de busca (blume-search.json e o índice MCP), e as ferramentas MCP aceitam um input filters que faz correspondência com elas, para que um agente possa obter, por exemplo, apenas os RFCs com status enforced no domínio architecture. Cada faceta precisa ser uma chave personalizada declarada — por tipo ou para todo o site — e apenas os valores do tipo string (ou números/booleanos convertidos em string) funcionam como facetas.

GitHub

Aponte o Blume para o seu repositório com github. É o que alimenta o link para o repositório no rodapé e a ação de página Editar no GitHub:

github: {
  owner: "acme",
  repo: "docs",
}

GitHub Enterprise

Docs cujo repositório fica em uma instância do GitHub Enterprise definem host, e todo link derivado do repositório — a marca do cabeçalho, os links de edição, o manifesto do agente — aponta para essa instância em vez do site público:

github: {
  host: "https://github.acme.com",
  owner: "acme",
  repo: "docs",
}

A base da API REST que o <GithubInfo> consulta é derivada de host: um tenant do Enterprise Cloud com residência de dados (acme.ghe.com) é servido a partir do seu subdomínio api., e qualquer outro host é tratado como Enterprise Server (/api/v3). Defina api explicitamente quando sua instância estiver em outro lugar.

Última modificação

Mostre uma linha “Última atualização em …” no rodapé de cada página. Desativado por padrão; defina lastModified como "git" para derivar a data de cada página do respectivo histórico do git:

lastModified: "git",

A fonte git lê o commit mais recente que tocou em cada arquivo, então funciona em qualquer repositório git — incluindo monorepos — e precisa do histórico do repositório no momento da build. Ela acompanha renomeações, como o git log --follow faz: renomear page.md para page.mdx, ou mover um arquivo para outra pasta dentro da mesma raiz de conteúdo, mantém a data da página, desde que o commit não altere o conteúdo do arquivo. Uma renomeação que também edita o arquivo faz a página assumir a data desse commit, e o mesmo acontece ao mover para a raiz de conteúdo um arquivo que estava fora dela. As plataformas de CI costumam fazer checkout de um clone raso, o que descarta silenciosamente a maioria das datas (a build avisa com BLUME_SHALLOW_GIT_HISTORY quando isso acontece): na Vercel, defina a variável de ambiente VERCEL_DEEP_CLONE=true; com o actions/checkout, defina fetch-depth: 0. O lastModified do frontmatter da própria página sempre prevalece, o que é útil para fixar uma data ou para arquivos que ainda não foram commitados:

---
title: My page
lastModified: 2026-06-20
---

Quando ativada, a data também é emitida como dateModified do schema.org nos dados estruturados da página.

Formato de data

Tanto a marca de “Última atualização” quanto a linha do tempo do changelog exibem suas datas através do mesmo dateFormat, para que elas sejam lidas do mesmo jeito. As datas são sempre exibidas no locale do site; o dateFormat controla o formato. Por padrão ele usa a forma longa (July 21, 2026, 2026年7月21日):

dateFormat: { dateStyle: "long" },

dateFormat é repassado diretamente para as opções de Intl.DateTimeFormat. Use um preset dateStyle para escolher um comprimento:

dateFormat: { dateStyle: "medium" },

Ou os campos de componentes individuais para um estilo numérico próprio como 2026/07/21:

dateFormat: { year: "numeric", month: "2-digit", day: "2-digit" },

timeZone, calendar e numberingSystem não alteram o formato: um dateFormat que define apenas essas opções mantém a forma longa.

SEO e agentes

Metadados, imagens Open Graph, feeds RSS, JSON-LD, o sitemap e o robots.txt ficam em seo; o llms.txt, o Markdown bruto, a API JSON, o servidor MCP e os manifestos de descoberta ficam em agents. Os dois são abordados página a página na seção Descoberta, que trata os buscadores e os agentes de IA como dois públicos da mesma camada legível por máquina. As funcionalidades de modelo voltadas para o leitor — o assistente e a ação Abrir no chat — ficam em ai.

seo: {
  og: { enabled: true },
  rss: { enabled: true, types: ["blog", "changelog"] },
  sitemap: true,
  robots: true,
  structuredData: true,
}

Eles funcionam melhor com um deployment.site absoluto, para URLs completas.

Sumário da página

O esquema “nesta página” está ativo por padrão e lista os títulos H2–H3. Desative-o, ou altere o intervalo de títulos, com toc:

export default defineConfig({
  toc: false, // hide it everywhere
});

Ou, em vez disso, restrinja o intervalo de títulos:

export default defineConfig({
  toc: { minHeadingLevel: 2, maxHeadingLevel: 4 },
});

Feedback da página

Cada página de documentação termina com uma avaliação “Esta página foi útil?”. Ela vem ativada por padrão; defina feedback como false para ocultá-la em todo o site:

export default defineConfig({
  feedback: false,
});

A resposta do leitor é enviada como um evento personalizado feedback — com helpful ("yes" ou "no"), path e title — por meio de cada adaptador de analytics configurado que tenha uma API de eventos, e como um evento blume:track em window. O Fathom, o Microsoft Clarity e o Hotjar recebem apenas o nome do evento, sem as propriedades, então eles contam as avaliações, mas não conseguem distinguir um sim de um não. Sem um adaptador de analytics, a resposta não é registrada em lugar nenhum e, com o consentimento de cookies ativado, a avaliação só aparece para os leitores que permitiram analytics, já que a resposta de qualquer outro leitor não chegaria a lugar algum. A pergunta e o texto de agradecimento são strings da interface que você pode traduzir com i18n.ui.

Feedback por escrito

Para ouvir mais do que sim ou não, ative os comentários. Depois de avaliar uma página, o leitor recebe uma caixa para dizer o que funcionou ou o que está faltando:

export default defineConfig({
  feedback: { comments: true },
});

Um comentário é enviado como um evento feedback_comment com os mesmos helpful, path e title da avaliação, além do comment do leitor (até 1.000 caracteres). Ele passa pelos mesmos adaptadores que a avaliação, então leia os comentários onde você lê os eventos. Os provedores limitam o tamanho do valor de uma propriedade, então um comentário longo pode chegar cortado: o Google Analytics mantém 100 caracteres, o Mixpanel, 255 bytes (menos caracteres em um sistema de escrita que usa vários bytes por caractere, como o japonês), e o Vercel Web Analytics aceita valores de até 255 caracteres, enquanto o PostHog e o Segment repassam os comentários inteiros. O Fathom, o Clarity e o Hotjar não recebem nenhum texto do comentário. O Plausible agrupa valores idênticos em vez de listar cada comentário, então ele serve melhor para avaliações do que para comentários. Os leitores podem escrever qualquer coisa na caixa, então trate os comentários como algo que pode conter dados pessoais.

O rótulo e o botão da caixa também são strings da interface (feedback.comment e feedback.send).

Opções de funcionalidades

Cada uma delas tem seu próprio guia. O campo de configuração é o ponto de entrada:

Precedência

As configurações são resolvidas da prioridade mais baixa para a mais alta, então você só precisa substituir o que quiser: