Páginas

Como os arquivos na sua pasta de conteúdo se tornam páginas, e como organizá-los e nomeá-los para que o roteamento e a navegação sejam inferidos automaticamente.

Sua documentação é apenas uma pasta de arquivos Markdown e MDX. O Blume transforma cada arquivo numa página — roteamento, navegação e metadados são inferidos a partir do sistema de arquivos, então não existe nenhum manifesto para manter sincronizado.

O conteúdo fica na sua raiz de conteúdo (docs/ por padrão; mude isso com content.root no blume.config.ts).

Markdown e MDX

O Blume renderiza dois tipos de arquivo:

• .md — Markdown para prosa simples: GFM, frontmatter, pontuação inteligente e sobrescrito/subscrito.
• .mdx — tudo o que o .md tem, mais componentes e as diretivas, instalações de pacotes e matemática exclusivas do MDX.

Opte pelo .md quando uma página for só prosa, e pelo .mdx quando ela precisar de componentes ou diretivas. Trocar é tão simples quanto renomear o arquivo.

No .mdx, { inicia uma expressão JavaScript e < inicia uma tag JSX, então um texto que funciona bem no .md pode quebrar uma página: uma chave literal, um comentário HTML (escreva {/* … */}) ou um elemento deixado aberto (escreva <br />). O Blume analisa todas as páginas .mdx quando lê o projeto, então o blume dev, o blume validate, o blume doctor e o blume check reportam uma página que não pode ser analisada como BLUME_MDX_SYNTAX, um erro na linha e na coluna em que o MDX parou, e o blume build para ali antes de compilar qualquer coisa. Com --no-strict, o build deixa a página de fora e gera o resto do site. O blume dev mantém a página, e abrir ela mostra o erro.

Uma expressão pode ser analisada sem problemas e ainda assim falhar quando a página é renderizada, como {user.name} numa página em que nada define user. O blume build reporta isso como BLUME_MDX_UNDEFINED_NAME na linha da expressão, na página ou no partial que contém ela. Para mostrar chaves como texto, escape cada chave de abertura (\{) ou coloque o texto em código inline. Para um valor que todas as páginas compartilham, defina uma variável.

Arquivos e rotas

Cada arquivo corresponde a uma rota pelo seu caminho na raiz de conteúdo:

Pastas aninhadas se tornam rotas aninhadas, e um index.mdx dentro de uma pasta se torna a página da própria pasta.

Caracteres que quebrariam a URL de uma página — #, ?, % e : — são removidos da rota dela, então 100%.mdx é publicado em /100. Não use # nem ? em nomes de arquivos e pastas: o carregador de conteúdo do Astro não consegue ler um arquivo assim, então o Blume reporta isso como um erro e deixa o arquivo de fora do site. Renomeie sdks/c#.mdx para sdks/c.mdx e ele é publicado em /sdks/c, a mesma rota que ele teria de qualquer forma depois que os caracteres fossem removidos.

Ordenação com prefixos numéricos

Prefixe um arquivo ou pasta com um número e um -, _ ou . para controlar a ordem dele na barra lateral. O prefixo é removido da URL, então você pode reordenar páginas sem quebrar links:

01-introduction.mdx  ->  /introduction
02-installation.mdx  ->  /installation

Uma versão ou uma data no início de um nome faz parte do nome, e não indica uma ordem: 1.2.0.mdx vira a rota /1.2.0, e 2024-01-05-launch.mdx vira /2024-01-05-launch. O Blume lê estes formatos como datas:

• Uma data ISO, YYYY-MM-DD: 2024-01-05.mdx vira a rota /2024-01-05.
• Um dia ou um mês primeiro e depois um ano de quatro dígitos, D-M-YYYY ou M-D-YYYY, com um ou dois dígitos para o dia e o mês: 12-05-2022.mdx vira a rota /12-05-2022.
• Um ano e um mês, YYYY-MM: 2024-01.mdx vira a rota /2024-01.

Uma data encerra o nome ou vem seguida de um -, _ ou . e do resto do nome (2024-01-recap.mdx). Versões anteriores do Blume liam o primeiro número das duas últimas formas como um prefixo de ordenação, então 12-05-2022.mdx era publicado em /05-2022 e 2024-01.mdx em /01. Essas URLs antigas agora redirecionam para as novas, a menos que outra página já esteja nelas. Só nomes de arquivos e pastas perdem o prefixo (as notas de um vault do Obsidian contam como arquivos). Um slug definido no frontmatter e uma página vinda de uma fonte de conteúdo, como um CMS ou o GitHub Releases, mantêm o nome que receberam.

A ordenação tem várias camadas — veja Navegação para as regras completas de precedência.

Pastas de agrupamento

Coloque o nome de uma pasta entre parênteses para agrupar as páginas dela na barra lateral sem adicionar um segmento à URL:

docs/(internal)/security.mdx  ->  /security

As páginas compartilham um grupo “Internal” na barra lateral, mas mantêm URLs planas e sem parênteses. Uma pasta de agrupamento aceita um prefixo numérico como qualquer outra pasta, dentro ou fora dos parênteses: (01-internal) e 01-(internal) aparecem primeiro na ordenação e geram a mesma rota que (internal).

Rascunhos

Marque uma página como rascunho para mantê-la fora dos builds de produção e ainda assim visualizá-la no blume dev:

---
title: Work in progress
draft: true
---

O blume build ignora rascunhos; o blume dev renderiza eles para que você possa trabalhar abertamente.

Tipos de conteúdo

Toda página tem um tipo, definido com o campo de frontmatter type (padrão doc). Os tipos permitem que o Blume trate grupos de páginas de forma diferente — e, mais importante ainda, as páginas blog e changelog são reunidas em feeds.

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

O tipo independe de onde o arquivo fica, mas, por convenção, os posts de blog ficam em blog/ e as entradas do changelog em changelog/. Os dois ganham um feed RSS automaticamente, e as entradas do changelog também são reunidas em uma linha do tempo /changelog gerada. Veja Blog e Changelog para escrever cada um deles.

Feeds

O Blume gera um feed RSS automaticamente para cada tipo de conteúdo listado em seo.rss.types — blog e changelog por padrão — desde que ele tenha pelo menos uma página. Os feeds são servidos em /<type>/rss.xml:

Dê uma date a cada entrada para que os itens sejam ordenados do mais recente para o mais antigo e tenham uma pubDate. Uma data YAML sem aspas funciona — o Blume normaliza ela:

---
title: Introducing Blume
type: blog
date: 2026-06-22
description: Why we built a markdown-first docs framework.
---

Feeds precisam de uma URL absoluta do site, então defina deployment.site. O Blume adiciona tags <link rel="alternate"> em todas as páginas para que navegadores e leitores de feeds descubram elas automaticamente. Veja Blog e Changelog para escrever cada tipo de conteúdo.

Nesta página

Toda página ganha um sumário automático, construído a partir dos seus títulos. Em telas largas, ele fica numa barra lateral fixa ao lado do seu conteúdo; em telas mais estreitas, ele se recolhe num painel Nesta página acima da página. Conforme você rola, a entrada da seção que você está lendo fica destacada, então você sempre sabe onde está numa página longa.

O Blume converte cada título em um slug para criar uma âncora, então cada entrada leva direto para a sua seção — e você pode criar links diretos para qualquer título acrescentando o slug dele à URL (.../my-page#getting-started).

Por padrão, o sumário lista seus títulos ## e ### (H2 e H3); defina toc para mudar o intervalo de títulos ou desativar o sumário. Uma página sem títulos nesse intervalo simplesmente não tem sumário.

Para onde ir agora