Notion

Importe um banco de dados do Notion com a fonte notion() — as linhas viram páginas, as propriedades viram frontmatter e os blocos viram componentes do Blume.

O adaptador notion() embutido transforma um banco de dados do Notion em uma coleção: cada linha vira uma página, as propriedades dela viram frontmatter e a árvore de blocos vira MDX. Callouts, toggles, colunas e blocos de código são mapeados para os componentes correspondentes do Blume, e o texto que você digita no Notion é renderizado exatamente como foi escrito: um caractere {, < ou de Markdown em uma página é escapado em vez de ser interpretado como MDX, JSX ou formatação, a menos que você ative o MDX. Blocos de vídeo viram um embed <YouTube> quando contêm um link do YouTube e um player <video> nos outros casos, e a legenda do bloco vira a legenda do <Frame> nos dois casos. Um link para uma página de vídeo em vez de um arquivo de mídia (uma URL do Vimeo ou do Loom, por exemplo) gera um aviso de build, e o player <video> dele continua apontando para a página, que ele não consegue reproduzir. Nesse caso, coloque um link para o vídeo no texto. O adaptador declara @notionhq/client (v5 ou posterior) como dependência de runtime, na forma de uma peer dependency opcional; o Blume lê o banco de dados pela primeira fonte de dados dele.

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

export default defineConfig({
  content: {
    sources: [
      filesystem({ root: "docs" }),
      notion({
        prefix: "handbook",
        database: "8f2c1e0a4b7d4f3c9e6a5d2b1c0f9e8d", // the id in the database URL
        // Property names default to the title-typed prop / Description / Slug / Order / Status
        // Pages whose Status isn't publishedValue (default "Published") import as drafts
        publishedValue: "Done",
      }),
    ],
  },
});

O token da integração vem da variável de ambiente NOTION_TOKEN (compartilhe o banco de dados com a sua integração). Sem ela, a fonte é interrompida antes de chamar o Notion, com um erro BLUME_MISSING_SECRET que informa o nome da variável, a menos que tenha um snapshot em cache para servir no lugar.

Por padrão, a propriedade Status controla a publicação. Uma página cujo Status (uma propriedade do tipo status ou select) tenha qualquer valor diferente de publishedValue, que por padrão é Published, é importada com draft: true, e os builds de produção descartam os rascunhos. Uma página sem valor de Status é publicada, e um banco de dados sem essa propriedade publica todas as páginas. As opções de status padrão do Notion são Not started, In progress e Done. Um banco de dados que usa essas opções não tem nenhum valor Published e não publica nada até você definir publishedValue: "Done" (ou a opção que significa publicado no seu caso). Use properties.status para indicar uma propriedade com outro nome. Para importar todas as páginas independentemente do status, aponte essa opção para uma propriedade que o banco de dados não tem.

As URLs de imagens e vídeos do Notion são assinadas e expiram, então o adaptador baixa esses arquivos durante o build para os assets do site e reescreve as referências. Assim, um asset do CMS nunca deixa de funcionar em um build estático. Só são salvos os arquivos que o servidor informa serem imagem ou vídeo (ou, quando a resposta não informa, aqueles cuja URL tem uma extensão de imagem ou vídeo). Qualquer outro arquivo mantém a URL original e gera um aviso de build, então a origem do seu site nunca serve nada além de mídia. As chamadas à API passam por um pequeno pool de requisições (3 por vez, de acordo com o limite de taxa por integração do Notion), para que bancos de dados com centenas de páginas sejam importados sem receber respostas 429. Defina concurrency na fonte para ajustar esse limite.

Transforme um banco de dados do Notion em um site de documentação mostra o processo de ponta a ponta, com uma propriedade Status que decide o que vai ao ar. Combine Markdown e Notion em um único site de documentação dá aos editores do Notion uma seção própria ao lado do Markdown no Git.

Escrevendo MDX no Notion

O Notion não tem bloco para a maioria dos componentes do Blume. Para usar um deles em uma página do Notion (um <CardGroup> de <Card>s, por exemplo), digite o MDX dele como texto e defina mdx: true. A fonte passa então a ler o texto de parágrafos, títulos, itens de lista, citações e callouts como MDX, então componentes, {expressions} e Markdown digitados no Notion são renderizados junto com o negrito, o itálico, os links e o código inline do próprio Notion. Blocos de código, títulos de toggles, legendas de imagens e vídeos e propriedades continuam como texto simples.

notion({
  database: "8f2c1e0a4b7d4f3c9e6a5d2b1c0f9e8d",
  mdx: true,
});

Nesse caso, o texto precisa seguir as regras do MDX, como um arquivo .mdx: um { ou < solto faz a página falhar, e um parágrafo que começa com import é lido como uma instrução de import. O MDX executa código durante o build do site, então qualquer pessoa que pode editar o banco de dados consegue executar código na sua máquina de build e ler as variáveis de ambiente dela, incluindo NOTION_TOKEN. Só ative o mdx em um banco de dados cujos editores você deixaria mexer no código do site.