Corrigir importação de Markdown no Notion que não reconhece especificador de linguagem em blocos de código

Ao importar um arquivo Markdown para o Notion, blocos de código que incluem um especificador de linguagem — como “`python ou “`javascript — geralmente perdem esse especificador e aparecem como blocos de código simples, sem realce de sintaxe. Isso acontece porque o parser de importação do Notion não lê o identificador de linguagem que segue as três crases iniciais. Em vez disso, ele trata a linha inteira como parte do conteúdo do código. Este artigo explica por que o especificador é descartado e fornece uma solução alternativa confiável para preservar o realce de sintaxe em blocos de código importados.

Por que o Notion descarta o especificador de linguagem durante a importação de Markdown

O parser de importação de Markdown do Notion segue uma versão simplificada da especificação CommonMark. No CommonMark, um bloco de código cercado começa com três ou mais crases. O especificador de linguagem opcional que segue as crases iniciais — por exemplo, python em ```python — tem a finalidade de indicar a linguagem de programação para realce de sintaxe. No entanto, o parser do Notion não extrai esse especificador. Em vez disso, ele inclui a linha inteira ```python como a primeira linha do conteúdo do bloco de código. Como resultado, o bloco de código importado exibe o especificador de linguagem como texto literal dentro do bloco, e o bloco em si não possui linguagem atribuída. Esse comportamento é uma limitação conhecida do recurso de importação. O parser também ignora outras extensões do CommonMark, como atributos de número de linha e strings de informação personalizadas.

Como o parser lida com crases

Quando o Notion encontra uma linha começando com três crases, ele inicia um bloco de código. Em seguida, lê cada linha subsequente como código até encontrar uma cerca de fechamento de três ou mais crases. O parser não examina o texto após as crases iniciais em busca de um identificador de linguagem. Isso significa que ```python, ```javascript e ``` são tratados de forma idêntica: a cerca de abertura é reconhecida, mas o especificador é consumido como parte do conteúdo do código. Após a importação, o bloco de código aparece com o texto do especificador visível no topo, e a propriedade de linguagem do bloco permanece não definida.

Três métodos para restaurar especificadores de linguagem após a importação

Método 1: Modificar o arquivo Markdown antes da importação

A maneira mais rápida de evitar o problema do especificador é remover todos os especificadores de linguagem do arquivo Markdown antes de importá-lo para o Notion. Após a importação, você pode atribuir manualmente o idioma correto a cada bloco de código. Este método é melhor quando você tem um número pequeno de blocos de código.

1. Abra o arquivo Markdown em um editor de texto simples
   Use o Bloco de Notas no Windows, TextEdit no Mac ou qualquer editor de código como Visual Studio Code.
2. Encontre todas as linhas que começam com três crases seguidas por um nome de linguagem
   Pesquise pelo padrão ```[a-zA-Z]. No Visual Studio Code, use a pesquisa regex e digite ```\w+.
3. Substitua cada linha correspondente por apenas três crases
   Altere ```python para ```. Faça o mesmo para cada especificador de linguagem.
4. Salve o arquivo modificado
   Mantenha o arquivo original como backup caso precise reimportar depois.
5. Importe o arquivo para o Notion
   Vá para o espaço de trabalho onde deseja a página. Clique em Importar no canto superior direito e selecione Markdown. Escolha o arquivo modificado.
6. Clique em cada bloco de código e defina o idioma
   Passe o mouse sobre o bloco de código, clique no ícone ⋮⋮ à esquerda e selecione o idioma correto no menu suspenso.

Método 2: Usar a API do Notion para criar blocos de código com idioma

Se você tem muitos blocos de código ou precisa automatizar o processo, use a API do Notion. Este método requer um token de integração do Notion e familiaridade básica com requisições HTTP. Você pode escrever um script em Python ou JavaScript que leia o arquivo Markdown, divida-o em blocos e envie cada bloco de código para a API com a propriedade de idioma correta.

1. Crie uma integração do Notion
   Acesse www.notion.so/my-integrations e clique em + Nova integração. Dê um nome e selecione o espaço de trabalho. Copie o token secreto da integração interna.
2. Compartilhe a página de destino com a integração
   Abra a página onde deseja adicionar os blocos de código. Clique em Compartilhar no canto superior direito, depois em Adicionar conexões e selecione sua integração.
3. Analise o arquivo Markdown e extraia blocos de código com seus especificadores de linguagem
   Escreva um script que leia o arquivo linha por linha. Quando encontrar uma linha correspondente a ```linguagem, capture o nome da linguagem e colete todas as linhas até o ``` de fechamento.
4. Envie cada bloco de código via API
   Use o endpoint blocks.children.append com um corpo de requisição que inclua um objeto de bloco code. Defina o campo language para o especificador capturado. Por exemplo, para Python defina "language": "python".
5. Execute o script e verifique a saída
   Após a conclusão do script, abra a página do Notion e confirme que cada bloco de código mostra o realce de sintaxe correto.

Método 3: Editar manualmente cada bloco de código após a importação

Se você já importou o arquivo e não pode reimportar, pode corrigir cada bloco de código manualmente. Este método é demorado, mas não requer ferramentas externas.

1. Abra a página importada no Notion
   Navegue até a página que contém os blocos de código.
2. Localize um bloco de código que exibe o especificador de linguagem como texto
   Procure por uma linha como python ou javascript no topo do bloco de código.
3. Exclua a linha do especificador do conteúdo do bloco de código
   Clique dentro do bloco de código, selecione a primeira linha que contém o nome da linguagem e pressione Delete.
4. Atribua o idioma correto ao bloco
   Passe o mouse sobre o bloco de código, clique no ícone ⋮⋮ à esquerda e escolha o idioma no menu suspenso.
5. Repita para cada bloco de código na página
   Esta etapa pode ser tediosa se você tiver muitos blocos. Considere usar o Método 1 ou 2 para arquivos grandes.

Se o Notion ainda exibir o especificador como texto após a correção

O conteúdo do bloco de código inclui crases extras

Às vezes, o bloco de código importado contém linhas extras de crases que faziam parte do Markdown original. Isso pode acontecer se o arquivo original usava quatro crases em vez de três, ou se a cerca de fechamento estava ausente. Para corrigir, exclua quaisquer linhas que não sejam código real. Certifique-se de que o bloco de código contenha apenas o código desejado e que as cercas de abertura e fechamento sejam exatamente três crases.

O especificador de linguagem estava embutido no próprio código

Se o arquivo Markdown usava um formato como ``` {.python} ou ```python {.numberLines}, o Notion pode incluir a string inteira como parte do código. Nesse caso, exclua os caracteres extras da primeira linha do bloco de código. Em seguida, atribua o idioma manualmente usando o menu do bloco.

O processo de importação criou um bloco de código dentro de outro bloco

Raramente, a importação pode aninhar um bloco de código dentro de um callout ou um toggle. Se o especificador aparecer dentro de um tipo de bloco diferente, arraste o bloco de código para fora do contêiner usando a alça de arrasto. Em seguida, aplique a correção de idioma conforme descrito no Método 3.

Métodos de importação de Markdown: Manual vs API vs Ferramentas de terceiros

Item	Localizar e substituir manual + reimportação	Script da API do Notion	Conversor de terceiros (ex.: md-to-notion)
Tempo de configuração	5 minutos	30–60 minutos	10 minutos
Preserva o especificador de linguagem automaticamente	Não	Sim	Depende da ferramenta
Requer programação	Não	Sim	Não
Melhor para	Arquivos pequenos com poucos blocos de código	Arquivos grandes ou importações repetidas	Usuários confortáveis com ferramentas de linha de comando
Risco de perda de dados	Baixo se você fizer backup do arquivo original	Baixo se o script tratar erros	Médio se o conversor modificar o conteúdo

Agora você pode importar arquivos Markdown para o Notion sem perder os especificadores de linguagem dos blocos de código. Comece modificando o arquivo antes da importação se você tiver apenas alguns blocos. Para projetos maiores, escreva um script que use a API do Notion para definir a propriedade de idioma diretamente. Como dica avançada, use o endpoint blocks.children.append com um objeto de bloco code que inclua os campos rich_text e language — isso dá controle total sobre a estrutura do bloco de código importado.