Truques Markdown: Soluções para Recursos que Faltam
Truques markdown são trechos de HTML e usos criativos da sintaxe que produzem recursos ausentes da especificação básica do markdown, desde texto sublinhado até miniaturas de vídeo clicáveis. Quase todo truque depende de uma condição: o renderizador precisa aceitar HTML embutido. O CommonMark repassa HTML bruto por padrão, então o VS Code, o Obsidian, o Typora e o editor deste site exibem essas soluções corretamente. Plataformas com sanitização se comportam de outra forma. O GitHub filtra a saída por uma lista fixa de tags permitidas e apaga todo atributo style, enquanto Reddit e Discord ignoram HTML por completo. Cada seção abaixo mostra a sintaxe e lista os renderizadores que a mantêm ou removem.
Sublinhar em Markdown
O markdown não tem sintaxe de sublinhado, então envolva o texto em uma tag HTML <ins> ou <u>. A tag <ins> marca texto inserido e aparece sublinhada em todos os principais navegadores. O sanitizador do GitHub mantém <ins> e descarta <u>, o que faz de <ins> a escolha portátil para READMEs.
Submit the form <ins>before 30 June</ins> to qualify.
Obsidian e Typora renderizam as duas tags. Bear e Simplenote dispensam o caminho do HTML e oferecem atalhos próprios de sublinhado. No Reddit, as tags aparecem como texto literal porque o parser da plataforma descarta HTML.
Recuar Parágrafos
O markdown elimina espaços iniciais e converte recuos de 4 espaços em blocos de código, então recue um parágrafo com a entidade de espaço sem quebra . Cada entidade sobrevive como um espaço visível na saída. Quatro delas imitam a tabulação clássica.
The opening line of this paragraph sits four spaces in.
Entidades passam por quase todos os renderizadores, GitHub incluído, porque são referências de caracteres e não tags. O limite aparece em escala. Um arquivo com dezenas de parágrafos recuados fica difícil de ler no código-fonte, e um editor com controle de modelos, como o iA Writer, trata o recuo com mais elegância.
Centralizar Texto Markdown
Para centralizar texto markdown, use a tag <center> ou <p style="text-align:center"> onde o CSS embutido sobrevive. O HTML 4.01 descontinuou a tag <center> lá em 1999, mas os navegadores ainda a respeitam e a maioria dos renderizadores de markdown a repassa sem alterações.
<center>Chapter 7</center>
<p style="text-align:center">Chapter 7</p>
O GitHub apaga atributos style, então a segunda forma falha por lá. Autores de README centralizam logos e selos 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 com CSS exatamente como escrita, direto na tela.
Cor de Texto Markdown
O markdown não oferece controle de cor de texto; use <span style="color:#0969da"> onde CSS é 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> foi descontinuada em 1999 e os sanitizadores modernos a tratam com rigor. O GitHub remove tanto o atributo style quanto o atributo color, então nenhuma das formas produz texto colorido em um README. Um substituto comum por lá é um bloco de código cercado com diff como linguagem, que pinta de verde as linhas iniciadas com + e de vermelho as iniciadas com -. Obsidian e Typora respeitam a versão com <span>, assim como sites em Hugo e Jekyll que repassam HTML bruto.
Ocultar Comentários
Oculte uma anotação dos leitores com o truque de referência de link [comment]: # ou com um comentário HTML padrão. Os dois mantêm o texto no arquivo-fonte e fora da página renderizada.
[everything in this line disappears from the output]: #
<!-- This note also stays hidden. -->
O truque dos colchetes explora as definições de referência de link, um recurso básico do markdown, e por isso funciona até onde o HTML é bloqueado. Deixe uma linha em branco acima e abaixo, ou um parágrafo vizinho pode se fundir à definição. O comentário HTML é mais fácil de ler, mas permanece no código-fonte da página gerada, onde qualquer usuário pode vê-lo. O GitHub aceita os dois métodos.
Admonições e Caixas de Destaque
Crie uma caixa de destaque com um emoji e um rótulo em 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 aceita 5 tipos de alerta: NOTE, TIP, IMPORTANT, WARNING e CAUTION. Cada um aparece com ícone e cor de destaque próprios no github.com, mas a sintaxe degrada para um blockquote comum em qualquer outro lugar. O Obsidian tem um formato de callout separado, > [!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 boa aparência em todos eles.
Redimensionar Imagens
Troque a sintaxe de imagem do markdown por uma tag <img> e defina os atributos width e height em pixels.
<img src="diagram.png" alt="Deployment diagram" width="480" height="270">
O GitHub mantém os atributos width e height mesmo removendo style="width:50%", então valores em pixels são o caminho confiável para READMEs. Dimensões fixas também evitam saltos de layout enquanto a página carrega na tela. Renderizadores sem suporte a HTML exibem a tag bruta como texto, então 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 abaixo 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> quanto <figcaption> estão na lista de permissões do GitHub, então a versão semântica funciona em READMEs. A linha em itálico é a alternativa para renderizadores sem HTML. Leitores de tela a anunciam como texto comum e não como legenda, e esse é o preço da portabilidade.
Links que Abrem em Nova Aba
Links em markdown não conseguem abrir em nova aba; escreva a âncora em HTML puro com target="_blank".
<a href="https://example.com/report" target="_blank" rel="noopener">2026 annual report</a>
Adicione rel="noopener" para que a nova página não consiga executar scripts contra a janela que a abriu. Este truque tem alcance curto. O GitHub remove o atributo target durante a sanitização, e todo link de README abre na mesma aba de qualquer forma. O truque funciona em geradores de sites estáticos como Hugo e Jekyll, que repassam o HTML intacto, e é justamente onde o comportamento de nova aba mais importa.
Símbolos e Caracteres Especiais
Digite os símbolos diretamente, já que arquivos markdown são texto Unicode puro, ou use entidades HTML quando um símbolo for difícil de alcançar pelo teclado. Copie © ou → de qualquer página de referência de caracteres e cole no arquivo; ele renderiza sem alterações.
| Símbolo | Entidade HTML |
|---|---|
| © copyright | © |
| ® registrado | ® |
| ™ marca registrada | ™ |
| → seta para a direita | → |
| ° grau | ° |
| € euro | € |
Entidades convertem em quase todos os renderizadores, GitHub incluído. A única armadilha são os blocos de código, onde © aparece literalmente porque o código cercado desativa a decodificação de entidades.
Sumário (Índice de Conteúdo)
Monte um sumário como uma lista de links que apontam para os IDs de âncora dos títulos. GitHub, GitLab e a maioria dos outros renderizadores geram um ID para cada título: o texto vira minúsculas e os espaços viram hifens, com a maior parte da 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 exibe um botão de sumário automático nos cabeçalhos de README desde 2021, então a lista manual vale a pena em documentos longos de outras plataformas. Reconfira as âncoras após cada edição de título, porque um título renomeado quebra os links em silêncio.
Incorporar Vídeos
O markdown não consegue incorporar um player de vídeo, então vincule uma miniatura clicável ao vídeo. O YouTube publica uma miniatura para cada vídeo em uma URL previsível, o que simplifica o padrão.
[](https://www.youtube.com/watch?v=VIDEO-ID)
Substitua VIDEO-ID pelo código de 11 caracteres da URL do vídeo. A miniatura renderiza em qualquer lugar onde o markdown padrão funciona, e um clique abre o vídeo no YouTube. Existem dois upgrades onde a plataforma permite. O GitHub aceita uploads diretos de .mp4 e .mov em issues, pull requests, discussões e arquivos markdown desde maio de 2021, e renderizadores com suporte completo a HTML aceitam um <iframe> de embed do YouTube colado no arquivo.
Perguntas frequentes
Truques markdown funcionam no GitHub?
Alguns sim. O GitHub mantém <ins>, atributos width de <img>, <figure>, comentários HTML, entidades e a própria sintaxe de alertas, mas remove todo atributo style e o atributo target. Teste qualquer truque em um gist de rascunho antes de depender dele, porque a lista de permissões do sanitizador pode mudar sem aviso.
Por que meu HTML sumiu da página renderizada?
O renderizador ou bloqueia HTML embutido por completo, como fazem Reddit e Discord, ou removeu a tag ou o atributo específico que você usou durante a sanitização. Verifique a documentação da plataforma em busca de uma lista de permissões e troque o elemento removido por um permitido, como <div align="center"> no lugar de um atributo style.
Qual estilo de comentário é melhor, [comment]: # ou <!-- -->?
Use [comment]: # quando a anotação precisar desaparecer por completo, e <!-- --> quando a legibilidade do código-fonte importar mais. A forma com colchetes é consumida pelo parser do markdown e nunca chega à saída, enquanto um comentário HTML padrão permanece visível para qualquer usuário que inspecione o código-fonte da página.