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

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

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

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

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

Tipos de Blocos de Código Markdown

Diferenças Principais

• Código inline usa aspas simples (`) e é destinado a trechos curtos de código 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 realce de sintaxe e são incomuns no Markdown moderno.
• Blocos de código com cerca usam três aspas simples (```) ou tildes (~~~) antes e depois do código. Este é o método preferido, especialmente em plataformas como o GitHub, porque:
  • São mais fáceis de ler e escrever.
  • Você pode especificar a linguagem de programação imediatamente após as aspas de abertura para obter realce de sintaxe.
  • Eles preservam a formatação e suportam código de múltiplas linhas.

Exemplo de bloco de código com cerca e realce de sintaxe:

Quando temos o seguinte texto formatado em Markdown:

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

A saída renderizada parece assim:

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

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

• Use blocos de código com cerca (três aspas simples) para código de múltiplas linhas para garantir clareza e compatibilidade entre plataformas.
• Especifique a linguagem após as aspas de abertura para obter realce de sintaxe (ex.: ```python).
• Use código inline para trechos curtos ou comandos dentro do texto.
• Evite blocos de código indentados, a menos que seja necessário para compatibilidade com legado, pois eles não suportam realce de sintaxe e podem ser menos legíveis.
• Coloque uma linha em branco antes e depois dos blocos de código com cerca para melhorar a legibilidade no Markdown bruto.

Recursos Especiais

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

Resumo de Referência Rápida

Use blocos de código com cerca com um identificador de linguagem para a melhor legibilidade e realce de sintaxe. Reserve o código inline para trechos curtos e evite blocos indentados, a menos que seja necessário para compatibilidade.

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

Realce de Sintaxe de Diferenças (Diff)

O realce de sintaxe de diferenças permite mostrar alterações de código de forma clara — útil em documentação, revisões de código e blogs técnicos.

• Use blocos de código com cerca com três aspas simples (```) para iniciar e terminar seu bloco.
• Especifique diff como o identificador de linguagem imediatamente após as aspas de abertura.

Exemplo:

- linha antiga que será removida
+ nova linha que será adicionada
  linha sem alterações

• Linhas que começam com - são destacadas como exclusões (geralmente em vermelho).
• Linhas que começam com + são destacadas como adições (geralmente em verde).
• Linhas sem prefixo não são destacadas de forma especial.

Melhores práticas:

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

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

Linguagens Suportadas para Realce de Sintaxe

O conjunto exato de linguagens suportadas depende do renderizador ou plataforma que você usa. O Markdown passa o identificador de linguagem ao mecanismo de renderização, que aplica o realce de sintaxe apropriado. Isso é importante ao converter HTML para Markdown com Python, pois as tags <code> que carregam atributos de classe de linguagem (ex. class="language-python") mapeiam diretamente para esses identificadores no bloco com cerca.

Linguagens comumente suportadas nas principais plataformas (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 & Consulta: sql, r, matlab
• Marcação & 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 muitos mais

Como especificar uma linguagem:

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

Identificadores de linguagem suportados na maioria dos renderizadores:

Nota: A maioria dos renderizadores é insensível a maiúsculas e minúsculas para nomes de linguagens. 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 o Linguist, suportando centenas de linguagens.
• VS Code e muitos renderizadores web: Usam highlight.js ou Pygments—consulte sua documentação para listas exaustivas.
• Bitbucket: Refere-se aos modos do CodeMirror e aos lexers do Pygments.

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

Exibir o nome do arquivo ao lado de 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 Markdown (certos geradores de sites estáticos 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 isso:

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

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

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

Para compatibilidade universal (incluindo GitHub, Stack Overflow e a maioria dos renderizadores 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 cabeçalho:

#### `app.js`

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

Isso funciona em todos os lugares e associa visualmente 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ê quer 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 entre plataformas.

Escapando Aspas Simples Dentro de Blocos de Código

Para exibir cercas de aspas simples dentro de um bloco de código — por exemplo, ao escrever documentação sobre o próprio Markdown — aninhe o bloco em um número maior de aspas simples:

````markdown
```python
# Esta cerca de três aspas simples está dentro de uma cerca de quatro aspas simples
print("hello")
```
````

Usar quatro aspas simples como cerca externa permite mostrar exemplos de três aspas simples dentro, o que é útil para tutoriais e guias de referência do Markdown.

Específico do Hugo: O Shortcode Highlight

Se você usa o Hugo, o shortcode highlight embutido oferece mais controle do que blocos com cerca simples, incluindo números de linha 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 números de linha
• hl_lines=2 4 — destacar as linhas 2 e 4
• linenostart=10 — iniciar a numeração de linha em 10

Isso é particularmente útil em tutoriais ou documentação onde você quer chamar a atenção para linhas específicas. Consulte o Guia de Referência do Markdown para mais recursos de formatação e o Guia de Referência do Hugo para uma referência mais ampla sobre comandos e modelos do Hugo.

Links Úteis

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