Você decide mover seu blog WordPress para Hugo, 11ty ou Obsidian, clica em Ferramentas e depois em Exportar — e o que recebe é um arquivo XML, não Markdown. É aqui que a maioria das migrações trava. Não existe um caminho único: a rota mais curta depende de quantos posts você tem e de quais ferramentas pode executar. Este guia compara três rotas, percorre cada uma delas e cobre a limpeza final que todas deixam para trás.
Qual rota escolher
A decisão vem primeiro.
- Dezenas ou centenas de posts, e você pode executar Node.js localmente — Rota A (wordpress-export-to-markdown)
- Você quer que tudo aconteça no servidor e tem permissão de administrador para instalar plugins — Rota B (plugins exportadores)
- Apenas alguns posts, sem Node.js, sem permissão para plugins, ou conteúdo que você não pode colar em um serviço que faz upload — Rota C (conversão no navegador, grátis, sem cadastro, sem enviar nada)
A Rota C é menos uma "migração" e mais uma ferramenta de extração precisa, mas para resgatar alguns posts de um WordPress interno ou adiantar um rascunho, é o caminho mais curto.
Por que o XML exportado ainda não é Markdown
Ao executar Ferramentas e depois Exportar no painel do WordPress, você baixa um arquivo WordPress eXtended RSS (WXR)Abre em uma nova aba: um formato XML que agrupa posts, páginas, categorias, tags e comentários. O corpo de cada post está dentro desse XML como HTML incorporado. Ou seja, a exportação é "HTML dentro de uma casca XML", e chegar ao Markdown exige duas conversões.
Além disso, posts escritos no editor de blocos (Gutenberg) carregam os delimitadores de bloco serializados como comentários HTML. Como mostra a documentação oficial de arquitetura do editor de blocosAbre em uma nova aba, um parágrafo é salvo assim:
<!-- wp:paragraph -->
<p>Bem-vindo ao mundo dos blocos.</p>
<!-- /wp:paragraph -->
Shortcodes como [gallery] também permanecem incorporados no corpo. Como você trata essas três camadas — a casca XML, os comentários de bloco e os shortcodes — é o que realmente diferencia as rotas.
Antes de migrar — o que se mantém e o que se perde
Todas as rotas convertem o corpo do post (títulos, parágrafos, listas, links, tabelas, blocos de código) em Markdown. As diferenças estão nos metadados.
- Datas de publicação, slugs, categorias e tags vivem no arquivo WXR. A Rota A as escreve no frontmatter; a Rota C só vê o HTML do corpo que você copiou, então o frontmatter é adicionado por você
- Comentários de leitores não viram Markdown em nenhuma rota. Se quiser mantê-los, planeje separadamente a troca para um serviço de comentários de sites estáticos
- Campos personalizados dependem da ferramenta. Se você depende de campos específicos, faça um inventário antes de começar
Rota A — conversão em massa com wordpress-export-to-markdown
O padrão de fato é o wordpress-export-to-markdownAbre em uma nova aba. Ele recebe o arquivo WXR como entrada, grava cada post como um arquivo Markdown com frontmatter, e baixa as imagens referenciadas reescrevendo as referências (a lista de recursos está no README do repositório).
- No painel, abra Ferramentas, depois Exportar, escolha "Todo o conteúdo" e baixe o XML.
- Em uma máquina com Node.js, execute:
npx wordpress-export-to-markdown
Um assistente interativo pergunta onde está o arquivo exportado, onde deixar a saída, como organizar pastas (--post-folders / --date-folders), se deve prefixar nomes com datas (--prefix-date), como salvar imagens (--save-images) e quais campos incluir no frontmatter (--frontmatter-fields). Quanto mais posts você tiver, mais esse processamento em lote compensa.
Rota B — exportar com um plugin
Se preferir manter tudo no servidor, existem plugins exportadores como o Static Site Exporter (antigo Jekyll Exporter)Abre em uma nova aba, que empacotam seus posts e páginas como arquivos Markdown com frontmatter YAML em um ZIP, prontos para Jekyll ou Hugo.
Dois avisos. Instalar um plugin exige permissão de administrador e, como a própria página do plugin indica, sites grandes tendem a estourar o tempo limite ao exportar pela interface web, então lá se recomenda a execução por linha de comando. Em hospedagem compartilhada você também pode esbarrar nos limites de memória do PHP.
Rota C — converter no navegador, sem instalar nada
Para alguns posts, a conversão no navegador sem configuração é a rota mais curta. Há duas formas de obter a entrada:
- Abra o post no editor de blocos, mude para a visão "Editor de código" no menu de opções e copie o HTML do corpo. Esse HTML contém os comentários de bloco como
<!-- wp:paragraph --> - Abra a página publicada no navegador e copie o HTML do artigo pelas ferramentas de desenvolvedor. É HTML renderizado, então não há comentários de bloco — mas vêm elementos de invólucro do tema
Cole o que copiou em HTML para Markdown e execute a conversão.
Por exemplo, ao colar este HTML copiado da visão de editor de código:
<!-- wp:heading -->
<h2 class="wp-block-heading">Migrating the archive</h2>
<!-- /wp:heading -->
<!-- wp:image -->
<figure class="wp-block-image size-large"><img src="https://example.com/wp-content/uploads/2024/03/diagram.png" alt="Architecture diagram" class="wp-image-42"/><figcaption class="wp-element-caption">Figure 1: the old stack</figcaption></figure>
<!-- /wp:image -->
a saída é esta:
## Migrating the archive
Figure 1: the old stack
Os comentários de bloco, as classes wp-block-* e os estilos inline desaparecem; títulos e imagens viram sintaxe Markdown. O texto do figcaption sobrevive como uma linha de texto simples sob a imagem. O código em <pre class="wp-block-code"> vira um bloco de código cercado, e as tabelas viram tabelas de pipe. Shortcodes não são HTML, então passam sem conversão — ficam como texto simples escapado, por exemplo \[gallery ids="12,13,14"\] (veja a seção de limpeza).
A conversão roda inteiramente no JavaScript do seu navegador; nada do que você cola é transmitido a lugar algum. Essa diferença importa quando os posts vêm de um WordPress interno ou são rascunhos não publicados — o oposto dos SaaS de conversão que fazem upload. Como avaliar esse risco está em os conversores online são seguros?. Para o fluxo geral de conversão, veja o guia de HTML para Markdown, e para limpar HTML colado do Word ou da web, colar HTML como Markdown — este artigo foca no que é específico do WordPress.
Lista de limpeza pós-migração
Seja qual for a rota, estes quatro itens ficam para o final.
- Limpeza de shortcodes.
[gallery],[caption]e shortcodes de plugins não são convertidos em Markdown. Suas formas variam (com atributos, envolventes), então procurar[nos arquivos e decidir caso a caso é mais seguro que uma substituição global - Realocação de imagens. Na Rota C, as URLs de imagem continuam apontando para
wp-content/uploads. Baixe as imagens para o novo ambiente e reescreva as URLs. Os atributossrcseteloading="lazy"se perdem na conversão; adicione equivalentes na plataforma de destino se precisar - Links internos. Reescreva os links que apontam para o domínio antigo ou para estruturas de permalink antigas (como a forma
?p=123) conforme o esquema de URLs do novo site - Frontmatter. Adicione título, data e tags como YAML no topo de cada arquivo. Para as diferenças entre formatos de SSG, veja frontmatter de Markdown em YAML e JSON
Comparação — escolhendo entre as três rotas
| Rota | Ideal para | Requisitos | Metadados | Imagens |
|---|---|---|---|---|
| A: wordpress-export-to-markdownAbre em uma nova aba | Migração em massa de dezenas ou centenas de posts | Node.js + exportação WXR | Gravados no frontmatter automaticamente | Baixadas, referências reescritas |
| B: plugins exportadores | Manter o trabalho no servidor | Permissão de administrador (instalar plugins) | Gravados no frontmatter automaticamente | Depende do plugin |
| C: HTML para Markdown | Migração pontual de poucos posts | Um navegador (grátis, sem cadastro) | Adicionados manualmente | URLs preservadas, realocação manual |
Perguntas frequentes
Posso converter posts do WordPress em Markdown sem Node.js?
Sim. Se você pode instalar plugins, use a Rota B; se não, a Rota C. Mude o post para a visão de editor de código, copie o HTML e cole em HTML para Markdown — sem configurar nada.
Os comentários de bloco do Gutenberg sobrevivem à conversão?
Na conversão do FormatArc, comentários HTML como <!-- wp:paragraph --> não aparecem na saída. Note que esses comentários só existem no HTML copiado da visão de editor de código; o HTML copiado de uma página publicada nunca os teve.
As imagens podem ser migradas junto com os posts?
A Rota A baixa as imagens referenciadas e reescreve as referências (conforme o READMEAbre em uma nova aba). A Rota C converte apenas a marcação — as URLs de imagem continuam apontando para o site original. Para poucos posts, salvar as imagens manualmente e reescrever as URLs é prático.
É seguro colar rascunhos não publicados ou conteúdo de um WordPress interno em uma ferramenta externa?
Com ferramentas que enviam dados a um servidor, o conteúdo sai das suas mãos no momento em que você cola. O FormatArc processa tudo dentro do navegador, então não há transmissão alguma. Os critérios para avaliar isso estão em os conversores online são seguros?.
Posts escritos no editor clássico funcionam com os mesmos passos?
Sim. O corpo do editor clássico é HTML puro sem comentários de bloco, o que na verdade simplifica a conversão. As Rotas A, B e C lidam com posts do editor clássico.
Resumo
A migração de WordPress para Markdown se decide por escala e ambiente. Para centenas de posts, wordpress-export-to-markdown; para ficar no servidor, um plugin exportador; para poucos posts sem configurar nada — ou conteúdo que não deve ser enviado a lugar algum — a conversão no navegador com HTML para Markdown é o caminho mais curto. Seja qual for a escolha, trate a limpeza de shortcodes, a realocação de imagens, a reescrita de links internos e o frontmatter como parte da migração, não como um detalhe. Se você fizer o mesmo exercício com conteúdo do Notion, exportar Notion para Markdown aplica o mesmo raciocínio.