--- title: Arquivo de configuração description: >- 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. sidebar: label: blume.config.ts --- 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. ```ts blume.config.ts lineNumbers import { defineConfig } from "blume"; export default defineConfig({ title: "My Docs", description: "Documentation for my project.", }); ``` ## Um exemplo completo [#a-complete-example] Um exemplo mais abrangente que aborda as opções mais comuns (consulte o guia de cada funcionalidade para as demais): ```ts blume.config.ts lineNumbers 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 — llms.txt, MCP, the AI catalog; see the Discoverability section ai: { llmsTxt: true, // AI Catalog / ARD manifest at /.well-known/ai-catalog.json (needs deployment.site) catalog: 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 — see the Deployment guide deployment: { output: "static", site: "https://docs.example.com", }, }); ``` ## Site | Opção | Padrão | Descrição | | --- | --- | --- | | `title` | `"Documentation"` | Nome do site — exibido no cabeçalho, nos títulos das páginas e nos cards OG. | | `description` | — | Meta descrição padrão, usada para SEO e OG. | | `logo` | — | Marca gráfica e/ou logotipo textual exibido no cabeçalho. | | `banner` | — | Barra de anúncios para todo o site, acima do cabeçalho. | ### Logotipo [#logo] 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: ```ts blume.config.ts 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: ```ts blume.config.ts lineNumbers 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 [#apple-touch-icon] 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 `` 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 [#banner] 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: ```ts blume.config.ts banner: "Docs are in beta — expect changes.", ``` ```ts blume.config.ts lineNumbers 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 [#content] Onde seu conteúdo fica e como o Blume o descobre. Consulte [Páginas](/docs/content) para saber como os arquivos viram rotas. ```ts blume.config.ts lineNumbers content: { root: "docs", } ``` | Opção | Padrão | Descrição | | --- | --- | --- | | `root` | `"docs"` | Pasta que o Blume analisa em busca de conteúdo. | | `include` | `["**/*.{md,mdx}"]` | Globs que correspondem a arquivos de conteúdo. | | `exclude` | `["**/_*", "**/.*"]` | Globs a ignorar (arquivos com underscore e com ponto). | | `pages` | `"pages"` | Pasta para páginas `.astro` personalizadas. | | `defaultType` | `"doc"` | `type` de página usado quando o frontmatter o omite. | | `types` | `{}` | Definições de conteúdo por tipo — chaves de frontmatter personalizadas restritas às páginas de um `type`. Consulte [Frontmatter](#frontmatter). | 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](/docs/content/syntax#links-and-images). ## Imagens [#images] 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](/docs/content/syntax#links-and-images) 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: ```ts blume.config.ts lineNumbers image: { domains: ["cdn.example.com"], remotePatterns: [{ protocol: "https", hostname: "**.example.com" }], } ``` | Opção | Padrão | Descrição | | --- | --- | --- | | `domains` | `[]` | Nomes de host cujas imagens remotas podem ser otimizadas. | | `remotePatterns` | `[]` | Autorização baseada em padrões (`protocol`, `hostname`, `port`, `pathname`); os nomes de host aceitam os wildcards `*.` (um nível) e `**.` (qualquer profundidade). | ## 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: ```ts blume.config.ts lineNumbers 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](https://standardschema.dev) — 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](/docs/reference/frontmatter#custom-keys) 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`: ```ts blume.config.ts lineNumbers 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](/docs/reference/frontmatter#per-type-keys) 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](/docs/discoverability/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](/docs/content/navigation#repository-link) no cabeçalho e as [ações de página](/docs/content/navigation#page-actions) **Editar no GitHub** e **Enviar feedback**: ```ts blume.config.ts lineNumbers github: { owner: "acme", repo: "docs", } ``` | Opção | Padrão | Descrição | | --- | --- | --- | | `owner` | — | Conta ou organização do GitHub dona do repositório. | | `repo` | — | Nome do repositório. | | `branch` | `"main"` | Branch para onde os links de edição apontam. | | `dir` | — | Caminho da raiz do repositório até a raiz do projeto (para monorepos). | | `host` | `"https://github.com"` | Origem da instância do GitHub, para instalações Enterprise. Precisa ser HTTP(S); normalizada para sua origem. | | `api` | derivado de `host` | Base da API REST, para o `` em uma instância Enterprise. Precisa ser HTTP(S); normalizada para uma origem e um caminho. | ### 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: ```ts blume.config.ts lineNumbers github: { host: "https://github.acme.com", owner: "acme", repo: "docs", } ``` A base da API REST que o [``](/docs/content/components) 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. :::warning Uma instância acessível apenas por HTTP simples ainda renderiza suas contagens, mas o `GITHUB_TOKEN` é omitido da requisição em vez de ser enviado em texto puro — então o card de um repositório privado volta sem elas. ::: :::note `host` cobre os links que o Blume deriva de `github`. Para apontar só a marca do cabeçalho para outro lugar — uma organização, digamos, quando o próprio repositório das docs é privado — use [`navigation.repo`](/docs/content/navigation#repository-link) com uma URL absoluta. ::: ## Última modificação [#last-modified] 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: ```ts blume.config.ts lastModified: true, ``` | Valor | Descrição | | --- | --- | | `false` | Desativado (padrão). | | `true` | Lê a data do histórico do git (datas dos commits). | | `{ type: "git" }` | O mesmo que `true`, escrito explicitamente. | | `{ type: "frontmatter" }` | Nunca executa o git — usa apenas o campo `lastModified` do frontmatter. | 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: ```mdx page.mdx --- 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 [#date-format] Tanto a marca de "Última atualização" quanto a linha do tempo do [changelog](/docs/advanced/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日`): ```ts blume.config.ts dateFormat: { dateStyle: "long" }, ``` `dateFormat` é repassado diretamente para as opções de [`Intl.DateTimeFormat`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl/DateTimeFormat/DateTimeFormat). Use um preset `dateStyle` para escolher um comprimento: ```ts blume.config.ts dateFormat: { dateStyle: "medium" }, ``` Ou os campos de componentes individuais para um estilo numérico próprio como `2026/07/21`: ```ts blume.config.ts dateFormat: { year: "numeric", month: "2-digit", day: "2-digit" }, ``` | Opção | Descrição | | --- | --- | | `dateStyle` | Comprimento predefinido: `"full"`, `"long"`, `"medium"` ou `"short"`. Não pode ser combinado com os campos de componentes. | | `weekday`, `era`, `year`, `month`, `day` | Componentes individuais, p. ex. `year: "numeric"`, `month: "2-digit"`. | | `timeZone` | Fuso horário IANA. Por padrão é `UTC`, para que uma data seja lida da mesma forma independentemente de onde o site é buildado. | | `calendar`, `numberingSystem` | Sistema de calendário (p. ex. `"japanese"`) e sistema de numeração (p. ex. `"arab"`). | ## SEO e IA [#seo-and-ai] 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 e o servidor MCP ficam em `ai`. Os dois são abordados página a página na seção [Descoberta](/docs/discoverability), que trata os buscadores e os agentes de IA como dois públicos da mesma camada legível por máquina. ```ts blume.config.ts lineNumbers seo: { og: { enabled: true }, rss: { enabled: true, types: ["blog", "changelog"] }, sitemap: true, robots: true, structuredData: true, } ``` | Opção | Padrão | Descrição | | --- | --- | --- | | `og.enabled` | automático | Imagens Open Graph por página — ativas quando uma URL do site está definida. | | `rss.enabled` | `true` | Cria feeds para conteúdos de blog e de changelog. | | `rss.types` | `["blog", "changelog"]` | Tipos de conteúdo que recebem cada um um feed. | | `rss.limit` | `50` | Número máximo de itens por feed. | | `sitemap` | `true` | Gera o sitemap.xml (precisa de deployment.site). | | `robots` | `true` | Gera o robots.txt com um link para o Sitemap. | | `structuredData` | `true` | Emite JSON-LD do schema.org no head de cada página. | Eles funcionam melhor com um [`deployment.site`](/docs/deployment) absoluto, para URLs completas. ## Sumário da página [#table-of-contents] 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`: ```ts blume.config.ts export default defineConfig({ toc: false, // hide it everywhere }); ``` Ou, em vez disso, restrinja o intervalo de títulos: ```ts blume.config.ts export default defineConfig({ toc: { minHeadingLevel: 2, maxHeadingLevel: 4 }, }); ``` ## Opções de funcionalidades [#feature-options] Cada uma delas tem seu próprio guia. O campo de configuração é o ponto de entrada: | Campo | O que configura | Guia | | --- | --- | --- | | `theme` | Cor de destaque, raio dos cantos, fontes, modo claro/escuro | [Temas](/docs/configuration/theming) | | `navigation` | Barra lateral explícita e abas do cabeçalho | [Navegação](/docs/content/navigation) | | `search` | Provedor (Orama, Pagefind, Algolia, entre outros) e indexação | [Busca](/docs/configuration/search) | | `markdown` | Opções de renderização de Markdown — blocos de código, âncoras de títulos, zoom em imagens | [Sintaxe](/docs/content/syntax) | | `ai` | `llms.txt`, espelhos em Markdown, a API JSON e o servidor MCP hospedado para agentes de programação | [SEO e AEO](/docs/discoverability) | | `ai.ask` | O assistente Ask AI dentro da página | [Ask AI](/docs/configuration/ask-ai) | | `analytics` | Vercel, PostHog e scripts personalizados | [Analytics](/docs/configuration/analytics) | | `seo` | Metadados, imagens OG, feeds, dados estruturados, sitemap, robots | [SEO e AEO](/docs/discoverability) | | `deployment` | Modo de saída, adaptador e URL do site | [Deploy](/docs/deployment) | | `redirects` | Redirecionamentos permanentes e temporários | [Deploy](/docs/deployment#redirects) | | `integrations` | Integrações do Astro adicionadas depois das integradas do Blume | [Personalização](/docs/configuration/customization#astro-integrations) | ## Precedência [#precedence] As configurações são resolvidas da prioridade mais baixa para a mais alta, então você só precisa substituir o que quiser: 1. **Padrões do Blume** Um valor padrão sensato para cada campo. 2. **blume.config.ts** A configuração de todo o seu projeto. 3. **Meta da pasta** [`meta.ts`](/docs/content/meta) para o título e a ordenação de uma seção. 4. **Frontmatter da página** As substituições por página prevalecem.