Truques Markdown: soluções para as funções em falta
Os truques Markdown são fragmentos de HTML e artifícios de sintaxe que acrescentam as funções que a especificação base do Markdown deixa de fora, do texto sublinhado às miniaturas de vídeo clicáveis. Quase todos os truques dependem de uma única condição: o renderizador tem de aceitar HTML inline. O CommonMark deixa passar HTML em bruto por predefinição, pelo que o VS Code, o Obsidian, o Typora e o editor deste site apresentam estas soluções corretamente. As plataformas com sanitização comportam-se de outra forma. O GitHub filtra o resultado através de uma allowlist fixa de tags e apaga todos os atributos style, enquanto o Reddit e o Discord ignoram o HTML por completo. Cada secção abaixo mostra a sintaxe e indica os renderizadores que a mantêm ou removem.
Sublinhar texto
O Markdown não tem sintaxe de sublinhado, por isso, para sublinhar em Markdown, envolva o texto numa tag HTML <ins> ou <u>. A tag <ins> marca texto inserido e aparece sublinhada em todos os principais browsers. O sanitizador do GitHub mantém <ins> e descarta <u>, pelo que <ins> é a escolha portátil para READMEs.
Submit the form <ins>before 30 June</ins> to qualify.
O Obsidian e o Typora renderizam ambas as tags. O Bear e o Simplenote dispensam a via do HTML e oferecem atalhos próprios de sublinhado. No Reddit, as tags aparecem como texto literal, porque o parser descarta o HTML.
Indentar parágrafos
O Markdown elimina os espaços iniciais e converte indentações de 4 espaços em blocos de código, por isso indente um parágrafo com a entidade , o espaço não separável. Cada entidade sobrevive como um espaço visível no resultado. Quatro seguidas imitam uma tabulação clássica.
The opening line of this paragraph sits four spaces in.
As entidades passam por quase todos os renderizadores, incluindo o GitHub, porque são referências a caracteres e não tags. O limite aparece em grande escala. Um documento com dezenas de parágrafos indentados torna-se difícil de ler no código-fonte, e um editor com controlo de modelos, como o iA Writer, trata a indentação de forma mais limpa.
Centrar texto
Para centrar texto Markdown, use a tag <center> ou <p style="text-align:center"> onde o CSS inline sobreviver. O HTML 4.01 tornou a tag <center> obsoleta em 1999, mas os browsers continuam a respeitá-la e a maioria dos renderizadores Markdown deixa-a passar intacta.
<center>Chapter 7</center>
<p style="text-align:center">Chapter 7</p>
O GitHub apaga os atributos style, pelo que a segunda forma falha nessa plataforma. Quem escreve READMEs centra logótipos e badges com <div align="center">, porque o atributo align sobrevive ao sanitizador do GitHub. O Typora e a pré-visualização do VS Code renderizam a versão CSS tal como está escrita.
Colorir texto
O Markdown não oferece qualquer controlo sobre a cor do texto; use <span style="color:#0969da"> onde o CSS for permitido, ou a antiga tag <font color="red"> nos renderizadores que ainda a aceitam.
<span style="color:#0969da">This sentence renders in blue.</span>
<font color="red">This sentence renders in red.</font>
A tag <font> ficou obsoleta em 1999 e os sanitizadores modernos tratam-na sem contemplações. O GitHub remove tanto o atributo style como o atributo color, pelo que nenhuma das formas produz texto colorido num README. Um substituto comum nessa plataforma é um bloco de código delimitado com diff como linguagem, que pinta de verde as linhas que começam com + e de vermelho as que começam com -. O Obsidian e o Typora respeitam a versão com <span>, tal como os sites Hugo e Jekyll que deixam passar HTML em bruto.
Ocultar comentários
Esconda uma nota dos leitores com o truque da referência de ligação [comment]: # ou com um comentário HTML normal. Ambos mantêm o texto no ficheiro de origem e fora da página renderizada.
[everything in this line disappears from the output]: #
<!-- This note also stays hidden. -->
O truque dos parênteses retos aproveita as definições de referência de ligações, uma função base do Markdown, pelo que funciona mesmo onde o HTML está bloqueado. Deixe uma linha em branco acima e abaixo, ou um parágrafo adjacente pode fundir-se com a definição. O comentário HTML é mais fácil de ler, mas permanece no código-fonte da página gerada, onde qualquer utilizador o pode ver. O GitHub aceita ambos os métodos.
Admonitions e caixas de destaque
Crie uma caixa de destaque com um emoji e um rótulo a negrito dentro de um blockquote, ou use a sintaxe de alertas do GitHub, introduzida em 2023.
> [!WARNING]
> This command overwrites all 14 archived backups.
> 💡 **Tip:** Blockquote callouts work in any renderer.
O GitHub suporta 5 tipos de alerta: NOTE, TIP, IMPORTANT, WARNING e CAUTION. Cada um aparece com o seu ícone e cor de destaque em github.com, mas a sintaxe degrada para um blockquote simples em qualquer outro lado. O Obsidian tem um formato de callout próprio, > [!note], adicionado na versão 0.14 em 2022, e o MkDocs com o tema Material usa linhas !!! note. O blockquote com emoji é a única variante com um aspeto aceitável em todas as plataformas.
Redimensionar imagens
Troque a sintaxe de imagem do Markdown por uma tag <img> e defina os atributos width e height em píxeis.
<img src="diagram.png" alt="Deployment diagram" width="480" height="270">
O GitHub mantém os atributos width e height, apesar de remover style="width:50%", pelo que os valores em píxeis são o caminho fiável para READMEs. As dimensões fixas também evitam saltos de layout enquanto a página carrega. Os renderizadores sem suporte de HTML mostram a tag em bruto como texto, por isso mantenha a forma simples  em plataformas como o Reddit.
Legendas de imagens
Adicione uma legenda com as tags <figure> e <figcaption>, ou coloque uma linha em itálico logo por baixo da imagem.
<figure>
<img src="harbor.jpg" alt="Fishing boats at dawn">
<figcaption>Hobart's harbor, photographed in March 2025.</figcaption>
</figure>
*Hobart's harbor, photographed in March 2025.*
Tanto <figure> como <figcaption> constam da allowlist do GitHub, pelo que a versão semântica funciona nos READMEs. A linha em itálico é a alternativa para renderizadores sem HTML. Os leitores de ecrã anunciam-na como texto normal e não como legenda, e é essa a contrapartida da sua portabilidade.
Ligações que abrem num novo separador
As ligações Markdown não podem abrir num novo separador; escreva a âncora em HTML em bruto com target="_blank".
<a href="https://example.com/report" target="_blank" rel="noopener">2026 annual report</a>
Acrescente rel="noopener" para que a nova página não possa executar scripts contra a janela que a abriu. Este truque tem um alcance curto. O GitHub remove o atributo target durante a sanitização, e todas as ligações de um README abrem no mesmo separador de qualquer forma. O truque funciona em geradores de sites estáticos como o Hugo e o Jekyll, que deixam passar o HTML intacto, e é aí que o comportamento de novo separador mais importa.
Símbolos e caracteres especiais
Escreva os símbolos diretamente, já que os ficheiros Markdown são texto Unicode simples, ou use entidades HTML quando um símbolo for difícil de alcançar no teclado. Copie © ou → de qualquer página de referência de caracteres e cole no ficheiro; aparece sem alterações.
| Símbolo | Entidade HTML |
|---|---|
| © direitos de autor | © |
| ® marca registada | ® |
| ™ marca comercial | ™ |
| → seta para a direita | → |
| ° grau | ° |
| € euro | € |
As entidades são convertidas em quase todos os renderizadores, incluindo o GitHub. A única armadilha são os blocos de código, onde © aparece de forma literal porque o código delimitado desativa a descodificação de entidades.
Índice de conteúdos
Construa um índice como lista de marcadores com ligações que apontam para os IDs de âncora dos títulos. O GitHub, o GitLab e a maioria dos outros renderizadores geram um ID para cada título: o texto passa a minúsculas, os espaços tornam-se hífenes e quase toda a pontuação é removida.
- [Underline Text](#underline-text)
- [Resize Images](#resize-images)
- [Embed Videos](#embed-videos)
Um título chamado "Resize Images" recebe a âncora #resize-images. O GitHub também mostra um botão de índice automático nos cabeçalhos dos READMEs desde 2021, pelo que uma lista manual continua a valer a pena em documentos longos noutras plataformas. Verifique as âncoras depois de cada edição de títulos, porque um título renomeado quebra as suas ligações em silêncio.
Incorporar vídeos
O Markdown não consegue incorporar um leitor de vídeo, por isso ligue uma miniatura clicável ao vídeo. O YouTube publica uma miniatura para cada vídeo num URL previsível, o que torna o padrão simples.
[](https://www.youtube.com/watch?v=VIDEO-ID)
Substitua VIDEO-ID pelo código de 11 caracteres do URL do vídeo. A miniatura aparece em qualquer lado onde o Markdown padrão funcione, e um clique abre o vídeo no YouTube. Existem duas melhorias onde a plataforma o permitir. O GitHub aceita carregamentos diretos de ficheiros .mp4 e .mov em issues, pull requests, discussões e ficheiros Markdown desde maio de 2021, e os renderizadores com suporte completo de HTML aceitam um embed <iframe> do YouTube colado.
Perguntas frequentes
Os truques Markdown funcionam no GitHub?
Alguns funcionam. O GitHub mantém <ins>, os atributos width de <img>, <figure>, comentários HTML, entidades e a sua própria sintaxe de alertas, mas remove todos os atributos style e o atributo target. Teste qualquer truque num gist de rascunho antes de depender dele, porque a allowlist do sanitizador pode mudar sem aviso.
Porque é que o meu HTML desapareceu da página renderizada?
O renderizador bloqueia o HTML inline por completo, como fazem o Reddit e o Discord, ou removeu durante a sanitização a tag ou o atributo específico que usou. Consulte a documentação da plataforma à procura de uma allowlist e troque o elemento removido por um permitido, como <div align="center"> no lugar de um atributo style.
Qual é o melhor estilo de comentário, [comment]: # ou <!-- -->?
Use [comment]: # quando a nota tiver de desaparecer por completo, e <!-- --> quando a legibilidade do código-fonte importar mais. A forma com parênteses retos é consumida pelo parser Markdown e nunca chega ao resultado, enquanto um comentário HTML normal fica visível para qualquer utilizador que veja o código-fonte da página.