Sintaxe Estendida do Markdown: Guia Completo com Exemplos

A sintaxe básica do Markdown cobre a maioria das necessidades de escrita do dia a dia, mas às vezes você precisa de mais. A sintaxe estendida adiciona recursos poderosos como tabelas, notas de rodapé, listas de tarefas e mais — transformando o Markdown de uma simples ferramenta de formatação em um ambiente de escrita completo.

Nem todos os processadores de Markdown suportam todos os elementos de sintaxe estendida. Antes de usá-los, verifique se sua ferramenta ou plataforma suporta o recurso específico que você precisa. A boa notícia: a maioria das plataformas modernas — GitHub, GitLab, VS Code e geradores de sites estáticos populares — suportam a maioria dessas extensões.

Se você ainda não está confortável com o básico, comece com nosso guia de sintaxe básica do Markdown.

Tabelas

Tabelas permitem organizar dados em linhas e colunas diretamente no Markdown. Use barras verticais (|) para separar colunas e hifens (-) para criar a linha de cabeçalho.

| Feature       | Basic Syntax | Extended Syntax |
| ------------- | ------------ | --------------- |
| Tables        | No           | Yes             |
| Footnotes     | No           | Yes             |
| Task Lists    | No           | Yes             |

Isso é renderizado como:

Feature	Basic Syntax	Extended Syntax
Tables	No	Yes
Footnotes	No	Yes
Task Lists	No	Yes

Alinhamento de colunas

Controle o alinhamento do texto adicionando dois pontos à linha separadora do cabeçalho:

| Left Aligned | Center Aligned | Right Aligned |
| :----------- | :------------: | ------------: |
| Text         |     Text       |          Text |
| More         |     More       |          More |

• :--- alinha à esquerda (padrão)
• :---: centraliza a coluna
• ---: alinha à direita

Dicas para tabelas

• Você não precisa alinhar perfeitamente as barras verticais no código fonte — isso apenas fica mais bonito
• Tabelas suportam formatação em linha como negrito, itálico, código e links
• Tabelas não suportam títulos, citações, listas ou imagens dentro das células
• Para dados complexos, considere usar tabelas HTML

Blocos de código delimitados

Enquanto a sintaxe básica suporta blocos de código indentados, os blocos de código delimitados são muito mais práticos. Envolva seu código com três crases (```) ou três tils (~~~) e especifique um idioma para destaque de sintaxe.

```python
def fibonacci(n):
    if n <= 1:
        return n
    return fibonacci(n - 1) + fibonacci(n - 2)

print(fibonacci(10))
```

Isso é renderizado com destaque de sintaxe completo:

def fibonacci(n):
    if n <= 1:
        return n
    return fibonacci(n - 1) + fibonacci(n - 2)

print(fibonacci(10))

Linguagens suportadas

A maioria dos renderizadores suporta dezenas de identificadores de linguagem. Aqui estão os mais comuns:

Language        Identifier
--------------  ----------------
JavaScript      javascript / js
Python          python / py
TypeScript      typescript / ts
HTML            html
CSS             css
JSON            json
Bash            bash / sh
SQL             sql
Markdown        markdown / md

Melhores práticas para blocos de código

• Sempre especifique um idioma — isso ativa o destaque de sintaxe e melhora a legibilidade
• Use text ou plaintext quando nenhum idioma se aplica
• Blocos delimitados são preferidos em relação aos blocos indentados porque suportam destaque e não requerem indentar cada linha

Notas de rodapé

Notas de rodapé permitem adicionar notas e referências sem poluir o texto principal. O conteúdo da nota de rodapé aparece na parte inferior da página.

Markdown was created by John Gruber in 2004.[^1] It has since become
the standard for technical writing.[^2]

[^1]: John Gruber's original Markdown project is documented on
    [Daring Fireball](https://daringfireball.net/projects/markdown/).
[^2]: Markdown is used by GitHub, Stack Overflow, Reddit, and
    countless other platforms.

Os números de referência são renderizados como links sobrescritos no texto, com as notas completas listadas na parte inferior do documento.

Regras de sintaxe de notas de rodapé

• A referência da nota de rodapé usa [^identifier] — o identificador pode ser um número ou uma palavra (sem espaços)
• A definição da nota de rodapé começa com [^identifier]: seguido do conteúdo
• Notas de rodapé com múltiplos parágrafos requerem indentação (quatro espaços ou um tab) para parágrafos subsequentes
• Definições de notas de rodapé podem ser colocadas em qualquer lugar do documento — sempre são renderizadas na parte inferior

Here's a footnote with multiple paragraphs.[^note]

[^note]: This is the first paragraph of the footnote.

    This is the second paragraph, indented with four spaces.

    You can even include code: `console.log("hello")`

IDs de títulos

IDs de título personalizados permitem criar links âncora precisos para seções específicas do seu documento. Adicione o ID entre chaves após o texto do título.

### My Custom Section {#custom-section}

Isso gera:

<h3 id="custom-section">My Custom Section</h3>

Vinculando a IDs de títulos

Uma vez que um título tem um ID, você pode vincular diretamente a ele:

Jump to [My Custom Section](#custom-section).

Isso é especialmente útil para criar um sumário manual no topo de documentos longos:

## Contents

- [Introduction](#introduction)
- [Getting Started](#getting-started)
- [Advanced Usage](#advanced-usage)
- [FAQ](#faq)

Nota de compatibilidade

Muitos processadores (incluindo o GitHub) geram automaticamente IDs de título a partir do texto do título, mesmo sem a sintaxe {#id}. No entanto, definir IDs explicitamente dá controle total e garante comportamento consistente entre plataformas.

Listas de definições

Listas de definições são perfeitas para glossários, FAQs e qualquer conteúdo onde você precisa parear termos com suas explicações.

Markdown
: A lightweight markup language for creating formatted text
  using a plain-text editor.

HTML
: The standard markup language for documents designed to be
  displayed in a web browser.

YAML
: A human-readable data serialization language commonly used
  for configuration files.

Isso gera o seguinte HTML:

<dl>
  <dt>Markdown</dt>
  <dd>A lightweight markup language for creating formatted text
      using a plain-text editor.</dd>
  <dt>HTML</dt>
  <dd>The standard markup language for documents designed to be
      displayed in a web browser.</dd>
</dl>

Múltiplas definições

Um termo pode ter mais de uma definição:

Markdown
: A lightweight markup language.
: A tool used by developers and writers worldwide.

Nota de compatibilidade

Listas de definições não são suportadas por todos os processadores. GitHub Flavored Markdown não as suporta, mas muitos geradores de sites estáticos e ferramentas de documentação suportam.

Tachado

O tachado exibe texto com uma linha horizontal através dele, indicando conteúdo excluído ou desatualizado. Envolva o texto com tils duplos (~~).

The project deadline is ~~Friday~~ Monday.
~~Old information~~ has been replaced with updated content.

Isso é renderizado como:

The project deadline is Friday Monday.

Saída HTML:

<p>The project deadline is <del>Friday</del> Monday.</p>

O tachado tem amplo suporte — é parte do GitHub Flavored Markdown (GFM) e funciona na maioria das plataformas modernas.

Listas de tarefas

Listas de tarefas (também chamadas de caixas de seleção ou listas de afazeres) criam checklists interativos. Use - [ ] para itens não marcados e - [x] para itens marcados.

- [x] Research extended syntax features
- [x] Write first draft
- [x] Add code examples for each section
- [ ] Create cover image
- [ ] Proofread and edit
- [ ] Publish the article

Isso é renderizado como:

• Research extended syntax features
• Write first draft
• Add code examples for each section
• Create cover image
• Proofread and edit
• Publish the article

Casos de uso de listas de tarefas

Listas de tarefas são especialmente populares em:

• Issues e pull requests do GitHub — acompanhar o progresso dos itens de trabalho
• Documentação de projetos — delinear etapas em um processo
• Notas de reunião — capturar itens de ação com seu status

Em plataformas como o GitHub, essas caixas de seleção são interativas — você pode clicar para alterná-las diretamente na visualização renderizada.

Emoji

Existem duas formas de adicionar emoji aos seus documentos Markdown.

Copiar e colar

A abordagem mais simples — basta copiar um emoji de qualquer fonte e colá-lo diretamente no seu texto:

That's a great idea! 🎉 Let's ship it! 🚀

Isso funciona em todos os lugares porque emoji são caracteres Unicode padrão.

Códigos curtos

Algumas plataformas suportam códigos curtos de emoji — palavras-chave envolvidas em dois pontos:

:smile: :rocket: :thumbsup: :warning: :heavy_check_mark:

Códigos curtos comuns incluem:

Shortcode              Emoji
---------------------  -----
:smile:                😄
:rocket:               🚀
:thumbsup:             👍
:warning:              ⚠️
:heavy_check_mark:     ✔️
:x:                    ❌
:fire:                 🔥
:star:                 ⭐

Nota de compatibilidade

Códigos curtos de emoji variam entre plataformas. GitHub, Slack e Discord suportam conjuntos diferentes. Emoji copiados e colados funcionam universalmente e são a escolha mais segura para documentos multiplataforma.

Destaque

O destaque chama atenção para palavras ou frases-chave dando-lhes um fundo colorido. Envolva o texto com sinais de igual duplos (==).

This is ==critically important== information.

Isso gera:

<p>This is <mark>critically important</mark> information.</p>

Alternativa HTML

Se seu processador Markdown não suporta a sintaxe ==, use a tag HTML <mark> diretamente:

This is <mark>critically important</mark> information.

Ambas as abordagens produzem o mesmo resultado — texto destacado que se sobressai do conteúdo ao redor.

Nota de compatibilidade

A sintaxe ==highlight== não tem amplo suporte. Funciona em alguns processadores, mas não no GitHub Flavored Markdown. Se a compatibilidade é importante, use a tag HTML <mark>.

Subscrito e sobrescrito

Esses elementos são essenciais para notação científica, expressões matemáticas e fórmulas químicas.

Subscrito

Use tils simples (~) para envolver texto subscrito:

The chemical formula for water is H~2~O.
Carbon dioxide is CO~2~.

Isso é renderizado como: H₂O e CO₂.

Equivalente HTML:

<p>The chemical formula for water is H<sub>2</sub>O.</p>

Sobrescrito

Use circunflexos (^) para envolver texto sobrescrito:

The equation is E = mc^2^.
This is the 3^rd^ edition.

Isso é renderizado como: E = mc² e 3^rd edição.

Equivalente HTML:

<p>The equation is E = mc<sup>2</sup>.</p>

Alternativa HTML

Se seu processador não suporta a sintaxe ~ e ^, use tags HTML diretamente:

H<sub>2</sub>O is water.
E = mc<sup>2</sup> is Einstein's famous equation.

Esta abordagem HTML funciona em praticamente todos os renderizadores Markdown.

Links URL automáticos

A maioria dos processadores Markdown converte automaticamente URLs brutas em links clicáveis sem qualquer sintaxe especial:

Visit https://example.com for more information.

Isso é renderizado como um link clicável mesmo sem a sintaxe [text](url).

Desativando links automáticos

Às vezes você quer exibir uma URL como texto simples sem torná-la clicável. Envolva-a em crases para renderizá-la como código em linha:

`https://example.com`

Isso exibe a URL como código em vez de um link clicável — útil para documentação onde você está explicando padrões de URL em vez de vincular a eles.

Quando usar links explícitos

Embora links automáticos sejam convenientes, a sintaxe de link explícito oferece mais controle:

<!-- Automatic: shows raw URL -->
https://example.com

<!-- Explicit: shows custom text -->
[Visit our website](https://example.com)

Use links explícitos quando quiser texto âncora descritivo — é melhor para legibilidade e SEO.

Referência rápida

Aqui estão todos os elementos de sintaxe estendida em um relance:

Element              Syntax                     Support
-------------------  -------------------------  --------
Table                | Col | Col |              Wide
Fenced Code Block    ``` code ```               Wide
Footnote             [^1] / [^1]: text          Moderate
Heading ID           ### Heading {#id}          Moderate
Definition List      Term / : Definition        Limited
Strikethrough        ~~text~~                   Wide
Task List            - [x] / - [ ]             Wide
Emoji (shortcode)    :emoji_name:               Varies
Highlight            ==text==                   Limited
Subscript            H~2~O                      Limited
Superscript          X^2^                       Limited
Auto URL Link        https://...                Wide

Comece a usar a sintaxe estendida

Agora você conhece todos os principais elementos de sintaxe estendida. Veja como colocá-los em prática:

1. Verifique sua plataforma: Confirme quais recursos seu processador Markdown suporta. GitHub, VS Code e a maioria dos geradores de sites estáticos lidam bem com os elementos amplamente suportados.

2. Use alternativas HTML: Para recursos com suporte limitado (destaque, subscrito, sobrescrito), as alternativas com tags HTML funcionam em quase todos os lugares.

3. Pratique com conteúdo real: Tente adicionar uma tabela ao seu próximo README, notas de rodapé à sua próxima postagem de blog ou listas de tarefas ao seu próximo plano de projeto.

4. Converta com confiança: Quando seu documento estiver pronto para compartilhar, converta Markdown para PDF para saída pronta para impressão com suporte a tabelas e matemática LaTeX, exporte para HTML para publicação web, ou gere um documento Word para revisão de envolvidos — todos os elementos de sintaxe estendida incluídos.

Entre a sintaxe básica e esses recursos estendidos, agora você tem o kit completo de ferramentas Markdown. Se você é completamente novo no Markdown, comece com O Que é Markdown para conhecer o essencial. Seja escrevendo documentação, postagens de blog, especificações técnicas ou planos de projeto — o Markdown tem tudo o que você precisa.