MDX remoto

Busque Markdown e MDX via HTTP a partir de um repositório do GitHub ou de uma URL raw com a source mdxRemote(), renderizados com todos os componentes do Blume.

O adapter nativo mdxRemote() busca arquivos .md/.mdx raw via HTTP. Você pode listar os arquivos a partir de uma subárvore de um repositório do GitHub (github) ou informá-los explicitamente em relação a uma URL base raw (url + files):

import { defineConfig } from "blume";
import { filesystem, mdxRemote } from "blume/sources";

export default defineConfig({
  content: {
    sources: [
      filesystem({ root: "docs" }),
      // The docs/ subtree of acme/sdk, mounted under /sdk
      mdxRemote({
        prefix: "sdk",
        github: { owner: "acme", repo: "sdk", ref: "main", path: "docs" },
      }),
    ],
  },
});

Para listar os arquivos você mesmo, aponte url para uma URL base raw:

mdxRemote({
  prefix: "sdk",
  url: "https://raw.githubusercontent.com/acme/sdk/main/docs",
  files: ["intro.mdx", "guide.mdx"],
});

include (padrão ["**/*.{md,mdx}"]) filtra os arquivos pelo caminho deles dentro de path, do mesmo jeito que o include de uma source filesystem(): um padrão que começa com ! exclui os arquivos que correspondem a ele (["**/*.mdx", "!drafts/**"]). Com github, a source lista a árvore inteira do repositório em ref e mantém os arquivos que estão dentro de path. Se não houver nada dentro de path nessa ref, a source não lê nenhuma página e emite o aviso BLUME_SOURCE_PATH_MISSING. O GitHub limita a listagem (100.000 entradas ou 7 MB para o repositório inteiro, seja qual for o path) e, acima desse limite, a source emite o aviso BLUME_SOURCE_TRUNCATED: nesse caso, liste os arquivos com url e files.

Um link relativo entre arquivos remotos ([Errors](./02-errors.mdx)) leva à página em que o arquivo vinculado é publicado, sem o prefixo de ordenação na rota. Isso vale na página renderizada, na cópia em Markdown da página e no llms-full.txt, e no que o assistente lê, e o blume validate verifica esse link da mesma forma.

O token de um repositório privado é lido da variável de ambiente GITHUB_TOKEN. O token nunca é inserido na sua configuração nem no output gerado, e só é enviado para os próprios hosts do GitHub (api.github.com, raw.githubusercontent.com), nunca para uma base url personalizada. Um repositório público funciona sem ele. Com github, o adapter declara essa variável, então o blume dev e o blume build emitem o aviso BLUME_MISSING_SECRET quando ela não está definida: a listagem de arquivos passa pela API do GitHub, que permite 60 requisições não autenticadas por hora. Uma url raw só lê arquivos, então nada é avisado de antemão; quando o GitHub recusa um arquivo com 401, 403 ou 404 enquanto GITHUB_TOKEN não está definida, o aviso do arquivo ignorado informa que a variável não está definida.

Um arquivo escrito para ser lido no GitHub costuma começar com um # Heading, enquanto o Blume renderiza o title da página como o <h1> dela. Quando a primeira linha de uma página remota é um h1 igual ao title do front matter dela, ou quando o front matter não define nenhum title, esse título é removido e o texto dele passa a ser o título da página, de modo que a página mostre um único <h1>. Se o primeiro título for diferente do title, ele é mantido.

As páginas remotas são renderizadas com total fidelidade de MDX e componentes: o conteúdo delas é materializado em um diretório de staging oculto e renderizado pelo Astro junto com a sua documentação local, então callouts, tabs e todos os outros componentes do Blume continuam funcionando.

Como em toda source remota, as páginas buscadas ficam em cache para builds offline e são atualizadas com blume sync. Veja Cache e builds offline.

O guia Monte um único portal de documentação a partir de vários repositórios do GitHub usa essa source para trazer a pasta de documentação de cada repositório para um único site, fixado em uma release que só muda quando você a altera.