Includes
Reutilize conteúdo entre páginas — insira arquivos Markdown, MDX ou de código compartilhados em qualquer página com a sintaxe de include.
Escreva um trecho uma vez e insira ele em qualquer página. Uma instrução <include> em sua própria linha embute outro arquivo no momento do build, como se o conteúdo estivesse escrito ali mesmo — os títulos entram no sumário da página, o texto é indexado pela busca, e o conteúdo aparece no espelho .md da página e no llms-full.txt. Uma instrução que um formatador quebre em várias linhas continua sendo inserida, e uma que o Blume não consiga interpretar gera um aviso BLUME_INCLUDE_MALFORMED na linha dela, em vez de ser renderizada como uma tag bruta.
<include>./_snippets/prerequisites.mdx</include>O caminho é resolvido em relação ao arquivo que faz o include. Caminhos que começam com / são resolvidos a partir da raiz do seu conteúdo, então páginas em níveis profundos podem referenciar trechos compartilhados sem cadeias de ../../..:
<include>/_snippets/prerequisites.mdx</include>A sintaxe é igual à do Fumadocs, então conteúdo migrado funciona sem alterações.
Veja funcionando na prática — este próximo destaque vem de um trecho compartilhado:
Parciais
Qualquer arquivo cujo nome (ou pasta) comece com underscore fica excluído do roteamento, da navegação, da busca e dos sitemaps — essa convenção é o lar natural dos trechos compartilhados. Os padrões que você adicionar em content.exclude se somam a essa regra em vez de substituí-la; para publicar arquivos com underscore mesmo assim, adicione "!**/_*" ao exclude:
docs/
_snippets/
prerequisites.mdx
cli-flags.md
guides/
quickstart.mdx ← <include>../_snippets/prerequisites.mdx</include>
index.mdxUma parcial é um arquivo Markdown ou MDX normal. O front matter dela é removido na inserção (o front matter da página que faz o include prevalece), e todo o resto — destaques, blocos de código, componentes, fórmulas matemáticas — é renderizado exatamente como seria inline. Parciais podem incluir outras parciais; um include circular é reportado como erro.
Definições de referência de links ([pep 508]: https://peps.python.org/pep-0508/) também atravessam includes, então uma parcial pode guardar as definições de links compartilhadas de um site: a página e as demais parciais dela podem citar as definições de uma parcial ([PEP 508]), e uma parcial pode citar as da página. Quando a página e uma parcial definem o mesmo rótulo, cada uma usa a sua.
Referências relativas a imagens dentro de uma parcial continuam funcionando: elas são rebaseadas para a página que faz o include, então um  ou <Card img="./cover.png"> colocado ao lado da parcial é resolvido onde quer que a parcial seja inserida. O caminho de uma imagem é rebaseado em qualquer forma em que esteja escrito: entre colchetes angulares (), com parênteses escapados ou seguido de um título com qualquer um dos tipos de aspas. Um link para outro arquivo ao lado da parcial ([spec](./spec.pdf), ou um <img src> ou <a href> que aponte para um) também acompanha a parcial. Um link para uma página é resolvido a partir da página que faz o include, como se tivesse sido escrito ali.
Editar uma parcial enquanto o blume dev está rodando recarrega todas as páginas que a incluem.
Props
Passe valores para uma parcial como atributos e leia eles na parcial com {{name}}, a mesma sintaxe das variáveis. Assim, uma única parcial atende todas as páginas que precisam de uma variação dela:
Upgrade to the **{{plan}}** plan to use {{feature}}.<include plan="Enterprise" feature="SSO">
./_snippets/upgrade.mdx
</include>Uma prop vale para o arquivo incluído e para tudo o que ele incluir, e tem precedência sobre uma variável global do site com o mesmo nome. Todo atributo, exceto lang e meta, é uma prop; os nomes dos atributos ficam em minúsculas, e os valores são texto puro entre aspas. Props só chegam a parciais Markdown e MDX: um {{name}} em um arquivo de código incluído não é substituído por uma prop.
Incluindo arquivos de código
Um alvo que não seja .md/.mdx é embutido como um bloco de código cercado, com a linguagem inferida da extensão. Use lang para sobrescrever a linguagem (ou para mostrar um arquivo Markdown como código-fonte em vez de inseri-lo), e meta para passar uma string de meta da cerca, como um título:
<include>./examples/config.ts</include>
<include meta='title="config.ts"'>./examples/config.ts</include>
<include lang="mdx">./_snippets/prerequisites.mdx</include>Regras e diagnósticos
Instruções de include precisam ocupar a própria linha — elas são de nível de bloco, não inline. Instruções dentro de blocos de código cercados são ignoradas, então você pode documentar a própria sintaxe (como esta página faz).
Os alvos precisam estar dentro da raiz do seu conteúdo: um arquivo fora dela ficaria silenciosamente ausente dos snapshots de versão e de projetos ejetados, então o blume reporta BLUME_INCLUDE_OUTSIDE_ROOT em vez de inseri-lo. Um alvo que não existe gera BLUME_INCLUDE_NOT_FOUND, e um laço de includes gera BLUME_INCLUDE_CYCLE — os três fazem o blume build falhar (passe --no-strict para buildar mesmo assim) e aparecem no blume validate.
Links quebrados dentro de uma parcial são reportados no arquivo da parcial, não nas páginas que a inserem, então você corrige onde eles realmente vivem.
Uma parcial é lida no formato da página que faz o include, então uma parcial .md incluída por uma página .mdx é lida como MDX. O MDX não tem comentários HTML, então os comentários <!-- … --> da parcial são inseridos como comentários MDX ({/* … */}) e continuam ocultos. O restante do HTML ali precisa ser JSX válido: um <img …> ou <br> sem a barra de fechamento engole tudo o que vem depois dele na parcial, sem nenhum erro. O Blume avisa sobre isso com BLUME_MDX_UNCLOSED_ELEMENT na linha da parcial; feche a tag como <br />. Qualquer outra coisa na parcial que o MDX não consiga interpretar depois de inserida, como um { solto, gera um aviso BLUME_MDX_SYNTAX na linha da parcial, e quando isso faz o build falhar, o build também reporta o erro ali, e não na página que faz o include.