Por que converter Markdown para HTML
Markdown é uma linguagem de marcação leve, amigável para quem escreve, mas os navegadores só entendem HTML. O conteúdo escrito em Markdown, para ser exibido em uma página web, precisa ser convertido em HTML.
Cenários comuns:
- Publicação de artigos em blogs
- Renderização de sites de documentação
- Exibição de README
- Editores de rich text exportando HTML
Correspondência de sintaxe entre Markdown e HTML
Títulos
Markdown:
# Título 1
## Título 2
### Título 3
HTML:
<h1>Título 1</h1>
<h2>Título 2</h2>
<h3>Título 3</h3>
Parágrafo
Markdown: parágrafos de texto separados por uma linha em branco.
HTML: <p>parágrafo</p>
Ênfase
Markdown:
**negrito**
*itálico*
~~tachado~~
HTML:
<strong>negrito</strong>
<em>itálico</em>
<del>tachado</del>
Link
Markdown:
[texto do link](https://example.com)
HTML:
<a href="https://example.com">texto do link</a>
Imagem
Markdown:
HTML:
<img src="image.png" alt="texto alternativo">
Lista
Markdown lista não ordenada:
- Item 1
- Item 2
HTML:
<ul>
<li>Item 1</li>
<li>Item 2</li>
</ul>
Markdown lista ordenada:
1. Primeiro item
2. Segundo item
HTML:
<ol>
<li>Primeiro item</li>
<li>Segundo item</li>
</ol>
Código
Markdown código inline:
Isto é `code` código inline
HTML: Isto é <code>code</code> código inline
Markdown bloco de código:
bloco de código
HTML:
<pre><code>bloco de código</code></pre>
Com destaque de linguagem:
```javascript
const x = 1;
Após a conversão, inclui marcação de destaque de sintaxe (requer biblioteca de destaque).
### Citação
Markdown:
Isto é uma citação
HTML:
```html
<blockquote>Isto é uma citação</blockquote>
Linha divisória
Markdown:
---
HTML:
<hr>
Tabela
Markdown:
| Nome | Idade |
| ----- | ----- |
| Tom | 25 |
HTML:
<table>
<thead>
<tr><th>Nome</th><th>Idade</th></tr>
</thead>
<tbody>
<tr><td>Tom</td><td>25</td></tr>
</tbody>
</table>
Sintaxe estendida
O Markdown padrão (CommonMark) não inclui os recursos abaixo, mas a maioria dos analisadores os suporta:
Lista de tarefas
- [x] Concluído
- [ ] Não concluído
HTML:
<ul>
<li><input type="checkbox" checked disabled> Concluído</li>
<li><input type="checkbox" disabled> Não concluído</li>
</ul>
Notas de rodapé
Texto[^1]
[^1]: Conteúdo da nota de rodapé
Tachado
~~tachado~~
Auto-link
URLs são convertidas automaticamente em links (sem precisar escrever ).
Listas de definição, sumário, fórmulas, etc.
Alguns analisadores suportam, com compatibilidade variável.
Pontos de atenção na conversão
Perda de estilo
A conversão de Markdown para HTML gera apenas tags, sem estilos. O efeito de exibição depende do CSS:
- Tamanho e espaçamento dos títulos
- Recuo e marcadores das listas
- Fundo e fonte dos blocos de código
- Bordas das tabelas
Após converter, é preciso adicionar CSS para ficar bonito.
Segurança contra XSS
O Markdown permite incorporar HTML. Ao converter Markdown fornecido pelo usuário em HTML, tags como <script> são preservadas, causando XSS.
Práticas seguras:
- Use Markdown puro (desative HTML incorporado)
- Após converter para HTML, filtre tags perigosas com uma biblioteca de sanitize
- Permita Markdown apenas de fontes confiáveis
Caracteres de escape
Caracteres especiais do Markdown (, #, _, ) precisam de escape. Escrever *no Markdown exibe um asterisco; após converter para HTML, é`, não uma tag.
Caminho das imagens
Imagens com caminho relativo no Markdown mantêm o caminho após a conversão para HTML. Ao mudar de diretório para exibição, ajuste o caminho.
Links de âncora
Títulos do Markdown geram âncoras automaticamente (id). Analisadores diferentes têm regras distintas; preste atenção ao vincular âncoras.
Ferramentas de conversão
Conversão online
Cole o Markdown e a ferramenta gera o HTML. Ideal para conversão única.
Use a ferramenta Markdown para HTML:
- Cole o conteúdo Markdown
- A ferramenta analisa e converte
- Gera o código HTML
- Copie e use
Conversão no navegador, o conteúdo não é enviado.
Integração com editores
Editores como VS Code e Typora trazem pré-visualização de Markdown para HTML integrada.
Conversão por programa
Em JavaScript, use as bibliotecas marked ou markdown-it. Em Python, use markdown ou mistune.
Dicas de conversão
Padronize o estilo Markdown
Diferentes dialetos do Markdown (CommonMark, GFM, MDX) podem gerar resultados distintos. A equipe deve padronizar um dialeto.
Pré-visualização e validação
Após converter, pré-visualize no navegador e verifique:
- A hierarquia dos títulos está correta
- O aninhamento das listas está normal
- O bloco de código está com destaque
- A tabela está alinhada
- A imagem aparece
- O link é clicável
CSS de apoio
Prepare um CSS de renderização de Markdown; aplique-o ao HTML gerado para uma exibição bonita.
Preserve o Markdown original
O HTML é o resultado da renderização; o Markdown é o arquivo-fonte. Preserve o Markdown para edições futuras e regenere o HTML sempre que necessário.
Perguntas frequentes
Estilo incorreto após a conversão
O HTML não tem CSS. Adicione uma folha de estilos de renderização de Markdown.
Bloco de código sem destaque
É necessária uma biblioteca de destaque de sintaxe (como highlight.js ou Prism). Se a ferramenta de conversão integra o destaque depende da configuração.
Tabela desalinhada
A sintaxe de tabela do Markdown não é estrita (número de colunas pode não corresponder). Verifique o formato da tabela antes de converter.
Caracteres especiais exibidos de forma anormal
Caracteres como < > & no Markdown têm significado especial em HTML. Devem ser escapados para < > &.
Resumo
A conversão de Markdown para HTML tem como núcleo o mapeamento de correspondência de sintaxe. Atenção ao CSS de apoio, à segurança contra XSS e ao escape de caracteres especiais. A ferramenta Markdown para HTML do DocsAll roda no navegador, sem enviar o conteúdo para fora.