Você clicou em Exportar como Markdown & CSV no Notion e recebeu um ZIP cheio de arquivos com um ID de página de 32 caracteres adicionado ao final de cada nome, blocos de callout que chegaram como HTML cru e toggles que perderam o envoltório recolhível. Ou tentou copiar uma página do Notion direto no seu editor e ganhou uma parede de spans com estilos. Tirar Markdown limpo do Notion não é um único fluxo — são dois, e escolher o certo economiza horas de limpeza manual.
Qual caminho serve para você
Os dois caminhos terminam no mesmo lugar — Markdown portátil que você joga no Obsidian, num gerador de sites estáticos, num README ou num prompt para um LLM. Eles diferem no ponto de partida e no que você precisa consertar depois.
- Caminho A — Exportação ZIP de Markdown & CSV. Você quer migrar um workspace inteiro ou uma árvore de páginas de uma vez. Não se importa em consertar nomes com UUID, HTML de callouts e duplicações de blocos sincronizados em lote. Leia a partir de Caminho A.
- Caminho B — Exportar como HTML e converter no navegador. Você tem uma ou poucas páginas com informação confidencial que não pode subir a lugar nenhum e quer a saída limpa na primeira tentativa. Leia a partir de Caminho B.
Se você está montando um pipeline automatizado, há uma terceira opção — a API de conteúdo Markdown do próprio Notion, lançada no início de 2026 — que tratamos depois dos dois caminhos.
Como o Notion emite Markdown na origem
O Notion é um editor baseado em blocos. Uma página é uma árvore de blocos (parágrafo, cabeçalho, item de lista, banco de dados, callout, toggle, bloco sincronizado, equação, conteúdo incorporado) e só um subconjunto tem equivalente em Markdown. Quando você pede para exportar como Markdown, o Notion percorre a árvore e emite o texto mais próximo possível. Tudo que não tem contraparte cai fora, é aplanado ou passa a HTML cru.
O Centro de Ajuda oficial do Notion confirma que os blocos de callout "serão exportados como HTML, porque não há equivalente em Markdown"Abre em uma nova aba. A mesma página avisa que no Windows a exportação com pastas aninhadas pode ultrapassar o MAX_PATH padrão de 260 caracteres e recomenda o 7-Zip como saída. As outras esquisitices não são listadas — você descobre ao abrir o ZIP.
Como rodar a exportação nativa Markdown & CSV
Antes de qualquer caminho, os passos mecânicos são os mesmos. Numa página, abra o menu ••• → Exportar → formato Markdown & CSV. Nos planos Business e Enterprise você pode ativar Incluir subpáginas, o que transforma uma exportação de página única numa exportação de subárvore inteira. Confirme para baixar o ZIP. Exportações de workspace inteiro ficam em Configurações → Workspace → Geral e podem levar várias horas em contas grandes.
Caminho A — Limpar a exportação ZIP de Markdown & CSV
Uma vez o ZIP no disco, você tem oito esquisitices recorrentes para lidar. São sempre as mesmas.
ID de página de 32 caracteres em nomes de arquivo e links
O Notion costuma acrescentar um ID de página hexadecimal de 32 caracteres ao final de cada nome de arquivo .md exportado, e cada link [menção de página] dentro do Markdown aponta para esse nome com ID. Renomear os arquivos à mão quebra os links. A correção usual é um script de duas passagens: primeiro coleta o mapa ID → título a partir dos nomes de arquivo, depois reescreve cada link e renomeia cada arquivo para o título limpo. Guias comunitários como Notion's Markdown Export QuirksAbre em uma nova aba descrevem o mesmo padrão.
Limite de 260 caracteres de caminho no Windows
Páginas aninhadas do Notion geram nomes tipo My Team's Handbook a1b2c3.../Onboarding e4f5g6.../Week 1 tasks h7i8j9....md. No Windows isso ultrapassa o MAX_PATH padrão de 260 caracteres com facilidade. A ajuda do Notion sugere desativar a criação de pastas ou extrair o ZIP com 7-Zip, que lida com caminhos longos. macOS e a maioria dos sistemas de arquivos Linux não aplicam o mesmo teto de 260 caracteres.
Blocos callout chegam como HTML cru
Um callout do Notion com emoji e fundo colorido é exportado como HTML inline, não como blockquote de Markdown. A página de ajuda do Notion confirma esse comportamento. Muitos renderizadores deixam o HTML inline passar sem tocar, então o callout pode aparecer com o estilo padrão do navegador (frequentemente como um bloco simples) em vez do visual que você via no Notion. Duas correções aceitáveis: reescrever cada callout como blockquote > (perde emoji e cor), ou converter os callouts para o padrão de admonition do GFM (> [!NOTE]) se seu renderizador de destino suportar.
Toggles podem perder o envoltório recolhível
Um toggle do Notion é uma seção recolhível — cabeçalho em cima, conteúdo escondido embaixo. Na exportação Markdown & CSV, o envoltório recolhível pode se perder; o cabeçalho e o conteúdo interno ficam lado a lado como parágrafos comuns. Se você precisa que o recolhimento sobreviva no GitHub ou num site estático, envolva o bloco à mão em <details><summary>...</summary>...</details>. Ambas as tags são HTML inline que o Markdown permite.
Blocos sincronizados duplicam conteúdo entre páginas
Um bloco sincronizado aparece em várias páginas dentro do Notion, mas a exportação resolve cada instância separadamente. O mesmo conteúdo acaba escrito em todos os arquivos que o referenciam. Se você alimenta a exportação num pipeline RAG ou num índice de busca, isso aparece como fragmentos quase duplicados que poluem a recuperação. A remediação é manual: escolha uma página canônica para cada bloco sincronizado e remova as duplicações antes de indexar.
Equações e conteúdo incorporado viram texto puro
Equações LaTeX do Notion são exportadas como texto cru entre cifrões. O Obsidian trata como matemática e o GitHub renderiza $…$ e $$…$$ como matemática nativamenteAbre em uma nova aba desde 2022. Outros renderizadores não. Conteúdo incorporado de vídeo, Figma e Twitter geralmente sai como URL crua — não como imagem Markdown, não como <iframe>.
Caminhos de imagem dependem da estrutura de pastas exportada
Imagens ficam numa pasta de anexos por página ao lado do .md, e o link em Markdown aponta para essa pasta via caminho relativo. Mover um único .md para outro lugar sem levar sua pasta de anexos quebra todas as imagens. Duas opções: manter o arquivo ao lado da pasta, ou reescrever os links de imagem para um caminho central /assets/ e mover os arquivos para lá.
Bancos de dados são exportados como CSV, não como tabela Markdown
Um banco de dados de página completa vira um CSV, e a página subjacente de cada linha vira um .md dentro de uma pasta com o mesmo nome. Não há representação como tabela Markdown, e as views (filtros, ordenação, agrupamento) junto com relações, rollups e fórmulas não são preservadas. Se você quer o banco de dados como tabela Markdown, passe o CSV por CSV para Markdown — ele emite tabelas com pipes direto. Para uso pesado de bancos de dados, esse único passo já muda a migração.
Caminho B — Exportar como HTML e converter no navegador
Se você tem só um punhado de páginas e não pode subir para lugar nenhum — planos de produto, contratos, entradas de base de conhecimento interna — o caminho prático é HTML.
O diálogo de exportação do Notion oferece três formatos: Markdown & CSV, HTML e PDF. HTML é o mais rico dos três: preserva a estrutura do callout (como HTML inline), mantém os envoltórios de toggle e conserva os links internos.
O fluxo:
- No Notion abra a página → ••• → Exportar → HTML. Inclua subpáginas se precisar.
- Abra o arquivo
.html(ou copie seu conteúdo). - Cole em HTML para Markdown e clique em Run.
- Copie o Markdown resultante para o Obsidian, seu CMS ou seu prompt para o LLM.
A conversão roda inteiramente no seu navegador — nenhuma requisição sai da página. Não há conta, OAuth, nem token de workspace para conceder a um serviço de terceiros. Isso importa pelas mesmas razões que mantêm conversores online são seguros? em pauta: subir um documento privado para um conversor hospedado é o momento em que você perde o controle.
O que sobrevive à conversão: cabeçalhos, listas, links, tabelas, blocos de código, negrito e itálico. O que é removido: atributos style inline, nomes de classe, <div> envoltório, atributos data-* e outra marcação de apresentação para a qual o Markdown não tem sintaxe. Os callouts do Notion sobrevivem como HTML inline — a tag permanece, mas o estilo que o app do Notion aplicava não viaja com ela. Se seu objetivo é alimentar o resultado num LLM, veja Markdown vs HTML para LLMs para entender por que o orçamento de tokens rende mais com Markdown do que com HTML. Para padrões gerais de limpeza ao colar HTML, veja colar HTML como Markdown.
Caminho C — A API de conteúdo Markdown do Notion (versão 2026-03-11)
O Notion adicionou endpoints de conteúdo Markdown de primeira parte em 2026. A documentação oficial para desenvolvedoresAbre em uma nova aba descreve essa superfície, e as requisições precisam enviar o cabeçalho de versão de API 2026-03-11 para usá-la. Em vez de percorrer a árvore de blocos e traduzir cada um, você faz uma única chamada:
GET /v1/pages/{id}/markdown— lê uma página como MarkdownPOST /v1/pagescom um corpomarkdown— cria uma página a partir de MarkdownPATCH /v1/pages/{id}/markdown— atualiza o conteúdo da página com Markdown
O Notion chama o formato de Enhanced Markdown. Cabeçalhos, listas, links e ênfase padrão parecem normais. Blocos sem análogo em CommonMark ganham tags com sabor XML: <callout>...</callout> para callouts, <details><summary>...</summary>...</details> para toggles, e <database> como tag de referência apontando para um banco de dados. Se sua ferramenta consumidora entende essas tags, você preserva a fidelidade que o Caminho A perde; se não, você as remove ou reescreve no mesmo script que consome a API. Os endpoints funcionam com integrações públicas além de tokens internos e pessoais.
Dois cuidados vale a pena destacar:
- A API retorna URLs assinadas para blocos de arquivo (imagens, PDFs). Essas URLs expiram — baixe os recursos no mesmo processo, não arquive só o Markdown.
- Páginas com mais de aproximadamente 20.000 blocos são truncadas; a resposta traz
unknown_block_idsque você pode buscar separadamente. A documentação do Notion descreve o padrão de continuação.
Para uma página avulsa ou uma que você não pode compartilhar com terceiros, a rota HTML → FormatArc costuma ser mais rápida. A API se justifica quando você monta um pipeline automatizado (Notion → CMS ou Notion → índice RAG) num repositório, com um token rotacionável.
Comparação: quatro formas de tirar Markdown do Notion
| Abordagem | Ideal para | Callouts / toggles | UUIDs na saída | Roda no navegador |
|---|---|---|---|---|
| Exportação nativa Markdown & CSV | Migração de workspace inteiro que você limpa em bloco | Callouts como HTML cru; toggles podem perder o envoltório | Sim (nomes + destinos de link) | Sim (ZIP é local) |
| Exportação HTML do Notion → HTML para Markdown | Uma ou poucas páginas confidenciais | Callouts como HTML inline; toggles como <details> | Não | Sim |
| Biblioteca npm notion-to-mdAbre em uma nova aba | Pipelines sob medida com controle por bloco | Configurável por bloco | Configurável | Sim (Node / CLI) |
API Markdown Content do Notion (versão 2026-03-11) | Pipelines automatizados com token de API | Tags <callout> / <details> do Enhanced Markdown | Não (sem saída em filesystem) | Não (chamada no servidor) |
Perguntas frequentes
Por que o Notion coloca IDs de página de 32 caracteres nos nomes de arquivo exportados?
Cada bloco e página no Notion tem um ID interno. Quando a exportação escreve cada página em disco, ela costuma anexar esse ID ao nome para que duas páginas com o mesmo título (por exemplo, "Ata de reunião") possam conviver na mesma pasta sem colidir. O custo são nomes ilegíveis e quebra de caminho no Windows. A exportação HTML e a API Markdown Content escapam do problema porque uma trabalha com um único arquivo HTML e a outra com uma única resposta de API.
Conversores online de Notion para Markdown são seguros com páginas confidenciais?
Depende se o conversor roda no navegador ou no servidor. Uma ferramenta baseada no navegador (como o HTML para Markdown do FormatArc) processa o conteúdo colado em JavaScript na sua própria máquina; nada é enviado. Um SaaS de servidor recebe o arquivo. Para planos de produto, contratos ou documentação não publicada, a regra prática é a mesma de qualquer outro conversor — veja conversores online são seguros? para as verificações que permitem distinguir os dois tipos.
Devo usar a API ou Exportar como Markdown?
Use a API quando tiver um trabalho repetível e automatizado — jogar páginas do Notion no build de um site estático, manter um índice RAG sincronizado ou migrar centenas de páginas em cronograma. Use Exportar como Markdown para uma migração pontual que você limpa à mão. Use exportação HTML + FormatArc para páginas confidenciais avulsas onde você quer a saída limpa sem tocar num servidor.
A API de Markdown do Notion preserva callouts e toggles?
Sim, via tags de Enhanced Markdown: <callout>...</callout> para callouts e <details><summary>...</summary>...</details> para toggles. Ambas são HTML inline que o CommonMark permite, e o GitHub renderiza <details> como um recolhível funcional. Callouts são renderizados como estão só no Notion; em outras plataformas você estiliza sozinho ou reescreve como blockquote.
O que acontece com meus bancos de dados do Notion na exportação?
A exportação nativa Markdown & CSV escreve cada banco de dados como um CSV, com a página subjacente de cada linha virando um .md dentro de uma pasta. A view do banco (filtros, ordenação, agrupamento) não é preservada. Se você quer o banco como tabela Markdown, passe o CSV por CSV para Markdown. Se você quer páginas por linha mais uma tabela resumo, faça os dois.
Para finalizar
A exportação Markdown do Notion não está quebrada — é lossy. O Caminho A entrega o workspace inteiro ao custo de oito esquisitices recorrentes que você conserta em lote. O Caminho B permite converter uma página confidencial com HTML para Markdown inteiramente no seu navegador, sem conta e sem upload. A API de conteúdo Markdown (versão 2026-03-11) fica entre as duas para pipelines automatizados. Para padrões gerais de conversão HTML → Markdown, veja o guia de HTML para Markdown; para alimentar o resultado num LLM, veja Markdown vs HTML para LLMs.