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.

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.

Ordenação com prefixos numéricos

Prefixe um arquivo ou pasta com um número 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

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.

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 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).

O sumário lista seus títulos ## e ### (H2 e H3). Uma página sem títulos nesse nível simplesmente não tem sumário.

Para onde ir agora