--- title: Versionamento description: >- Congele snapshots dos seus docs por release com um seletor de versões, SEO canônico para a versão mais recente, busca com escopo por versão e uma superfície de agentes que entende versões. --- O Blume versiona seus docs do jeito que os releases funcionam de verdade: a documentação mais recente fica na raiz do seu conteúdo, com URLs limpas e sem prefixo, e cada versão passada é um snapshot congelado na própria pasta. Crie um snapshot quando você lançar, e o Blume monta o seletor, o aviso de "versão antiga", o escopo da busca, o SEO e a superfície de agentes pra você. É opcional: sem um bloco `versions`, nada muda. ## Habilite Adicione um bloco `versions` nomeando os docs atuais e quaisquer snapshots arquivados: ```ts blume.config.ts lineNumbers versions: { current: { label: "v2.0", badge: "Latest" }, archived: [ { id: "v1.0" }, { id: "v0.9", label: "0.9 (legacy)" }, ], } ``` `current` rotula a árvore sem prefixo no seletor (com um `badge` opcional). O `id` de cada entrada arquivada é ao mesmo tempo o nome do diretório do snapshot e o segmento da URL — os ids precisam começar com uma letra (`v1.0`, não `1.0`) para que nunca colidam com [prefixos numéricos de ordenação](/docs/content/navigation#ordering). Liste as versões arquivadas da mais nova para a mais antiga; essa é a ordem do seletor. ## Crie uma versão Quando você lançar, congele os docs atuais com um comando: ```bash blume version v1.0 ``` Isso copia sua árvore de conteúdo para `docs/v1.0/` (snapshots existentes são excluídos), reescreve os links absolutos a partir da raiz dentro da cópia para que continuem dentro do snapshot (`/guides/x` vira `/v1.0/guides/x`, com código em blocos e inline intocados) e registra o id em `blume.config.ts` — ou imprime a entrada para você colar, quando seu config estiver estruturado de um jeito que ele não vai mexer. Links para páginas que não fazem parte da árvore copiada — referências de API geradas, fontes remotas como um changelog — continuam apontando para as páginas vivas, já que o snapshot não tem cópia delas. Rode `blume version` sem id para listar as versões configuradas. Revise e commite o novo diretório como qualquer outro conteúdo. Reinicie o `blume dev` para que ele seja reconhecido. ```txt docs/ index.mdx -> / (latest) guides/quickstart.mdx -> /guides/quickstart v1.0/ index.mdx -> /v1.0 (frozen) guides/quickstart.mdx -> /v1.0/guides/quickstart ``` **Arquivado significa congelado.** As edições futuras pertencem à árvore viva; um snapshot são os docs como eles eram. O Blume se apoia nisso: snapshots mantêm os próprios metadados de pasta e traduções, o [`blume translate`](/docs/reference/translate) nunca os retraduz, e uma sidebar explícita configurada se aplica só aos docs atuais — a sidebar de um snapshot sempre vem dos arquivos dele. ## O seletor e o aviso Com as versões configuradas, o cabeçalho ganha um dropdown de versão automaticamente. Ao trocar, você cai na mesma página da versão de destino quando ela existe, e na raiz daquela versão quando não existe (defina `switcher.redirect: "root"` para sempre cair na raiz). Se você declarar seu próprio seletor `kind: "version"` em [`navigation.selectors`](/docs/content/navigation#selectors), ele substitui o automático. Toda página arquivada também mostra um aviso não dispensável com um link "Ir para a mais recente" apontando para o equivalente vivo da página. Personalize ou desative por versão: ```ts blume.config.ts archived: [ { id: "v1.0", banner: "These docs cover the 1.x SDK." }, { id: "v0.9", banner: false }, ]; ``` ## SEO Docs antigos são a armadilha favorita dos mecanismos de busca: a página desatualizada supera a viva no ranking, ou as duas competem. O Blume usa como padrão a resposta que os guias de SEO recomendam e que nenhum outro framework de docs automatiza — páginas arquivadas continuam indexáveis, mas declaram o **equivalente mais recente como seu canônico**, então a página viva é a autoritativa enquanto o conteúdo exclusivo daquela versão (uma página que não existe mais nos docs mais recentes) continua localizável com um canônico apontando para si mesma. Por versão, você pode escolher um tratamento diferente: ```ts blume.config.ts archived: [ { id: "v1.0" }, // canonical → latest (default) { id: "v0.9", canonical: "self" }, // every page authoritative { id: "v0.8", noindex: true }, // deindexed entirely ]; ``` O sitemap segue a mesma lógica: páginas arquivadas cujo canônico aponta para um equivalente vivo ficam de fora, versões com `noindex` ficam de fora por completo, e páginas exclusivas de uma versão continuam listadas. O frontmatter `seo.canonical` da própria página sempre vence. ## Busca O diálogo de busca limita os resultados à versão que está sendo vista, com um alternador "Todas as versões" (lembrado por leitor) ao lado do de idioma. Resultados de outras versões mostram a versão deles na linha do resultado. Orama (o padrão), FlexSearch, Algolia e Typesense todos respeitam esse escopo — os registros hospedados carregam uma faceta `version`, com os docs atuais enviados como `"current"` — enquanto o Pagefind fica sem escopo, coerente com o comportamento dele para locales. ## Agentes A superfície de agentes entende versões — algo que nenhum outro framework de docs faz: - As ferramentas MCP `search_docs` e `list_pages` usam os docs atuais por padrão e aceitam `version`: um id arquivado (`"v1.0"`) ou `"all"`. O `get_navigation` retorna a árvore de um snapshot arquivado quando solicitado. - O `llms.txt` coloca as versões arquivadas depois dos docs atuais, rotuladas como `1.0 (archived)`, para que um agente lendo o índice saiba quais docs estão congelados. - O `llms-full.txt` continua somente com a versão atual — o dump plano nunca intercala cópias congeladas da mesma página. - Espelhos em Markdown puro (URLs `.md`) existem para as páginas de todas as versões, como para qualquer rota. ## Com i18n O versionamento se combina com a [internacionalização](/docs/content/i18n). No disco, a pasta da versão é a mais externa — um snapshot naturalmente contém as pastas de locale dele — enquanto nas URLs o locale continua sendo o mais externo, igual ao resto do site: ```txt docs/ guides/x.mdx -> /guides/x fr/guides/x.mdx -> /fr/guides/x v1.0/ guides/x.mdx -> /v1.0/guides/x fr/guides/x.mdx -> /fr/v1.0/guides/x ``` O fallback de locale funciona dentro de cada versão: uma página de snapshot não traduzida renderiza o conteúdo do locale de fallback na URL localizada, e as alternativas `hreflang` se agrupam por versão. Um id de versão não pode colidir com um código de locale configurado — o Blume rejeita essa configuração de cara. ## O que fica sem versionamento O versionamento cobre a árvore de conteúdo dos docs. O blog, o changelog, as referências de API geradas a partir de specs OpenAPI e as páginas customizadas são sempre a versão atual. Mais dois comportamentos que vale conhecer: as abas do cabeçalho são definidas em relação aos docs atuais, então dentro de uma árvore arquivada a sidebar é renderizada sem escopo por abas; e sites grandes devem notar que cada snapshot é uma cópia completa — conteúdo, entradas do índice de busca e dados de navegação crescem a cada versão.