Blocos de código Markdown: guia completo com sintaxe, linguagens e exemplos

Blocos de código delimitados carregam código-fonte multilinha em Markdown. O token após a cerca de abertura é uma etiqueta de idioma, e apenas o renderizador decide o que essa etiqueta destaca.

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

O GitHub consulta a etiqueta de idioma no Linguist e nas palavras-chave em languages.yml. O Hugo 0.164 passa a mesma etiqueta para o Chroma. Uma etiqueta que o Chroma não conhece ainda é um bloco de código, desenhada como texto simples. Títulos, tabelas e os outros tipos de bloco estão na Folha de Dicas de Markdown.

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

O Markdown tem três maneiras de marcar código. Código em linha é um trecho dentro de um parágrafo. Um bloco indentado e um bloco delimitado são ambos multilinha, e apenas a cerca carrega uma etiqueta de idioma.

Um bloco indentado não pode carregar um idioma. O CommonMark trata uma linha indentada com quatro espaços como código e não dá nada para o destacador corresponder, o que é por isso que a cerca é a forma a usar quando a amostra deve ser colorida.

Uma cerca é uma linha com pelo menos três crases ou três tildes, o código, e então uma linha de fechamento com o mesmo caractere pelo menos com o mesmo comprimento. A linha de fechamento não tem string de informação. Para mostrar uma cerca de três crases dentro da amostra, abra e feche com quatro crases. Os documentos de blocos de código do GitHub pedem uma linha em branco antes e depois da cerca para que o arquivo cru seja mais fácil de ler; a cerca ainda é analisada sem essa linha em branco.

Quando a seguinte fonte é armazenada como Markdown:

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

este site Hugo a renderiza assim:

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

Código em linha usa a mesma regra de crases em menor escala. Um par de crases simples é suficiente para git status. Quando o trecho em si contém uma crase, use duas crases em cada lado:

`` `código` ``

Destaque de Sintaxe Diff

Uma cerca etiquetada como diff é como uma alteração é mostrada como texto. O léxer Chroma do Hugo aceita diff e udiff. O GitHub destaca o mesmo identificador da sua lista de idiomas.

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

Linhas que começam com - recebem o estilo de exclusão, e linhas que começam com + recebem o estilo de inserção. Uma linha com nenhum prefixo é texto comum nesse léxer. A coloração é da linha inteira. Uma palavra alterada no meio de uma linha não é marcada sozinha.

Identificadores de Idioma

A primeira palavra da string de informação é o idioma. Os documentos do Hugo tratam essa palavra como não distinguindo maiúsculas e minúsculas. Se o Chroma não tiver um léxer para ela, o Hugo 0.164 emite um <pre><code class="language-…"> simples sem envoltório de destaque. Uma renderização local de notalang fez isso. guessSyntax é falso por padrão, e os documentos do Hugo dizem que apenas cinco léxers implementam detecção automática, portanto uma etiqueta omitida permanece como texto simples em vez de um idioma suposto.

O HTML produzido a partir dessas cercas usa a classe language-python e o mesmo token. Essa classe é o que um conversor tem de preservar quando converte uma página destacada de volta para Markdown, o que é o mapeamento coberto em Convertendo HTML para Markdown com Python.

Os identificadores abaixo são os listados para esses idiomas na tabela do Chroma do Hugo. Em uma renderização do Hugo 0.164, cs, yml e markdown também foram coloridos, mesmo onde a tabela publicada imprime csharp, yaml e md.

Sites do GitHub Pages que ainda destacam através do Jekyll precisam do identificador em minúsculas. Os próprios documentos do GitHub declaram esse requisito separadamente da renderização no github.com.

O GitHub também trata algumas cercas como diagramas em vez de fonte colorida: mermaid, geojson, topojson e stl. A tabela do Chroma do Hugo não lista mermaid. Em um site Hugo, a cerca permanece como texto de fonte até que um gancho de renderização, shortcode ou script a desenhe. A Iniciação Rápida e Folha de Dicas de Diagramas Mermaid cobre essa configuração.

Especificando um Nome de Arquivo

Nada no CommonMark ou nos documentos de blocos de código do GitHub transforma a string de informação em um nome de arquivo. As opções de destaque do Hugo são pares de chaves como {linenos=inline}. Elas não incluem um campo de nome de arquivo.

Dois-pontos após o idioma

Alguns geradores tratam js:app.js como um idioma mais um nome:

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

O GitHub não. O Hugo 0.164 mantém o token inteiro como a classe do elemento de código (language-js:app.js) e não imprime um nome de arquivo. Quais dialetos adicionam significado além da primeira palavra é a comparação em GFM vs CommonMark vs Pandoc Markdown.

Nome acima da cerca

Uma linha de código em linha em negrito acima da cerca mostra o nome no GitHub, neste site e em outros renderizadores do CommonMark:

**`app.js`**

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

Um título funciona da mesma forma:

#### `app.js`

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

Nome dentro da amostra

Um comentário na primeira linha viaja com o código quando alguém copia o bloco:

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

Escapando Crases

Quatro crases por fora exibem uma cerca de três crases, o que é o padrão para uma página que documenta Markdown:

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

A cerca de fechamento tem de ser o mesmo caractere que a de abertura, e pelo menos com o mesmo comprimento. Um fechador mais curto termina o bloco precocemente e deixa o resto da amostra como parágrafos comuns.

Opções de Destaque do Hugo

O config.toml deste site não tem um bloco [markup.highlight], portanto os padrões do Hugo se aplicam: blocos delimitados são destacados, o estilo é monokai, os estilos são escritos em linha (noClasses verdadeiro) e os números de linha estão desligados. O Hugo 0.164 ainda colora uma cerca que pede apenas um idioma, como a amostra Python acima faz.

Números de linha e linhas enfatizadas são opções entre chaves após o idioma. Esta cerca pede números em linha e marca a linha 2:

```python {linenos=inline hl_lines=[2]}
def hello():
    print("Hello, world!")
```

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

linenos aceita inline, table, true ou false. hl_lines é uma lista de números de linha ou intervalos. linenostart define o primeiro número exibido. As mesmas chaves não distinguem maiúsculas e minúsculas. O shortcode highlight os recebe como uma única string entre aspas, e essa string ainda renderizou números de linha no Hugo 0.164:

{{< highlight python "linenos=true,hl_lines=2" >}}
def hello():
    print("Hello, world!")
{{< /highlight >}}

Para mover as cores para uma folha de estilo, defina noClasses como falso e gere o CSS. O Hugo 0.164 aceita --mode e --modeSelector nesse comando:

hugo gen chromastyles --style=monokai --mode=light > assets/css/highlight.css
hugo gen chromastyles --style=monokai --mode=dark --modeSelector > assets/css/highlight-dark.css

--modeSelector escopa cada regra sob uma classe de nível superior como .dark .chroma. A lista de bandeiras é hugo gen chromastyles --help.

Quando a Cerca Parece Errada

Verifique o elemento gerado antes de alterar a amostra. Nesta versão do Hugo, um idioma conhecido é um div.highlight cujo elemento de código tem data-lang definido para o identificador. Um identificador desconhecido é um pre e code simples com class="language-…", o que é o que notalang produziu.

Se o nome app.js estiver ausente e a classe for language-js:app.js, a forma com dois-pontos foi usada. Mova o nome para a linha acima da cerca.

Se as cercas de um tutorial aparecerem como parágrafos soltos, a cerca externa tem o mesmo comprimento que a interna. Alongue a cerca externa.

Se um comando curto engole a crase no meio de uma frase, o trecho precisa de um par de crases mais longo que o caractere que contém.

Links Úteis

• https://www.markdownguide.org/extended-syntax/
• https://docs.github.com/en/get-started/writing-on-github/working-with-advanced-formatting/creating-and-highlighting-code-blocks
• https://gohugo.io/content-management/syntax-highlighting/