Converter Markdown em HTML

Um fragmento ou uma página, e qual você quer

Existem dois resultados úteis, e um não substitui o outro. Um fragmento é só a marcação convertida — títulos, parágrafos, listas, links — sem a estrutura de documento, que é o que você quer quando o resultado vai para um template, um campo de CMS ou outra página. Uma página completa acrescenta o doctype, um head, a declaração do conjunto de caracteres e uma folha de estilos, então abre sozinha e já tem boa aparência. Colar uma página completa em um CMS gera um documento dentro de outro documento; abrir um fragmento no navegador mostra texto sem estilo.

A conversão cobre o conjunto estendido de Markdown amplamente aceito: títulos, ênfase, listas, links, imagens, citações, tabelas, blocos de código com destaque de sintaxe, listas de tarefas, texto riscado e notas de rodapé. Os títulos recebem identificadores derivados do próprio texto, então dá para criar links direto para eles — as âncoras que tornam uma documentação longa usável.

O HTML bruto dentro do Markdown passa adiante, o que faz parte da especificação e merece atenção: significa que um arquivo Markdown de origem não confiável pode conter uma tag script, e convertê-lo gera uma página com esse script. Nunca renderize Markdown de desconhecidos sem sanitizar o HTML depois — a conversão não é uma barreira de segurança e nunca teve essa intenção.

Duas coisas saem como blocos de código em vez de renderizadas, de propósito. Fórmulas matemáticas em notação LaTeX precisam de uma biblioteca de composição tipográfica, e diagramas Mermaid precisam de um renderizador de diagramas — cada um é uma dependência considerável, e uma equação renderizada errado é pior do que uma que aparece como código. Uma página completa usa fontes comuns do sistema em vez de baixar alguma, então funciona offline e fica um pouco diferente no Windows, no macOS e no Linux.

Quando você precisa de outra coisa

O Pandoc faz o que ficou de fora aqui e muito mais: pandoc in.md -o out.html --mathjax --standalone --toc renderiza matemática direito, gera um sumário e aceita um template para o resultado combinar com o seu próprio site. Ele também converte de e para cerca de quarenta outros formatos, e por isso vale a pena instalar uma vez.

Para um site, e não um arquivo, use um gerador em vez de converter página por página. Hugo, Eleventy, Jekyll e MkDocs transformam uma pasta de Markdown em um site com navegação, busca e estilo consistente, e o reconstroem sempre que o conteúdo muda — que é o trabalho de verdade sempre que existe mais de um documento.