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

Aqui estou revisando Opções de blocos de código em Markdown — como especificar a linguagem de programação, formatação de diffs e nomes de arquivos em blocos de código.

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

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

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

Tipos de Blocos de Código em Markdown

Principais Diferenças

• 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 colorização de sintaxe e são incomuns no Markdown moderno.
• Blocos de código delimitados usam três aspas (```) ou til (~~~) antes e depois do código. Este é o método preferencial, 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 colorização de sintaxe.
  • Eles preservam a formatação e suportam código multi-linha.

Exemplo de um bloco de código delimitado com colorização 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 em Markdown

• Use blocos de código delimitados (três aspas) para código multi-linha para garantir clareza e compatibilidade entre plataformas.
• Especifique a linguagem após as aspas de abertura para colorização 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 legadas, pois eles não suportam colorização de sintaxe e podem ser menos legíveis.
• Deixe uma linha em branco antes e depois dos blocos de código delimitados para melhorar a legibilidade no Markdown bruto.

Recursos 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 aspas dentro de um bloco de código, envolva o bloco em um número maior de aspas (por exemplo, quatro aspas para exibir três aspas dentro).

Resumo de Referência Rápida

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

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

Colorização de Sintaxe de Diff

A colorização de sintaxe de 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 aspas (```) para iniciar e finalizar 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 inalterada

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

Melhores práticas:

• Deixe uma linha em branco antes e depois do seu bloco de código para melhor legibilidade no Markdown bruto.
• Observe que a colorização de diff só colore linhas inteiras com base no caractere inicial; ela não destaca alterações inline dentro de uma linha.

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

Linguagens Suportadas para Colorização de Sintaxe

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

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 & Query: sql, r, matlab
• Markup & Config: markdown, ini, toml, dockerfile, makefile
• Especial: diff, mermaid, geojson, topojson, stl (para diagramas e visualizações de dados no GitHub) — o identificador mermaid em particular habilita a renderização completa de diagramas em plataformas suportadas; consulte o Guia de Início Rápido e Referência de Diagramas Mermaid para uma referência completa de sintaxe e guia de configuração do Hugo
• 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 não distingue maiúsculas de minúsculas para nomes de linguagens. Se você usar um identificador não suportado, o bloco de código será renderizado como texto puro.

Encontrando a lista completa de linguagens suportadas:

• GitHub: Usa o Linguist, suportando centenas de linguagens.
• VS Code & muitos renderizadores web: Usam highlight.js ou Pygments — consulte sua documentação para listas exaustivas.
• Bitbucket: Refere-se aos modos do CodeMirror e 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 de 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 do Hugo deste site não o suporta:

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

Nota: Isso não é suportado no Markdown sabor do GitHub (GitHub Flavored Markdown).

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

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 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ê 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 entre plataformas.

Escapando Aspas Dentro de Blocos de Código

Para exibir aspas de delimitação 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:

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

Usar quatro aspas como a barreira externa permite que você mostre exemplos de três aspas dentro, o que é útil para tutoriais e guias de referência rápida de Markdown.

Específico do Hugo: O Shortcode Highlight

Se você usa o Hugo, o shortcode highlight integrado oferece mais controle do que blocos delimitados 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 das linhas em 10

Isso é particularmente útil em tutoriais ou documentação onde você deseja chamar a atenção para linhas específicas. Consulte o Guia de Referência Rápida de Markdown para mais recursos de formatação e o Guia de Referência Rápida 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