Markdown para HTML

O Markdown para HTML é uma ferramenta gratuita que converte excertos de Markdown em código HTML puro, pronto a usar em sites, sistemas de gestão de conteúdos e fluxos de trabalho de desenvolvimento.

O que é convertido de Markdown para HTML?

A ferramenta transforma a formatação Markdown nos elementos HTML correspondentes. Um título passa a ser um elemento de título, uma ligação passa a ser um elemento de âncora e uma lista com marcas passa a ser uma lista não ordenada com os respetivos itens.

Markdown é um formato de marcação em texto simples, muito utilizado em ficheiros README, documentação técnica, descrições de problemas e conteúdos para sites estáticos. A conversão para HTML é útil quando o destino exige HTML em vez de Markdown, como acontece num modelo de site, num sistema de correio eletrónico ou num campo de um sistema de gestão de conteúdos.

Existem vários dialetos de Markdown. O CommonMark, o GitHub Flavored Markdown e os analisadores específicos de determinadas aplicações podem tratar de forma diferente as tabelas, as listas de tarefas, as quebras de linha e o HTML incorporado. A informação disponível sobre a ferramenta não indica um dialeto específico. Por isso, antes de usares o resultado, verifica qualquer sintaxe que vá além de títulos, parágrafos, ligações e listas comuns.

Como converto Markdown em HTML?

Introduz o texto original no campo Markdown, executa a conversão e consulta ou copia o código gerado no campo HTML.

1. Cola um excerto completo, em vez de apenas parte de um marcador de formatação.
2. Converte o texto e verifica a estrutura dos elementos no HTML devolvido.
3. Testa as ligações, as listas aninhadas e os blocos de código na aplicação que os vai apresentar.
4. Aplica os estilos do site separadamente se o destino ainda não tiver CSS adequado.

A conversão é efetuada no servidor. O conteúdo introduzido é enviado para o servidor através de HTTPS e não é armazenado. Como o texto sai do teu dispositivo para ser processado, não envies credenciais, chaves privadas nem material confidencial quando a política da tua organização proibir a utilização de ferramentas executadas no servidor.

Como devo interpretar o HTML devolvido?

Lê o resultado como código HTML puro, composto por elementos que representam a estrutura do Markdown. Podes inseri-lo numa página, num modelo ou num campo de conteúdo existente, mas não se trata necessariamente de um documento HTML completo com doctype, metadados, estilos e scripts.

Num exemplo simples de um título, a entrada em texto simples é:

# Release notes

O resultado HTML convencional é:

<h1>Release notes</h1>

Uma entrada com uma lista curta é:

- Alpha

- Beta

A estrutura correspondente é uma lista não ordenada com dois elementos de lista:

<ul>

<li>Alpha</li>

<li>Beta</li>

</ul>

A maioria dos erros de Markdown não gera erros formais do analisador. Um marcador de formatação sem correspondência, um recuo incorreto ou a falta de um espaço depois de um marcador de lista pode simplesmente aparecer como texto normal. Se o HTML devolvido parecer válido, mas a estrutura estiver errada, compara os elementos da saída com a hierarquia pretendida para o documento.

• Confirma que os títulos usam o nível esperado e não saltam desnecessariamente de um nível para outro.
• Verifica se os itens das listas aninhadas têm um recuo consistente no Markdown original.
• Examina os destinos das ligações antes de publicares, sobretudo quando processares conteúdos de terceiros.
• Revê cuidadosamente os blocos de código delimitados, porque um delimitador por fechar pode abranger todo o resto do documento.
• Procura HTML puro no conteúdo original, pois diferentes implementações de Markdown podem preservá-lo, convertê-lo em entidades ou rejeitá-lo.

Detalhes práticos da conversão

A conversão de Markdown altera a estrutura, não a língua do texto. Letras acentuadas, alfabetos não latinos, números e sinais de pontuação comuns podem permanecer como conteúdo textual dentro dos elementos gerados. Os caracteres com significado especial em HTML podem ter de ser codificados como entidades quando se destinam a aparecer literalmente, em vez de constituírem marcação.

Os espaços e as linhas em branco podem afetar a análise. É habitual uma linha em branco separar parágrafos, enquanto o recuo pode criar uma lista aninhada ou um bloco de código. O tratamento das quebras de linha também varia entre dialetos de Markdown, pelo que uma única mudança de linha no conteúdo original nem sempre produz uma quebra de linha visível em HTML.

Uma entrada vazia não contém uma estrutura de documento relevante para converter. Para entradas muito extensas, poderá ser preferível usar um processo de compilação local, no qual o conteúdo possa ser controlado por versões, testado e convertido de forma consistente com o mesmo analisador utilizado em produção. Nenhum conversor consegue determinar se o nível de um título, o destino de uma ligação ou a hierarquia de uma lista está semanticamente correto para o teu projeto.

Quando vale a pena converter Markdown em HTML?

A conversão é útil quando um sistema posterior aceita HTML, mas o conteúdo original está escrito ou é fornecido em Markdown. Entre os casos habituais estão a verificação de documentação de terceiros antes da importação, a resolução de problemas na compilação de um site estático, a preparação de notas de lançamento para um editor que só aceita HTML ou a revisão da marcação gerada antes da publicação.

Em geral, não vale a pena converter Markdown em HTML quando o conteúdo só será lido por uma máquina e o Markdown já funciona no formato exigido. Da mesma forma, converter Markdown numa fase inicial de um fluxo de trabalho pode dificultar alterações posteriores se os autores tiverem de continuar a trabalhar em Markdown.

Não minifiques o HTML enquanto estiveres a resolver problemas de estrutura. Uma marcação legível facilita a identificação de elementos inesperados e de estruturas aninhadas no local errado. Depois de verificares a saída e de esta estar pronta para produção, podes usar o Minificador de HTML para reduzir os espaços em branco desnecessários.

Perguntas frequentes

O HTML convertido inclui estilos CSS?

O HTML descreve a estrutura, enquanto o CSS controla a maior parte da apresentação. Um elemento de título pode ter um aspeto diferente em cada site porque os estilos são fornecidos pelo navegador, pela aplicação ou pelo tema. Adiciona ou reutiliza CSS no destino, em vez de esperares que o Markdown original defina o aspeto final.

Posso converter tabelas e listas de tarefas em Markdown?

O suporte depende do dialeto de Markdown usado pelo analisador. As tabelas e as caixas de seleção das listas de tarefas são extensões comuns, não sintaxe Markdown universal. Converte uma pequena amostra representativa e verifica os elementos devolvidos antes de dependeres destas funcionalidades num documento maior.

É seguro converter Markdown de uma fonte não fidedigna?

Continua a tratar Markdown de uma fonte não fidedigna como conteúdo não fidedigno depois da conversão. Dependendo do analisador e do destino, o HTML incorporado ou os esquemas de ligação inseguros podem exigir sanitização. Este conversor altera o formato, mas a conversão, por si só, não deve ser considerada um filtro de segurança.

Posso colar o HTML no WordPress ou noutro CMS?

Normalmente, sim, desde que o editor tenha uma vista de HTML ou de código e permita os elementos devolvidos. Alguns sistemas de gestão de conteúdos sanitizam a marcação colada, removem atributos não suportados ou alteram o espaçamento entre parágrafos. Pré-visualiza o conteúdo e verifica a versão guardada, pois o CMS pode transformá-lo depois do envio.

Porque é que o meu bloco de código aparece incorretamente?

Confirma que os delimitadores de abertura e de fecho correspondem e aparecem em linhas separadas. Os blocos de código com recuo também podem deixar de funcionar quando o recuo das listas envolventes é inconsistente. Se precisares de realce de sintaxe, o destino terá de reconhecer o identificador da linguagem e fornecer o seu próprio script ou os estilos de realce.

Devo guardar o Markdown depois da conversão?

Guarda o Markdown quando este for a versão original editável. Armazena o HTML gerado separadamente ou volta a criá-lo durante a compilação, para que as alterações posteriores não divirjam entre os dois formatos. Antes de publicares, valida as ligações e verifica o fragmento no destino real, em vez de te baseares apenas no código puro.