Changelogs

Escreva as notas de lançamento como arquivos de conteúdo normais ou obtenha-as do GitHub Releases, e o Blume constrói automaticamente uma página de cronologia e um feed RSS.

O Blume traz um changelog pronto para usar. Escreva cada versão como um arquivo de conteúdo normal, marque com type: changelog, e o Blume reúne todas as entradas em uma página de índice gerada e em um feed RSS — sem layout para construir, sem lista para manter. Ou dispense os arquivos por completo e alimente seu changelog a partir do GitHub Releases.

Escrever uma entrada

Uma entrada de changelog é uma página .md ou .mdx normal com type: changelog no frontmatter. Por convenção elas ficam em changelog/, mas o que importa é o tipo — não a pasta:

---
title: v1.2.0
type: changelog
date: 2026-06-20
changelog:
  version: 1.2.0
  category: Features
---

A big batch of components landed this release — columns, frames, trees, and tooltips, plus code groups that render as proper language tabs.

- New `Accordion`, `Expandable`, and `Tooltip` components
- `CodeGroup` tabs with flush code blocks

Atribua uma date a cada entrada para que o índice e o feed ordenem da mais recente para a mais antiga. Uma data YAML sem aspas serve — o Blume normaliza.

O objeto changelog

O objeto opcional changelog adiciona metadados mais ricos para o índice e o feed:

A página de índice

Assim que você tiver pelo menos uma entrada type: changelog, o Blume gera automaticamente uma página /changelog. É um índice focado e de largura total — sem barra lateral nem sumário — que lista cada versão em uma linha, da mais recente para a mais antiga e agrupadas por ano, para que um histórico longo continue sendo uma página curta (bem abaixo do tamanho que um agente consegue ler em uma única janela de contexto):

• O título da entrada é o rótulo da linha — ou v{version} quando não há título. Ele leva à página da própria entrada, que é onde as notas de lançamento são exibidas por completo.
• A category é exibida como uma tag ao lado do título, para que o leitor distinga de relance uma versão de uma pré-versão, ou novos recursos de correções.
• A data segue o dateFormat configurado, sem o ano que o grupo da linha já mostra.
• Os rascunhos e as entradas com sidebar.hidden são ignorados.

A página tem o título Changelog (em inglês), com uma descrição de uma linha logo abaixo. Defina os seus com changelog na sua configuração; eles também viram o <title> da página, a meta description e o card OG, além do topo do espelho em Markdown dela em /changelog.md:

changelog: {
  title: "Release notes",
  description: "Every Acme SDK release, newest first.",
},

Cada um também aceita um mapa de código de idioma para texto, como um rótulo de aba do cabeçalho. O índice é renderizado no idioma padrão, então mostra a entrada desse idioma. Se você deixar algum deles sem definir, ele mantém o texto integrado, que pode ser substituído por uma sobrescrita de strings da interface (changelog.title e changelog.description em i18n.ui).

A página só aparece quando nada já ocupa a rota /changelog.

Escrever seu próprio índice

Para colocar algo acima da lista — uma introdução, um link para o feed, uma nota sobre a frequência dos seus lançamentos — escreva a página você mesmo e coloque <Changelog /> onde a lista deve ficar. O Blume continua cuidando da lista, então você só escreve as partes para as quais ele não tem espaço:

---
title: Changelog
description: Every Acme SDK release, newest first.
mode: center
---

Every release, newest first. Subscribe to the [RSS feed](/changelog/rss.xml) to follow along.

<Changelog />

Uma página de conteúdo em /changelog assume a rota, então a página gerada sai de cena e a sua é renderizada no lugar. Coloque-a em changelog/index.mdx, ao lado das suas entradas, para que o grupo Changelog da barra lateral leve até ela — um changelog.mdx ao lado da pasta adiciona um segundo item Changelog à barra lateral. O mode: center dá a ela o layout da página gerada — sem barra lateral, sem sumário, com uma coluna centralizada mais larga — e a página gerada renderiza o mesmo componente, então as duas não têm como ficar diferentes. A lista é convertida para Markdown nas superfícies para agentes (/changelog.md, llms-full.txt, get_page do MCP, busca) exatamente como a da página gerada.

A lista sempre mostra as entradas do idioma padrão, onde quer que a tag esteja — a regra que todas as superfícies que a publicam já seguem, para que uma página traduzida liste as mesmas versões em vez de divergir sobre quais existem. As datas dela aparecem no idioma da própria página.

Substituir a página por completo

Para um design que o componente não consegue expressar, adicione uma página personalizada em pages/changelog.astro — ela assume o controle e o Blume para de gerar o índice padrão. O componente <Update>, com o qual a cronologia anterior era construída, continua disponível para uma página personalizada que queira as notas de lançamento embutidas. Ele não faz parte dos componentes MDX, então importe-o na própria página .astro: import Update from "blume/components/content/Update.astro";.

Construir a lista você mesmo significa reproduzir o que o <Changelog /> faz, inclusive uma coisa que falha em silêncio: as entradas de uma fonte que não é o sistema de arquivos (como o GitHub Releases) são renderizadas por uma coleção staged paralela, então uma página que lê apenas getCollection("docs") não lista nenhuma delas, sem nenhum aviso. Prefira o <Changelog /> em uma página de conteúdo, a menos que você realmente precise de uma marcação diferente.

A partir do GitHub Releases

Em vez de escrever as entradas à mão, aponte a fonte githubReleases() integrada para um repositório e cada versão vira uma entrada type: changelog — a mesma cronologia e o mesmo feed, alimentados diretamente pelas versões que você já publica. O próprio changelog do Blume é construído assim:

import { filesystem, githubReleases } from "blume/sources";

content: {
  sources: [
    filesystem({ root: "content" }),
    githubReleases({
      prefix: "changelog",
      owner: "acme",
      repo: "sdk",
    }),
  ],
}

O nome da versão vira o título, a tag dela vira changelog.version e a respectiva data de publicação ordena a cronologia. Cada página de versão também recebe uma meta description única, resumida a partir das notas — sem markdown, sem títulos de seção nem prefixos de hash de commit dos changesets, cortada para o comprimento de trecho de busca que o blume audit verifica — em vez de recorrer à descrição do site. Um repositório privado se autentica com a variável de ambiente GITHUB_TOKEN. Veja GitHub Releases para todas as opções.

Manter as entradas fora da barra lateral

As entradas do changelog são páginas normais, então a barra lateral gerada as lista como qualquer outra: uma pasta changelog/, ou uma fonte githubReleases() com prefix: "changelog", vira um grupo Changelog, com a entrada mais recente primeiro, que cresce a cada versão. Os links de anterior/próxima também passam por ele, então a última página da documentação pode levar à versão mais recente.

Para manter as entradas fora da barra lateral da documentação, vincule o changelog com uma aba do cabeçalho em vez de uma ação do cabeçalho:

navigation: {
  tabs: [
    { label: "Docs", path: "/" },
    { label: "Changelog", path: "/changelog" },
  ],
}

A aba /changelog abre o índice, sem precisar de href, e fica responsável pela seção changelog/: as páginas fora dela deixam de listar as versões, e os links de anterior/próxima delas continuam entre as páginas da documentação. A página da própria entrada mostra a lista de versões como barra lateral. O índice, o feed RSS, o llms.txt, o sitemap e a busca continuam listando todas as entradas. O path da aba precisa corresponder à pasta ou ao prefix em que as entradas ficam. A aba Docs em / é opcional; ela dá aos leitores uma aba para onde voltar.

Definir sidebar.hidden nas entradas não faz isso: elas deixam de ser listadas em todo lugar, inclusive no índice e no feed.

O feed RSS

O Blume também constrói um feed do changelog em /changelog/rss.xml, ordenado por date da mais recente para a mais antiga. Os feeds precisam de uma URL absoluta do site, então defina deployment.site; o Blume então injeta uma tag <link rel="alternate"> em todas as páginas para que os leitores o descubram automaticamente.

O feed vem ativado por padrão. Ajuste em seo.rss:

seo: {
  rss: {
    enabled: true,
    types: ["blog", "changelog"],
    limit: 50,
  },
}

Remova "changelog" de rss.types para dispensar o feed mantendo a cronologia.

Dados estruturados

Quando os dados estruturados estão ativos, cada entrada do changelog é emitida como um TechArticle do schema.org com a descrição e a data de publicação dela, para que os mecanismos de busca possam indexar as versões como artigos datados.