Bloco de Código Markdown: Guia Completo com Sintaxe, Linguagens e Exemplos

Aqui estou revisando opções de blocos de código no Markdown — como especificar a linguagem de programação, formatação de diffs e nome do arquivo do bloco de código.

Este guia faz parte do nosso Ferramentas de Documentação em 2026: Markdown, LaTeX, PDF & Fluxos de Trabalho de Impressão hub.

Visão Geral dos Blocos de Código no Markdown

Blocos de código no Markdown exibem código ou texto pré-formatado dentro de documentos Markdown, preservando a formatação e, opcionalmente, habilitando a destaque de sintaxe. Existem dois principais tipos de formatação de código no Markdown: código inline e blocos de código.

Tipos de Blocos de Código no Markdown

Diferenças Principais

• Código inline usa backticks simples (`) e é usado para trechos curtos dentro de uma frase.
• Blocos de código indentados usam quatro espaços ou uma tabulação no início de cada linha. Eles não suportam destaque de sintaxe e são raros no Markdown moderno.
• Blocos de código delimitados usam três backticks (```) ou tildes (~~~) antes e depois do código. Este é o método preferido, especialmente em plataformas como GitHub, porque:
  • Eles são mais fáceis de ler e escrever.
  • Você pode especificar a linguagem de programação imediatamente após os backticks abertos para destaque de sintaxe.
  • Eles preservam a formatação e suportam código de várias linhas.

Exemplo de um bloco de código delimitado com destaque de sintaxe:

Quando temos o seguinte texto formatado em Markdown:

```python
def hello():
    print("Hello, world!")
```

A saída renderizada parece com:

def hello():
    print("Hello, world!")

Melhores Práticas para Blocos de Código no Markdown

• Use blocos de código delimitados (três backticks) para código de várias linhas para garantir clareza e compatibilidade entre plataformas.
• Especifique a linguagem após os backticks abertos para destaque de sintaxe (por exemplo, ```python).
• Use código inline para trechos curtos ou comandos dentro do texto.
• Evite blocos de código indentados a menos que sejam necessários para compatibilidade com versões antigas, pois eles não suportam destaque de sintaxe e podem ser menos legíveis.
• Coloque uma linha em branco antes e depois dos blocos de código delimitados para melhor legibilidade no Markdown bruto.

Funcionalidades Especiais

• Algumas plataformas suportam identificadores de linguagem adicionais, como diff para mostrar alterações de código, que destaca linhas adicionadas ou removidas em revisões de código.
• Para exibir backticks dentro de um bloco de código, envolva o bloco com um número maior de backticks (por exemplo, quatro backticks para exibir três backticks dentro).

Resumo Rápido de Referência

Use blocos de código delimitados com um identificador de linguagem para a melhor legibilidade e destaque de sintaxe. Reserve código inline para trechos curtos e evite blocos indentados a menos que sejam necessários para compatibilidade.

Blocos de código combinam naturalmente com tabelas no Markdown para criar documentação técnica bem estruturada.

Destaque de Sintaxe com Diff

O destaque de sintaxe com diff permite mostrar alterações de código claramente — útil em documentação, revisões de código e blogs técnicos.

• Use blocos de código delimitados com três backticks (```) para iniciar e encerrar seu bloco.
• Especifique diff como o identificador de linguagem imediatamente após os backticks abertos.

Exemplo:

- linha antiga que será removida
+ nova linha que será adicionada
  linha inalterada

• Linhas começando com - são destacadas como exclusões (normalmente em vermelho).
• Linhas começando com + são destacadas como adições (normalmente em verde).
• Linhas sem prefixo não são destacadas especialmente.

Melhores práticas:

• Coloque uma linha em branco antes e depois do seu bloco de código para melhor legibilidade no Markdown bruto.
• Note que o destaque de diff apenas colora linhas inteiras com base no caractere inicial; não destaca alterações inline dentro de uma linha.

Dica: O destaque de diff é amplamente suportado no GitHub, GitLab e na maioria dos renderizadores de Markdown, tornando-o uma escolha confiável para comunicar alterações de código.

Linguagens Suportadas para Destaque de Sintaxe

O conjunto exato de linguagens suportadas depende da renderer ou plataforma que você usa. O Markdown passa o identificador da linguagem para o motor de renderização, que aplica o destaque de sintaxe apropriado. Isso importa quando converter HTML para Markdown com Python, já que os tags <code> carregando atributos de classe de linguagem (por exemplo, class="language-python") mapeiam diretamente para esses identificadores nos blocos delimitados.

Linguagens comumente suportadas em plataformas principais (GitHub, VS Code, Bitbucket, Docusaurus, ReadMe):

• Web & Scripting: javascript (js), typescript (ts), html, css, json, xml, yaml, shell/bash (sh, bash, shell, zsh)
• Programação: python (py), java, c, cpp (c++), csharp (c#), php, ruby, go, rust, scala, swift, kotlin, objective-c
• Dados & Consultas: sql, r, matlab
• Markup & Configuração: markdown, ini, toml, dockerfile, makefile
• Especiais: diff, mermaid, geojson, topojson, stl (para diagramas e visualizações de dados no GitHub)
• Outros: jsx, tsx, perl, lua, julia, dart, groovy, powershell, vb, elixir, erlang, fortran, haskell, lisp, scheme e muitas outras

Como especificar uma linguagem:

```python
def hello():
    print("Hello, world!")
```

Identificadores de linguagem suportados por maioria dos renderizadores:

Nota: A maioria dos renderizadores é case-insensitive para nomes de linguagem. Se você usar um identificador não suportado, o bloco de código será renderizado como texto simples.

Como encontrar a lista completa de linguagens suportadas:

• GitHub: Usa Linguist, suportando centenas de linguagens.
• VS Code & muitos renderizadores web: Usam highlight.js ou Pygments — veja suas documentações para listas exaustivas.
• Bitbucket: Refere-se a CodeMirror modes e lexers do Pygments.

Especificando um Nome de Arquivo em um Bloco de Código no Markdown

Exibir o nome do arquivo junto com um bloco de código ajuda os leitores a identificar a qual arquivo um trecho pertence. O suporte varia conforme a plataforma.

1. Nome do Arquivo no Rótulo do Bloco de Código (Sintaxe Meta)

Alguns motores de Markdown (certos geradores de site estático e plataformas de documentação) suportam uma sintaxe meta onde você anexa o nome do arquivo após a linguagem, separado por dois pontos:

```js:app.js
console.log("Hello, world!");
```

Isso exibe o nome do arquivo acima ou ao lado do bloco de código. O renderizador Hugo deste site não suporta:

console.log("Hello, world!");

Nota: Isso não é suportado no Markdown do GitHub.

2. Título ou Código Inline com o Nome do Arquivo

Para compatibilidade universal (incluindo GitHub, Stack Overflow e a maioria dos renderizadores de Markdown), coloque o nome do arquivo acima do bloco de código usando código inline em negrito:

**`app.js`**

```js
console.log("Hello, world!");
```

Ou com um título:

#### `app.js`

```js
console.log("Hello, world!");
```

Isso funciona em todos os lugares e visualmente associa o nome do arquivo ao bloco de código.

3. Nome do Arquivo como Comentário Dentro do Código

Inclua o nome do arquivo como um comentário dentro do próprio bloco de código:

```js
// app.js
console.log("Hello, world!");
```

Isso é especialmente útil quando você deseja que o nome do arquivo seja visível ao copiar o código.

Resumo de Compatibilidade

Use código inline em negrito acima do bloco de código para máxima compatibilidade, e considere um comentário dentro do código para clareza ao compartilhar em plataformas.

Escapando Backticks Dentro de Blocos de Código

Para exibir fences de backticks dentro de um bloco de código — por exemplo, quando você está escrevendo documentação sobre Markdown em si — aninhe o bloco com um número maior de backticks:

````markdown
```python
# Este fence de backticks triplo está dentro de um fence de quatro backticks
print("hello")
```
````

Usar quatro backticks como o fence externo permite que você mostre exemplos de backticks triplos dentro, o que é útil para tutoriais e dicas rápidas de Markdown.

Específico do Hugo: O Shortcode de Destaque

Se você usa o Hugo, o shortcode embutido highlight oferece mais controle do que blocos simples delimitados, incluindo numeração de linhas e linhas destacadas:

{{< highlight python "linenos=true,hl_lines=2 4" >}}
def greet(name):
    print(f"Hello, {name}!")

greet("world")
{{< /highlight >}}

Opções:

• linenos=true — mostrar numeração de linhas
• hl_lines=2 4 — destacar as linhas 2 e 4
• linenostart=10 — iniciar a numeração de linhas em 10

Isso é particularmente útil em tutoriais ou documentação onde você deseja chamar a atenção para linhas específicas. Veja o Cheatsheet do Markdown para mais recursos de formatação, e o Cheatsheet do Hugo para uma referência mais ampla sobre comandos e templates do Hugo.

Links Úteis

• https://www.markdownguide.org/extended-syntax/
• https://docs.readme.com/rdmd/docs/code-blocks