Problemas na conversão Markdown: tabelas, código e imagens

Você escreveu seu Markdown direitinho. Clicou em "Converter". E o resultado não tem nada a ver com o que você esperava: as tabelas estão destruídas, os blocos de código aparecem como texto puro, as imagens sumiram e suas fórmulas LaTeX viraram um monte de texto sem sentido.

Depois de ajudar milhares de usuários a converter Markdown para Word, PDF e HTML com o MarkFlow, catalogamos as falhas de conversão mais comuns e suas correções. Este guia cobre 15 problemas reais com soluções práticas, sem enrolação.

Referência rápida: problema e solução

---

Problemas com tabelas

Problema 1: Colunas da tabela ficam desalinhadas ou se fundem no Word

O que você vê: Sua tabela Markdown, que ficava perfeita no editor, vira uma bagunça no Word — colunas fundidas, conteúdo transbordando ou a estrutura da tabela simplesmente desaparece.

Por que acontece:

A causa mais comum é sintaxe de tabela inválida. Tabelas Markdown são surpreendentemente rígidas. Um único caractere de pipe faltando ou uma linha de separação desalinhada quebra a tabela inteira.

Veja o que costuma dar errado:

<!-- ERRADO: Falta o pipe inicial -->
Header 1 | Header 2
--- | ---
Cell 1 | Cell 2

<!-- ERRADO: A linha de separação não bate com o número de colunas -->
| Header 1 | Header 2 | Header 3 |
| --- | --- |
| Cell 1 | Cell 2 | Cell 3 |

Como resolver:

Sempre use uma sintaxe de pipes consistente com o mesmo número de colunas:

| Header 1 | Header 2 | Header 3 |
|:---------|:--------:|----------:|
| Left     | Center   | Right     |
| Cell 1   | Cell 2   | Cell 3    |

Regras essenciais:

• Comece e termine cada linha com um pipe |
• A linha de separação precisa ter o mesmo número de colunas que o cabeçalho
• Use dois pontos para alinhar — :--- esquerda, :---: centro, ---: direita
• Não use células mescladas — Markdown padrão não suporta isso. Se você precisa mesclar células, edite o documento Word manualmente depois da conversão

Dica: Antes de converter, cole sua tabela em um linter de Markdown ou ferramenta de pré-visualização. A maioria dos editores (VS Code, Typora, Obsidian) mostra na hora se a tabela tem algum erro.

---

Problema 2: A largura das colunas fica desigual no Word

O que você vê: A tabela renderiza certinho no seu editor Markdown, mas depois de converter para Word, uma coluna ocupa 80% da largura da página enquanto as outras ficam espremidas.

Por que acontece:

A maioria dos conversores de Markdown para Word calcula a largura das colunas com base no tamanho do conteúdo. Se uma célula tem uma frase longa ou URL enquanto as outras têm valores curtos, a distribuição fica desbalanceada. Diferente do HTML, Markdown não tem sintaxe para especificar larguras de coluna.

Como resolver:

• Mantenha o conteúdo das células curto. Mova descrições longas para notas de rodapé ou parágrafos separados abaixo da tabela
• Encurte URLs longas com texto de link: Use [Texto do link](url) em vez de colar URLs diretamente nas células
• Use o MarkFlow para a conversão — ele aplica distribuição balanceada de colunas por padrão, gerando tabelas mais legíveis no Word do que a maioria dos conversores

Se você precisa de larguras de coluna exatas, edite a tabela no Word depois da conversão: selecione a tabela, vá em Propriedades da Tabela, aba Coluna, e defina a largura desejada.

---

Problema 3: Conteúdo com caracteres especiais quebra a renderização da tabela

O que você vê: Caracteres de pipe | dentro das células quebram a estrutura de colunas, ou entidades HTML aparecem como texto cru.

Por que acontece:

O caractere pipe | é o delimitador de colunas nas tabelas Markdown. Quando o conteúdo da célula tem um pipe literal, o parser interpreta como uma divisão de coluna.

Como resolver:

Escape o caractere pipe com uma barra invertida:

| Comando | Descrição |
|:--------|:------------|
| `echo "a \| b"` | Redireciona a saída pelo filtro |
| `status: pass\|fail` | Mostra status de sucesso ou falha |

Para outros caracteres especiais em células de tabela:

• Use \| para caracteres pipe literais
• Use entidades HTML como & para e-comercial se necessário
• Envolva o conteúdo com backticks de código inline para evitar a interpretação do Markdown

---

Problemas com blocos de código

Problema 4: Blocos de código perdem o destaque de sintaxe após a conversão

O que você vê: Seu código Python ou JavaScript, que estava lindo com cores no editor, vira texto monocromático sem graça no documento Word.

Por que acontece:

Duas causas comuns:

1. Sem identificador de linguagem — Você usou crase tripla sem especificar a linguagem
2. O conversor não suporta destaque — Muitos conversores básicos removem o destaque de sintaxe durante a exportação para Word/PDF

A diferença é clara:

<!-- SEM destaque — falta a tag da linguagem -->
```
function hello() {
  console.log("Hello");
}
```

<!-- COM destaque — linguagem especificada -->
```javascript
function hello() {
  console.log("Hello");
}
```

Como resolver:

Sempre especifique a linguagem depois das crases triplas de abertura. Identificadores comuns:

Se o seu conversor continua sem produzir código com destaque, o MarkFlow preserva o destaque de sintaxe tanto no Word quanto no PDF — o código aparece com cores, tipografia e indentação corretos.

---

Problema 5: A formatação de código inline desaparece

O que você vê: O texto entre crases simples como config.yaml ou npm install aparece como texto normal no documento convertido, sem nenhuma distinção visual.

Por que acontece:

Alguns conversores tratam código inline como texto puro e não aplicam nenhum estilo. A sintaxe de crase é reconhecida, mas o formato de saída não inclui fonte monoespaçada nem cor de fundo.

Como resolver:

• Use um conversor que respeite o estilo de código inline. O MarkFlow renderiza código inline com fonte monoespaçada e fundo sutil na saída Word
• Evite crases aninhadas no código inline. Se seu código contém crases, use crases duplas: `code with `backtick` vira ``code with `backtick` ``
• Não abuse do código inline para dar ênfase — use negrito ou itálico no lugar. Reserve as crases para código real, comandos, nomes de arquivo e identificadores técnicos

---

Problema 6: A indentação e os espaços em branco do código estão errados

O que você vê: Os blocos de código na saída Word têm indentação incorreta — ou tudo está alinhado à esquerda, ou os tabs foram convertidos em espaçamento inconsistente.

Por que acontece:

A conversão de tabs para espaços difere entre os parsers de Markdown e o motor de renderização do Word. Alguns conversores também removem espaços iniciais ou colapsam múltiplos espaços em um só.

Como resolver:

• Use espaços, não tabs, nos seus blocos de código Markdown. A maioria dos guias de estilo recomenda 2 ou 4 espaços. Tabs são interpretados de forma inconsistente entre conversores
• Use blocos de código cercados (crase tripla) em vez de blocos de código indentados (4 espaços). Blocos cercados são parseados de forma mais confiável:

<!-- PREFERÍVEL: Bloco de código cercado -->
```python
def nested():
    if True:
        for i in range(10):
            print(i)
```

<!-- EVITAR: Bloco de código indentado (4 espaços) -->
    def nested():
        if True:
            for i in range(10):
                print(i)

• Verifique a saída logo depois de converter. Se o espaçamento está errado, o problema é no conversor, não no seu Markdown. Teste com outra ferramenta ou reporte o bug

---

Problemas com imagens

Problema 7: As imagens não aparecem após a conversão

O que você vê: O documento Word ou PDF convertido mostra ícones de imagem quebrada, espaços vazios ou o texto alternativo no lugar da imagem real.

Por que acontece:

Esse é o problema de conversão número um, e quase sempre se resume aos caminhos de imagem:

1. Caminhos relativos que o conversor não consegue resolver — ![Alt](./images/foto.png) funciona no seu editor porque ele sabe onde o arquivo está. O conversor pode não saber
2. URLs remotas que exigem autenticação — Imagens em repos privados do GitHub, Google Drive ou Notion não são baixadas durante a conversão
3. Problemas de protocolo — Alguns conversores não lidam com caminhos file:// ou caminhos absolutos locais
4. Formato de arquivo não suportado — Certos conversores têm dificuldade com SVG, WebP ou TIFF

Como resolver:

Para uma abordagem confiável, use URLs de imagem acessíveis publicamente:

<!-- Mais confiável: URL absoluta -->
![Diagrama de arquitetura](https://seu-dominio.com/images/diagrama.png)

<!-- Também confiável: incorporação base64 (para imagens pequenas) -->
![Ícone](data:image/png;base64,iVBORw0KGgo...)

Com o MarkFlow: Arraste e solte seu arquivo .md junto com a pasta de imagens — os caminhos relativos são resolvidos automaticamente. Você também pode colar Markdown com URLs de imagens e elas serão incorporadas na saída Word.

---

Problema 8: As imagens ficam grandes demais ou pequenas demais no Word

O que você vê: Uma imagem que fica perfeita na pré-visualização do Markdown aparece minúscula ou enorme no documento Word convertido, quebrando o layout da página.

Por que acontece:

Markdown não tem sintaxe nativa para dimensionar imagens. O formato ![alt](url) não aceita parâmetros de largura ou altura. A maioria dos conversores insere as imagens nas dimensões originais em pixels, que podem não corresponder à largura da página do Word.

Como resolver:

Alguns sabores de Markdown suportam dimensionamento de imagens via HTML:

<!-- Controle o tamanho com HTML -->
<img src="./diagrama.png" alt="Diagrama de arquitetura do sistema" width="600" />

No entanto, nem todos os conversores de Markdown para Word processam tags HTML. Suas opções:

• Redimensione a imagem original para aproximadamente 600-800px de largura antes de adicioná-la ao Markdown — isso se encaixa na maioria dos layouts de página Word
• Use tags HTML img com width se o seu conversor suporta HTML inline
• Redimensione depois da conversão no Word: clique com o botão direito na imagem, selecione Tamanho e Posição, e defina a largura desejada

Dimensões recomendadas para saída Word:

• Imagens em largura total: 600-800px de largura
• Diagramas inline: 400-500px de largura
• Ícones ou badges: 100-200px de largura

---

Problema 9: Imagens embutidas em base64 falham na conversão

O que você vê: Imagens codificadas como data URIs base64 no seu Markdown funcionam na pré-visualização, mas aparecem quebradas ou são completamente removidas no documento convertido.

Por que acontece:

Imagens em base64 aumentam significativamente o tamanho do arquivo (cerca de 33% a mais que o binário). Alguns conversores têm limites de tamanho para data URIs inline, ou simplesmente não processam o formato data:image/...;base64,....

Como resolver:

• Mantenha as imagens base64 pequenas — abaixo de 100KB codificadas (cerca de 75KB no binário original). Ícones e logotipos pequenos funcionam bem; screenshots e fotos geralmente não
• Use arquivos de imagem reais para conteúdo grande. Hospede-os ou inclua junto ao seu arquivo .md
• Verifique a documentação do seu conversor sobre suporte a data URIs. O MarkFlow lida com imagens base64 tanto em Word quanto em PDF, mas há um limite prático de cerca de 2MB por imagem

---

Problemas com fórmulas LaTeX e diagramas Mermaid

Problema 10: As fórmulas LaTeX aparecem como texto puro

O que você vê: Em vez de uma equação renderizada corretamente, o documento Word mostra o código-fonte LaTeX: $E = mc^2$ ou $$\int_{0}^{1} x^2 dx$$ como texto literal.

Por que acontece:

O suporte a fórmulas LaTeX não faz parte do Markdown padrão nem do GFM. É uma extensão que precisa de engines de renderização específicas (KaTeX ou MathJax). A maioria dos conversores Markdown básicos — incluindo Pandoc sem as flags certas, VS Code sem extensões e Dillinger — não processa a sintaxe LaTeX.

Como resolver:

Primeiro, verifique se a sintaxe está correta:

<!-- Fórmula inline: cifrões simples -->
A fórmula $E = mc^2$ descreve a equivalência massa-energia.

<!-- Fórmula em bloco: cifrões duplos -->
$$
\frac{-b \pm \sqrt{b^2 - 4ac}}{2a}
$$

Depois, use um conversor que suporte LaTeX:

Erros comuns de LaTeX que causam falhas na renderização:

<!-- ERRADO: Espaço depois do $ de abertura -->
$ E = mc^2 $

<!-- CERTO: Sem espaço depois do $ de abertura -->
$E = mc^2$

<!-- ERRADO: Falta o delimitador de fechamento -->
$$\int_{0}^{1} x^2 dx

<!-- CERTO: Delimitadores correspondentes -->
$$\int_{0}^{1} x^2 dx$$

---

Problema 11: Os diagramas Mermaid não aparecem na saída

O que você vê: Em vez de um fluxograma ou diagrama de sequência renderizado, a saída Word/PDF mostra o código Mermaid como um bloco de código comum.

Por que acontece:

Mermaid é uma engine de renderização baseada em JavaScript. Precisa de um navegador ou de um ambiente Node.js para gerar o diagrama visual. A maioria dos conversores de Markdown para Word processa o Markdown como texto puro e não executa JavaScript, então trata os blocos Mermaid como código qualquer.

Como resolver:

Verifique primeiro a sintaxe do Mermaid:

```mermaid
graph TD
    A[Início] --> B{Decisão}
    B -->|Sim| C[Ação 1]
    B -->|Não| D[Ação 2]
    C --> E[Fim]
    D --> E
```

Ferramentas que renderizam Mermaid para Word/PDF:

• MarkFlow — Renderiza diagramas Mermaid como imagens incorporadas na saída Word
• Typora — Renderiza Mermaid na pré-visualização e exporta para PDF
• Pandoc — Requer o plugin mermaid-filter (npm install -g mermaid-filter)

Alternativa para conversores sem suporte a Mermaid:

1. Use o Mermaid Live Editor para renderizar seu diagrama
2. Exporte como PNG ou SVG
3. Substitua o bloco de código Mermaid por uma referência à imagem no seu Markdown
4. Converta normalmente

Isso adiciona um passo manual, mas garante que o diagrama apareça na saída de qualquer conversor.

---

Problemas de formatação e estrutura

Problema 12: Os níveis de título estão errados no Word

O que você vê: A hierarquia de títulos no Word não corresponde ao seu Markdown. Os H2 aparecem como H1, ou todos os títulos são renderizados no mesmo tamanho.

Por que acontece:

Duas causas comuns:

1. Múltiplos títulos H1 no Markdown. Um documento deveria ter apenas um H1 (o título). Alguns conversores fundem ou remapeiam títulos quando detectam múltiplos H1
2. O conversor mapeia títulos Markdown para estilos Word de forma diferente. Algumas ferramentas tratam o primeiro título como título do documento independente do seu nível

Como resolver:

Siga uma hierarquia de títulos correta:

# Título do documento (H1 — use exatamente uma vez)

## Título de seção (H2 — seções principais)

### Subseção (H3 — dentro de seções)

#### Detalhe (H4 — raramente necessário)

• Nunca pule níveis — não vá do H2 direto para o H4
• Use H1 apenas uma vez no topo do documento, ou deixe o conversor adicioná-lo a partir dos metadados do título
• Verifique o painel de Estilos do Word — os títulos devem aparecer como "Título 1", "Título 2", etc. Se mostram "Normal", o conversor não mapeou corretamente

---

Problema 13: Listas aninhadas perdem a indentação

O que você vê: Sua lista com marcadores ou numerada, cuidadosamente aninhada, aparece completamente achatada na saída Word — todos os itens no mesmo nível.

Por que acontece:

A indentação inconsistente é a culpada. Markdown exige espaçamento consistente para detectar níveis de aninhamento. Misturar tabs e espaços, ou usar 2 espaços em um lugar e 3 em outro, confunde o parser.

Como resolver:

Use 4 espaços (ou 1 tab) por nível de aninhamento, de forma consistente:

- Item de primeiro nível
    - Item de segundo nível
        - Item de terceiro nível
    - Volta ao segundo nível
- Volta ao primeiro nível

1. Primeiro item
    1. Sub-item um
    2. Sub-item dois
2. Segundo item
    - Marcador misto sob número

Erros comuns:

<!-- ERRADO: Indentação inconsistente (2 espaços e depois 3) -->
- Item A
  - Sub A (2 espaços)
   - Sub B (3 espaços — o parser se confunde)

<!-- CERTO: Indentação consistente de 4 espaços -->
- Item A
    - Sub A
    - Sub B

Se o conversor continua achatando as listas, tente trocar de ferramenta. O MarkFlow preserva a indentação de listas aninhadas na saída Word, incluindo listas mistas ordenadas/não ordenadas.

---

Problema 14: As notas de rodapé somem ou quebram

O que você vê: As referências de notas de rodapé como [^1] aparecem como texto literal no documento convertido, e o conteúdo da nota no final do seu Markdown está faltando ou é renderizado como um parágrafo normal.

Por que acontece:

Notas de rodapé são uma extensão do GFM, não fazem parte da especificação original do Markdown. Conversores que suportam apenas Markdown básico não processam a sintaxe de footnotes.

Como resolver:

Sintaxe correta de notas de rodapé:

Esta afirmação precisa de uma fonte[^1]. Outro ponto aqui[^nota].

[^1]: Silva, M. (2025). "Título do Artigo de Pesquisa." Nome do Periódico.
[^nota]: Esta é uma nota de rodapé mais longa com várias frases.
    Indente as linhas de continuação com 4 espaços.

Verifique se:

• A referência [^id] e a definição [^id]: usam o mesmo identificador
• As definições de notas de rodapé estão no final do documento (ou pelo menos depois de todas as referências)
• Seu conversor suporta notas de rodapé GFM — MarkFlow, Pandoc e Typora lidam com elas corretamente

---

Problema 15: Os caracteres emoji aparecem como quadrados vazios

O que você vê: Emojis como marcas de verificação, foguetes ou sinais de alerta aparecem como retângulos vazios ou pontos de interrogação na saída Word.

Por que acontece:

O documento Word usa uma fonte que não inclui glifos de emoji. Quando o conversor mapeia o texto Markdown para Word, aplica uma fonte padrão (como Calibri ou Times New Roman) que pode não conter caracteres emoji Unicode.

Como resolver:

• Depois da conversão: Selecione os caracteres emoji no Word, mude a fonte para "Segoe UI Emoji" (Windows) ou "Apple Color Emoji" (macOS)
• Antes da conversão: Se a renderização de emoji é essencial, considere substituí-los por equivalentes em texto ou imagens
• Use um conversor que lide com fontes emoji: O MarkFlow mapeia os caracteres emoji para a fonte do sistema apropriada na saída Word

---

Prevenção: como evitar problemas de conversão

A maioria dos problemas de conversão é evitável. Incorpore esses hábitos ao seu fluxo de trabalho com Markdown.

Valide antes de converter

Use um linter de Markdown para pegar erros de sintaxe antes que virem problemas de conversão:

# Instale o markdownlint CLI
npm install -g markdownlint-cli

# Analise seu arquivo
markdownlint documento.md

Se você usa VS Code: instale a extensão "markdownlint" para validação em tempo real.

Use uma pré-visualização que corresponda ao formato de saída

A pré-visualização do seu editor e a saída do conversor usam engines de renderização diferentes. O que fica bonito no VS Code pode quebrar no Word. Sempre faça uma conversão de teste antes da exportação final.

Padronize seu estilo Markdown

Escolha convenções e mantenha-as:

• Indentação: 4 espaços para aninhar
• Quebras de linha: Uma linha em branco entre blocos
• Blocos de código: Sempre cercados (não indentados), sempre com tag de linguagem
• Imagens: Formato de caminho consistente (todos relativos ou todos absolutos)
• Tabelas: Pipes no início e no final de cada linha

Se você está começando com as convenções de Markdown, nosso guia de sintaxe básica de Markdown cobre cada elemento em detalhe. Para funcionalidades avançadas como notas de rodapé e listas de tarefas, veja o guia de sintaxe estendida.

Mantenha um documento de teste

Tenha um arquivo Markdown com um exemplo de cada elemento que você usa — tabelas, blocos de código, fórmulas, diagramas, listas aninhadas, notas de rodapé, emoji. Passe-o pelo seu conversor sempre que atualizar suas ferramentas. Isso detecta regressões antes que afetem documentos reais.

---

Quando usar cada conversor

Ferramentas diferentes resolvem problemas diferentes:

---

Perguntas frequentes

P: Por que minha tabela Markdown quebra ao converter para Word? R: A causa mais comum é sintaxe de pipes inconsistente — pipes iniciais/finais faltando ou uma linha de separação que não bate com o número de colunas. Valide a sintaxe da sua tabela em uma pré-visualização Markdown antes de converter.

P: Como manter o destaque de sintaxe nos blocos de código ao converter para Word? R: Sempre especifique a linguagem depois das crases triplas de abertura (por exemplo, ```python). Depois use um conversor como o MarkFlow que preserva o destaque na saída Word.

P: Por que minhas imagens estão faltando depois de converter Markdown para Word? R: O conversor não consegue resolver os caminhos das suas imagens. Use URLs absolutas para imagens remotas, ou use uma ferramenta como o MarkFlow que lida com caminhos relativos quando você faz upload do arquivo .md com a pasta de imagens.

P: Posso converter fórmulas LaTeX para Word sem perder a formatação? R: Sim, mas você precisa de um conversor com suporte a LaTeX. O MarkFlow, Pandoc (com flags de matemática) e Typora renderizam LaTeX corretamente. Conversores básicos vão mostrar o código-fonte LaTeX como texto puro.

P: Por que os diagramas Mermaid aparecem como código no meu documento convertido? R: A maioria dos conversores não executa JavaScript, que é o que o Mermaid precisa. Use o MarkFlow para renderização automática do Mermaid, ou pré-renderize os diagramas como imagens usando o Mermaid Live Editor.

P: Como corrigir a indentação de listas aninhadas na saída Word? R: Use exatamente 4 espaços por nível de aninhamento no seu Markdown. Evite misturar tabs e espaços. Se o problema persistir, tente outro conversor — alguns lidam melhor com listas aninhadas do que outros.

---

Recursos relacionados

• Conversor de Markdown para Word — Converta com suporte completo de formatação
• Conversor de Markdown para PDF — Gere PDFs prontos para impressão
• Conversor de Markdown para HTML — Exporte HTML limpo e semântico
• Guia de sintaxe básica de Markdown — Domine os fundamentos
• Guia de sintaxe estendida de Markdown — Funcionalidades avançadas e extensões GFM
• Guia completo de Markdown para Word — Fluxo de trabalho completo de conversão