O Markdown foi criado por John Gruber em 2004 com um único objetivo elegante: escrever texto simples que se leia naturalmente, depois convertê-lo em HTML limpo. Duas décadas depois, está em todo lugar — arquivos README do GitHub, descrições de pull request, mensagens do Slack, documentos do Notion, postagens de blog, respostas de chat de IA. É uma das ferramentas que você usará todos os dias pelo resto de sua carreira, quer pense conscientemente nisso ou não.

O Que o Markdown Realmente É

Markdown é texto simples com sintaxe leve e legível sobre ele. Um # no início de uma linha vira um <h1>. Envolver uma palavra em **asteriscos duplos** a torna negrito. Backticks produzem código inline. A filosofia central de design é que o fonte Markdown deve ser legível como está — mesmo antes de ser renderizado. Se você já escreveu um e-mail com *asteriscos em volta da ênfase* ou usou traços para uma lista de marcadores, já estava escrevendo algo muito próximo de Markdown.

Aqui está um antes e depois rápido. O Markdown à esquerda produz o HTML à direita:

markdown
## Getting Started

Install the package with **npm**:

`npm install my-library`

Then import it in your project — see the [docs](https://example.com) for details.
html
<h2>Getting Started</h2>
<p>Install the package with <strong>npm</strong>:</p>
<p><code>npm install my-library</code></p>
<p>Then import it in your project — see the <a href="https://example.com">docs</a> for details.</p>

Você escreve a metade de cima; um processador Markdown produz a metade de baixo. Essa etapa de tradução é invisível uma vez que está no seu editor ou pipeline de CI.

Sintaxe Principal — A Parte Que Todo Sabor Compartilha

Qualquer que seja a variante do Markdown que você esteja usando, esses blocos de construção funcionam em todo lugar:

  • Títulos — # H1, ## H2, ### H3 (até seis níveis)
  • Negrito e itálico — **negrito**, *itálico*, ***ambos***
  • Links — [texto do link](https://url.com)
  • Imagens — ![texto alternativo](imagem.png)
  • Código inline — `backtick` envolve um snippet; três backticks abrem um bloco de código cercado
  • Citações em bloco — comece uma linha com >
  • Listas não ordenadas — linhas começando com - ou *
  • Listas ordenadas — linhas começando com 1., 2., etc.
  • Regra horizontal — três ou mais traços: ---

Aqui está um snippet realista de README que usa todos os itens acima juntos:

markdown
# json-transform

> A zero-dependency library for transforming JSON structures.

## Installation

```bash
npm install json-transform
```

## Usage

```js
import { transform } from 'json-transform';

const result = transform(input, schema);
```

## Features

- **Fast** — processes 10k objects/sec on average hardware
- *Typed* — ships with full TypeScript definitions
- Zero runtime dependencies

See the [full documentation](https://json-transform.dev/docs) for advanced options.

---

MIT License
Dica: você pode usar nossa ferramenta Pré-visualização de Markdown para colar qualquer Markdown e ver renderizado instantaneamente — útil para verificar a sintaxe antes de enviar para o GitHub.

O Problema dos Sabores — CommonMark, GFM e Outros

Aqui está o problema: "Markdown" não é uma coisa única. A especificação original de Gruber de 2004 foi intencionalmente solta, o que levou a anos de implementações incompatíveis. Parsers diferentes lidam com casos extremos — listas aninhadas, linhas em branco dentro de citações em bloco, precedência entre ênfase e links — de maneiras diferentes. O mesmo arquivo fonte seria renderizado de forma diferente em ferramentas diferentes.

CommonMark (lançado em 2014) corrigiu isso. Um grupo de desenvolvedores — incluindo pessoas do GitHub, Stack Overflow e Reddit — escreveu uma especificação rigorosa e inequívoca que cobre todos os casos extremos com um conjunto de testes de 652 exemplos. A maioria das ferramentas modernas agora usa CommonMark como base.

O GitHub então estendeu o CommonMark com suas próprias adições e publicou o GitHub Flavored Markdown (GFM). GFM é o que você escreve nos READMEs, issues e pull requests do GitHub. Muitas outras ferramentas adotaram as extensões do GFM também, mas nem todas — então o que renderiza no GitHub pode não renderizar da mesma forma no seu gerador de site estático ou aplicativo de anotações. Saber qual sabor sua ferramenta suporta economiza muitas dores de cabeça.

Extensões do GitHub Flavored Markdown

GFM adiciona cinco recursos sobre o CommonMark que você usará constantemente no GitHub e em qualquer ferramenta que suporte o superconjunto GFM:

Tabelas — colunas delimitadas por pipe com uma linha separadora de traços:

markdown
| Method  | Returns       | Mutates? |
|---------|---------------|----------|
| map()   | new array     | No       |
| filter()| new array     | No       |
| sort()  | same array    | Yes      |

Listas de tarefas — caixas de seleção em issues e pull requests:

markdown
- [x] Write unit tests
- [x] Update CHANGELOG
- [ ] Add migration guide
- [ ] Tag release

Tachado — envolva o texto com dois til:

markdown
~~deprecated API~~ — use `newMethod()` instead

Blocos de código cercados com dicas de linguagem — o identificador de linguagem após os backticks de abertura aciona o realce de sintaxe:

markdown
```python
def parse_config(path: str) -> dict:
    with open(path) as f:
        return json.load(f)
```

Autolinks — URLs simples como https://example.com são automaticamente tornados clicáveis sem precisar da sintaxe [texto](url). Isso é conveniente em comentários de issues, mas pode ser surpreendente se você colar uma URL que não quer vinculada.

Use nosso Formatador de Markdown para limpar espaçamento inconsistente, normalizar indentação de lista e padronizar delimitadores de bloco de código cercado — útil antes de confirmar documentos em um repositório.

Onde Você Usará Markdown na Prática

Markdown aparece em mais lugares do que a maioria dos desenvolvedores espera quando o encontra pela primeira vez:

  • GitHub e GitLab — arquivos README, issues, descrições de pull request, wikis e até corpos de mensagens de commit. Todo repositório que você tocar terá pelo menos um README.md.
  • Geradores de site estático — Jekyll, Hugo, Eleventy, Astro e Next.js todos aceitam arquivos de conteúdo Markdown. Você escreve posts em arquivos .md e o gerador os converte em páginas HTML no momento da compilação.
  • Ferramentas de documentação — MkDocs, Docusaurus e GitBook são construídos inteiramente em torno de fontes Markdown. Bibliotecas de código aberto quase universalmente usam uma delas.
  • Aplicativos de anotações — Obsidian, Notion, Bear e Typora todos usam Markdown como formato nativo (com extensões variadas). Suas notas são arquivos de texto simples portáteis, não um banco de dados proprietário.
  • Plataformas CMS — Ghost usa Markdown nativamente. Contentful e Strapi ambos suportam campos Markdown. Configurações de CMS headless tipicamente armazenam conteúdo longo como strings Markdown.
  • Ferramentas de IA — ChatGPT e Claude ambos produzem Markdown por padrão. Snippets de código, termos em negrito e listas de marcadores em respostas de IA são Markdown — a UI do chat os renderiza, mas o texto subjacente é **negrito** e ```python.

Markdown vs HTML — Quando Usar Qual

Markdown converte para HTML, mas não pode expressar tudo que HTML pode. Não há equivalente para <div class="card">, atributos data-* ou atributos aria-*. Para conteúdo de prosa simples — documentação, READMEs, postagens de blog, changelogs — Markdown é mais rápido de escrever e muito mais legível em sua forma bruta. Para componentes de UI complexos, layouts personalizados ou anotações de acessibilidade que requerem atributos específicos, você precisa de HTML.

A boa notícia: a maioria dos processadores Markdown permite HTML bruto inline. Você pode misturar os dois. Se você precisa de um <figure> com um <figcaption>, ou um widget de divulgação <details>, basta escrever o HTML diretamente em seu arquivo .md. O processador o passa inalterado. Use essa saída de emergência com moderação — se mais de um terço do seu arquivo é HTML bruto, pode ser melhor escrever HTML diretamente e usar nosso Formatador HTML para mantê-lo limpo.

  • Use Markdown para: documentação, READMEs, changelogs, postagens de blog, artigos de base de conhecimento, campos de descrição de API
  • Use HTML para: layout preciso, componentes personalizados, formulários, elementos que requerem atributos específicos
  • Misture ambos quando: principalmente conteúdo de prosa com um punhado de exceções estruturais (uma tabela responsiva, um embed de vídeo)

Conclusão

O Markdown é enganosamente simples — parece apenas um punhado de regras de pontuação, mas alimenta a documentação de praticamente todo grande projeto de código aberto. Aprender a sintaxe central leva cerca de dez minutos. Entender as diferenças de sabor (CommonMark vs GFM vs o que seu SSG usa) é o que separa os desenvolvedores que ocasionalmente brigam com suas ferramentas de documentação dos que não brigam.

As referências autoritativas: CommonMark para a especificação padronizada, GitHub Flavored Markdown para as extensões do GitHub, e Guia de Markdown para uma referência de folha de consulta prática. Para escrita do dia a dia, nossa Pré-visualização de Markdown permite ver a saída renderizada instantaneamente, e o Formatador de Markdown mantém seus arquivos fonte consistentes.

← All Markdown articles Browse all categories →