Visualizar Markdown

Qual Markdown e por que o HTML é higienizado

Markdown é uma família, não uma única especificação, e o dialeto usado aqui é o conjunto amplamente aceito do GitHub: títulos, ênfase, listas, links, imagens, citações, tabelas, blocos de código cercados com realce de sintaxe, listas de tarefas, tachado, notas de rodapé e links automáticos. É isso que quase todo mundo escreve e o que um README vai conter. Dialetos mais exóticos e os plugins personalizados que um site específico adiciona — blocos de aviso, shortcodes, templates — não são suportados, então um documento escrito para um gerador específico pode mostrar parte da sua sintaxe literalmente.

O HTML bruto é renderizado, mas higienizado antes, e é esta a parte que vale entender. O Markdown permite HTML de propósito, o que significa que um arquivo Markdown de qualquer origem pode conter uma tag script, um manipulador de eventos embutido, um iframe ou um link javascript:. Renderizar isso como está executaria o código de um desconhecido na sua sessão só porque você colou o README dele para dar uma olhada. Tudo o que é executável é removido antes de qualquer coisa ser exibida, então a formatação sobrevive e o código não.

Essa é uma lição geral, não um detalhe desta página. Qualquer sistema que renderiza Markdown enviado por usuários — uma caixa de comentários, uma wiki, um chamado de suporte — está renderizando HTML enviado por usuários, a menos que o higienize, e “é só Markdown” é como isso passa despercebido. Converter o Markdown não é uma barreira de segurança; a etapa de higienização é.

O que você recebe é uma visualização do conteúdo, não de um site específico. GitHub, GitLab e um gerador de documentação aplicam cada um sua própria folha de estilos, âncoras de títulos e extensões, então o mesmo arquivo fica diferente em cada um — a estrutura mostrada aqui é aquilo em que todos concordam. Nada é buscado, então imagens referenciadas por um endereço da web só carregam se esse servidor permitir, e caminhos relativos para arquivos de um repositório não podem ser resolvidos de jeito nenhum.

Quando você precisa de outra coisa

Para um README que você está escrevendo de verdade, visualize-o onde ele vai ficar. O próprio editor do GitHub mostra a visualização com a renderização, as extensões e as âncoras exatas, e o GitHub CLI — gh markdown-preview — faz isso localmente com o mesmo renderizador. Para documentação, o próprio gerador (MkDocs, Docusaurus, Hugo) tem uma visualização com recarregamento automático que mostra o estilo e a navegação reais, que é o que o leitor vai ver.

Para editar, e não só conferir, um editor de Markdown com painel ao vivo — Obsidian, Typora, VS Code com a visualização embutida — é melhor do que colar em uma página toda vez, porque a visualização atualiza enquanto você digita e o arquivo fica onde está. Esta página é para ler o Markdown de outra pessoa, ou para dar uma olhada rápida em algo que enviaram para você.