Conversor de Markdown para HTML

Como usar este conversor

1. Cole seu Markdown. A ferramenta aceita CommonMark mais as extensões GFM mais comuns, tabelas, código cercado com dicas de linguagem, riscado, autolinks e itens de lista de tarefas.
2. Observe a conversão ao vivo. O painel direito mostra a saída HTML bruta enquanto você digita; o painel de pré-visualização abaixo a renderiza visualmente.
3. Copie o HTML. Use o botão Copiar HTML para pegar a saída pronta para colar em seu CMS, cliente de e-mail, template de gerador de sites estáticos ou em qualquer outro lugar que aceite HTML.

Uma breve história do Markdown

Markdown foi criado por John Gruber, o escritor por trás do weblog Daring Fireball, com substancial feedback de design de Aaron Swartz. O primeiro lançamento público, versão 1.0, foi anunciado no site de Gruber em 9 de março de 2004; a versão 1.0.1, o lançamento de referência canônico, seguiu em 17 de dezembro de 2004 e ainda é a versão linkada de daringfireball.net/projects/markdown. Markdown era duas coisas ao mesmo tempo desde o início: uma sintaxe de formatação em texto puro e o script Perl original que o convertia em HTML. O objetivo declarado de Gruber era que o texto fonte deveria ser legível como está, um documento Markdown aberto em um editor de texto puro deveria parecer um e-mail formatado pensativamente, não uma sopa de tags. Essa restrição de legibilidade é a linha filosófica que separa Markdown de formatos baseados em XML e de marcação mais pesada como LaTeX, e é a razão pela qual cada extensão posterior teve que argumentar por si mesma em termos de o quanto perturba a fonte. Aaron Swartz havia escrito anteriormente uma marcação leve relacionada chamada atx (2002), que contribuiu para o estilo de cabeçalho # e ## agora familiar, às vezes ainda chamado «cabeçalhos estilo atx» dentro das especificações de parser.

CommonMark, consertando a subespecificação

A descrição de sintaxe original de Gruber de 2004 era famosamente informal, um documento em prosa com exemplos, não uma gramática. Deixava dezenas de casos limite não especificados, e Gruber nunca lançou um parser de referência além de seu script Perl, cujo comportamento era idiossincrático de maneiras que outros implementadores tinham que copiar ou substituir. O resultado no início dos anos 2010 foi que GitHub, Reddit, Stack Overflow, Pandoc e o parser Discount C renderizavam a mesma fonte Markdown ligeiramente diferente. Em 2012, o cofundador do Stack Overflow Jeff Atwood e o autor do Pandoc John MacFarlane começaram um esforço para escrever uma especificação real e testável. O projeto foi lançado publicamente em setembro de 2014 como «Standard Markdown»; em poucos dias Gruber se opôs ao nome em e-mail privado, Atwood escreveu um post público explicando a mudança, e o projeto foi renomeado «CommonMark». O primeiro lançamento numerado veio em 25 de outubro de 2014. A versão publicada atual é CommonMark 0.31.2, lançada em 28 de janeiro de 2024. A especificação CommonMark é incomum por ser ela mesma um documento CommonMark, com mais de 600 casos de teste executáveis em linha; um parser reivindica conformidade passando esses testes. GitHub Flavored Markdown (GFM), a especificação formal na versão 0.29-gfm datada de 6 de abril de 2019, define cinco extensões em cima de CommonMark: tabelas, itens de lista de tarefas, riscado, autolinks para URLs simples, e HTML cru proibido (uma restrição de segurança que remove tags perigosas do HTML fornecido pelo autor).

Os principais parsers

marked.js foi criado por Christopher Jeffrey em 2011 e tem sido mantido pela organização GitHub markedjs desde 2018, um design lexer-depois-parser de uma única passagem que prioriza velocidade bruta; ~36k estrelas e o projeto Markdown mais estrelado no GitHub. É o parser que esta ferramenta usa para a conversão. markdown-it foi lançado em 2014 por Vitaly Puzrin e Alex Kocharin, anunciando 100% de conformidade CommonMark com alternâncias GFM opcionais mais um ecossistema de plugins agressivo (markdown-it-footnote, markdown-it-emoji, markdown-it-attrs, markdown-it-anchor e várias centenas de outros). É o parser usado pela pré-visualização Markdown embutida do VS Code, pela interface web do GitLab e pelo Eleventy. remark / unified.js não é um único parser mas um framework de transformação de árvore, o coletivo unified define uma especificação de árvore sintática abstrata chamada mdast (Markdown AST); remark parseia Markdown em mdast, plugins manipulam a árvore, e remark-rehype converte mdast em hast (HTML AST) para emissão. Mais lento que marked mas vastamente mais composável; usuários notáveis incluem Prettier, Gatsby, MDN e o linter de linguagem inclusiva alex. Pandoc, lançado por John MacFarlane em 10 de agosto de 2006, é o conversor universal de documentos, escrito em Haskell, parseia cerca de 30 formatos de entrada, renderiza em cerca de 40 formatos de saída; onipresente em publicações acadêmicas e técnicas.

O pipeline MD-para-HTML, mecanicamente

Um parser Markdown tipicamente funciona em duas passagens. O parsing em nível de bloco divide a entrada em estruturas de bloco, parágrafos, cabeçalhos, listas, cercas de código, citações em bloco, regras horizontais, tabelas. Os limites de bloco são determinados por linhas em branco e indentação; acertá-los é a maior parte do que torna um parser CommonMark correto. O parsing inline então percorre o conteúdo de cada bloco e combina a sintaxe inline: ênfase (*itálico*, **negrito**), links ([texto](url)), spans de código inline (`código`), imagens (![alt](url)), riscado (~~texto~~ em GFM), e autolinks explícitos (<https://example.com>). O parsing de ênfase inline é a parte mais cheia de detalhes de qualquer especificação Markdown, CommonMark dedica várias páginas da especificação e dezenas de casos de teste a especificar quando *foo*bar* deveria produzir <em>foo</em>bar* versus *foo<em>bar</em>. O parser então renderiza cada token como o elemento HTML correspondente e concatena os resultados. Impressão bonita, indentação e destaque de sintaxe de blocos de código são sobrepostos pelas opções de renderização.

Por que converter MD para HTML em primeiro lugar?

• Importações CMS. Muitos CMSs headless (Contentful, Sanity, Wagtail, Ghost) aceitam HTML mas não Markdown. Redigir em Markdown e converter uma vez no momento da publicação mantém a experiência de edição agradável.
• Composição de e-mail. Os clientes de e-mail renderizam HTML; a maioria não renderiza Markdown. Plataformas de newsletter (Mailchimp, ConvertKit, Substack) tipicamente aceitam HTML colado em seu editor. Converta seu rascunho, cole, envie.
• Rascunhos de posts de blog. Algumas instalações antigas do WordPress sem o plugin Markdown exigem HTML no corpo do post; algumas páginas de loja Shopify e Webflow aceitam HTML em seus campos de texto enriquecido.
• Snippets de gerador de sites estáticos. Quando você precisa de um pedaço HTML inline para um shortcode Hugo, um template Eleventy ou um arquivo MDX Next.js, converter Markdown em um único fragmento HTML é mais rápido do que lutar com o pipeline de conversão próprio do SSG.
• Compartilhamento de notas renderizadas. Colar Markdown «renderizado» no Slack, Notion, Linear, ClickUp ou outros destinos de texto enriquecido às vezes quer HTML na área de transferência em vez de Markdown cru.
• Arquivamento de documentação. Armazenar o HTML renderizado ao lado da fonte Markdown significa que seu arquivo é legível por humanos em um navegador sem parser, útil para preservação a longo prazo.

Opções de saída que vale a pena conhecer

Diferentes usos posteriores querem coisas diferentes do HTML convertido. Documento completo vs fragmento. Um documento HTML completo inclui <!DOCTYPE html>, <html>, <head> com metadados, e um wrapper <body>, apropriado quando você vai salvar o arquivo como .html e abri-lo em um navegador. Um fragmento é apenas o conteúdo do corpo, sem wrapper, apropriado quando você vai colar em um campo CMS que já fornece a estrutura do documento. Esta ferramenta emite fragmentos por padrão; envolva com seu próprio boilerplate se precisar de um documento completo. Sanitização. Por padrão, os parsers Markdown passam HTML cru sem alteração, então se sua fonte contém <script>alert(1)</script>, essa tag script aparecerá na saída. Para documentos que vão para um sistema multiusuário, passe a saída por DOMPurify (Cure53, iniciado em fevereiro de 2014) antes de injetar no DOM. Para uso pessoal pontual, a saída crua está bem. IDs de cabeçalho. Gerar atributos id em cabeçalhos (slugificados a partir do texto do cabeçalho) permite que você construa uma tabela de conteúdo com links de âncora. O algoritmo de slug exato difere entre plataformas, GitHub usa uma regra, MkDocs outra, marked.js uma terceira, então os links de âncora podem quebrar quando o conteúdo se move entre sistemas. Quebras de linha rígidas. CommonMark requer ou dois espaços ao final de uma linha ou uma barra invertida para forçar um <br>; algumas plataformas (Discord, issues do GitHub) tratam quebras de linha únicas como quebras. A escolha depende do estilo esperado da sua fonte.

Armadilhas comuns

• Conversão de aspas inteligentes. Alguns parsers (ou camadas de pós-processamento como o próprio SmartyPants do Gruber) substituem aspas retas por aspas tipográficas curvas por padrão. Se você precisa que aspas retas sejam preservadas (porque sua saída está sendo analisada como código), verifique se essa transformação está desativada.
• Sensibilidade ao espaço em branco do marcador de lista. Misturar - e * e + na mesma lista, indentar parágrafos de continuação de lista menos do que o marcador requer, ou colocar uma linha em branco entre itens de lista pode transformar uma lista apertada em uma lista solta (cada item envolvido em tags <p>). A diferença visual na saída é dramática.
• Excesso de zelo do autolink. O autolinking estilo GFM transforma qualquer URL crua em link, o que geralmente é o que você quer, mas pode mutilar URLs contendo parênteses (URLs da Wikipedia especialmente) ou pontuação no final.
• Tabelas que precisam escape. Caracteres pipe dentro de células de tabela devem ser escapados como \|, caso contrário são lidos como separadores de coluna. Pega qualquer um tentando colocar um exemplo de código de uma linha dentro de uma célula.
• Markdown e HTML misturados. Markdown foi projetado para passar HTML arbitrário, então jogar um <div class="callout"> em um arquivo Markdown funciona. Mas no momento em que você coloca sintaxe Markdown dentro de um bloco HTML, os parsers divergem: CommonMark trata a maioria dos blocos HTML como opacos; Markdown Extra introduziu markdown="1" para optar ao parsing aninhado.
• IDs de cabeçalho entre plataformas. Diferentes algoritmos de slugificação produzem diferentes fragmentos de âncora para o mesmo cabeçalho; links intra-documento podem quebrar quando o conteúdo se move entre sistemas.

Esta ferramenta vs o pré-visualizador Markdown

Absolutool entrega duas ferramentas relacionadas que se sobrepõem no mesmo parser. O pré-visualizador Markdown é para edição ao vivo, escreva Markdown à esquerda, veja a saída visual renderizada à direita, sem conceito de «a saída HTML». Este conversor Markdown-para-HTML é para conversão pontual, cole Markdown, copie HTML cru, cole em seu CMS ou cliente de e-mail. Use o pré-visualizador quando estiver redigindo e precisar de feedback visual; use este conversor quando tiver Markdown finalizado e precisar de HTML que possa transportar para outro lugar. Ambas as ferramentas usam marked.js por baixo dos panos e aceitam o mesmo dialeto CommonMark + GFM, então o comportamento de conversão é idêntico entre elas.

Privacidade: por que somente-navegador importa aqui

Rascunhos de escrita não publicada, posts de blog em progresso, documentação interna, entregáveis de cliente sob NDA, capítulos de manuscritos, artigos acadêmicos, são exatamente o tipo de texto que você não quer enviar para um serviço de terceiros. Conversores Markdown do lado servidor exigem enviar o documento inteiro para um endpoint remoto, o que significa que ele fica nos logs do servidor, possivelmente em um cache CDN, possivelmente em um pipeline de analytics, possivelmente em um backup. Para texto publicado, a questão é discutível. Para trabalho de rascunho, a arquitetura importa. Esta ferramenta executa todo o pipeline no seu navegador via JavaScript e marked.js. O Markdown nunca cruza a rede, verifique na aba Rede do DevTools enquanto digita, ou tire a página do ar (modo avião) após carregar e confirme que o conversor ainda funciona. Seguro para rascunhos confidenciais, entregáveis de cliente, capítulos de manuscrito sob NDA, memorandos internos ou qualquer outra coisa que você não queira ver copiada no disco rígido de um estranho.

Perguntas frequentes

Que dialeto Markdown este conversor suporta?

CommonMark com as extensões GFM mais comuns habilitadas, tabelas (delimitadas por pipes com alinhamento : opcional), blocos de código cercados com dicas de linguagem, riscado via ~~texto~~, autolinks para URLs simples, e itens de lista de tarefas via [ ] e [x]. Cabeçalhos, negrito, itálico, links, imagens, listas, citações em bloco, regras horizontais e código inline funcionam todos como você esperaria no GitHub. O renderizador é marked.js, o mesmo parser que o pré-visualizador Markdown usa.

Isto suporta GitHub Flavored Markdown (GFM)?

Sim, tabelas com pipes, blocos de código cercados com dicas de linguagem, listas de tarefas, autolinks e riscado funcionam todos. Se uma extensão GFM não está renderizando, verifique se a entrada segue as regras de sintaxe CommonMark/GFM: linhas em branco em torno de elementos de bloco, contagens de backticks correspondentes em blocos de código cercados, exatamente dois espaços no final (ou uma barra invertida) para quebras de linha rígidas. A causa mais comum de «GFM não funciona» é um editor que remove espaços no final ao salvar, o que mata a sintaxe de quebra rígida.

A saída terá a mesma aparência no GitHub?

O HTML estrutural, parágrafos, listas, tabelas, cabeçalhos, corresponderá para qualquer entrada que seja CommonMark + GFM válida. Duas camadas diferirão. O GitHub aplica seu próprio tema CSS e destaque de sintaxe, então cores, fontes e espaçamento parecerão diferentes. O GitHub também sobrepõe pós-processamento em cima da especificação, atalhos de emoji (:smile:), menções @user, autolinking de #issue, caminhos de imagem relativos ao repositório, que nenhum conversor conforme à especificação reproduz. O HTML que esta ferramenta emite é portável estruturalmente; a aparência visual depende do CSS no destino.

Devo sanitizar a saída antes de publicar?

Se a fonte puder incluir conteúdo fornecido pelo usuário, sim. Os parsers Markdown passam HTML cru sem alteração, então uma fonte contendo <img src=x onerror="alert(1)"> produzirá essa tag na saída. Para sistemas multiusuário, passe a saída por DOMPurify (Cure53, fevereiro de 2014, o sanitizador JavaScript de facto) antes de injetar no DOM. Para uso pessoal pontual onde a fonte é sua própria escrita, isso não é um problema, o pior que você pode fazer à sua própria página é colar seu próprio HTML.

Posso obter um documento HTML completo com head e body?

Atualmente esta ferramenta emite apenas o fragmento de corpo, o Markdown convertido envolvido em tags HTML semânticas mas não em um documento <html>/<head>/<body> completo. Para salvar como um arquivo .html autônomo, envolva a saída você mesmo: <!DOCTYPE html><html><head><meta charset="utf-8"><title>...</title></head><body>[fragmento]</body></html>. Ou use Pandoc com a flag --standalone para saída totalmente autônoma com CSS dirigido por template.

Meu Markdown é enviado para algum lugar?

Não. A conversão roda inteiramente no seu navegador via marked.js. O Markdown que você cola nunca cruza a rede, verifique na aba Rede do DevTools enquanto digita, ou tire a página do ar (modo avião) após carregar e confirme que o conversor ainda funciona. Seguro para rascunhos confidenciais, entregáveis de cliente sob NDA, capítulos de manuscrito ou qualquer texto que você não queira ver copiado no disco rígido de um estranho.

Ferramentas relacionadas