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 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 sitemap from "@astrojs/sitemap";
import { defineConfig } from "blume";

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

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

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

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

  // Search — see the Search guide
  search: {
    provider: "orama",
  },

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

  // AI — see the AI guide
  ai: {
    llmsTxt: true,
    // MCP server (needs server output)
    mcp: {
      enabled: false,
      route: "/mcp",
    },
  },

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

  // Deployment — see the Deployment guide
  deployment: {
    output: "static",
    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/).

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.
• 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: "Blume v1 is here!",
  link: { text: "Read more", href: "/blog/v1" },
  dismissible: true,
  id: "v1",
},

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.

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 cabeçalho e as ações de página Editar no GitHub e Enviar feedback:

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 true para derivar a data de cada página do respectivo histórico do git:

lastModified: true,

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. 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" },

SEO

Imagens Open Graph, feeds RSS e dados estruturados JSON-LD, agrupados em seo. Consulte o guia de SEO para metadados, substituições no frontmatter e a referência completa.

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 },
});

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: