Bloco de código Markdown - folha de dicas e exemplos de como usar

Aqui estou revisando opções de blocos de código no Markdown.

Blocos de código no Markdown

Blocos de código no Markdown são uma forma de exibir código ou texto pré-formatado dentro de documentos Markdown, preservando a formatação e, opcionalmente, ativando a destaque 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 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 menos comuns 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 imediatamente a linguagem de programação após os backticks de abertura para destaque de sintaxe.
  • Eles preservam a formatação e suportam código multi-linha.

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!")
```

Então o texto renderizado teria a seguinte aparência:

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

Melhores práticas para usar blocos de código no Markdown

• Use blocos de código delimitados (três backticks) para código multi-linha para garantir clareza e compatibilidade entre plataformas.
• Especifique a linguagem após os backticks de abertura para destaque 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 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 adicionais de linguagem, como diff para mostrar alterações no código, que podem destacar 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 (ex: quatro backticks para exibir três backticks).

Resumo

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.

Destaque de sintaxe diff

Para usar efetivamente o destaque de sintaxe diff em blocos de código no Markdown, siga estas etapas:

• Use blocos de código delimitados com três backticks (```) para iniciar e encerrar seu bloco.
• Especifique diff como identificador de linguagem imediatamente após os backticks de abertura. Isso ativa o destaque de sintaxe para diferenças, semelhante ao que você vê em mensagens de commit do Git ou solicitações de pull.

Exemplo:

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

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

Melhores práticas:

• Use este formato para comunicar claramente alterações de código, correções ou sugestões em documentação, revisões de código ou blogs técnicos.
• Coloque uma linha em branco antes e depois do seu bloco de código para melhor legibilidade no Markdown bruto.
• Note que o destaque diff apenas colora linhas inteiras com base no caractere inicial; não destaca alterações inline dentro de uma linha.

Dica:
Este método é amplamente suportado em plataformas como GitHub, GitLab e muitos renderizadores de Markdown, tornando-o uma escolha confiável para compartilhar visualmente alterações de código.

Linguagens suportadas

Blocos de código no Markdown suportam uma ampla variedade de linguagens para destaque de sintaxe, mas o conjunto exato de linguagens suportadas depende do renderizador ou plataforma que você está usando. O Markdown em si não define quais linguagens são suportadas; ele apenas passa o identificador de linguagem para o motor de renderização, que então aplica o destaque de sintaxe apropriado. Os blocos de código delimitados em si não definem um conjunto fixo de linguagens de programação oficialmente suportadas. Em vez disso, a lista de linguagens suportadas depende do renderizador de Markdown ou plataforma que você está usando (como GitHub, GitLab, VS Code, Typora, Quarto, etc.).

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

• Web & Scripting: javascript (js), typescript (ts), html, css, json, xml, yaml, shell/bash (sh, bash, shell, zsh)
• Programação: python (py), java, c, c++, 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)
• Outras: jsx, tsx, perl, lua, julia, dart, groovy, powershell, vb, elixir, erlang, fortran, haskell, lisp, scheme, e muitas outras

Como especificar uma linguagem: Use o nome da linguagem imediatamente após os backticks triplos de abertura:

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

As seguintes linguagens são amplamente suportadas por MAIORIA dos renderizadores de Markdown:

Nota: O identificador real pode variar (ex: js vs. javascript). A maioria dos renderizadores é insensível a maiúsculas e minúsculas para nomes de linguagem.

Como encontrar a lista completa de linguagens suportadas:

• GitHub: Usa Linguist para destaque, suportando centenas de linguagens.
• VS Code & muitos renderizadores web: Usam highlight.js ou Pygments — veja sua documentação para listas exaustivas.
• Bitbucket: Refere-se a modos CodeMirror e lexers Pygments.

Pontos-chave:

• A maioria das plataformas suporta todas as linguagens principais de programação, scripting e markup.
• Algumas plataformas também suportam formatos de diagrama e dados (como mermaid, geojson).
• O identificador de linguagem é geralmente insensível a maiúsculas e minúsculas, mas deve estar em minúsculas para melhor compatibilidade.
• Se você usar um identificador de linguagem não suportado, o bloco de código será renderizado como texto simples.

Especificar o nome do arquivo em um bloco de código no Markdown

Para especificar um nome de arquivo em um bloco de código no Markdown, você tem várias opções, mas o método depende da plataforma e do renderizador:

1. Nome do arquivo no rótulo do bloco de código (sintaxe meta)

Alguns motores de Markdown (como certos geradores de site estático, ferramentas de documentação e plataformas de blog) 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 exibirá o nome do arquivo (ex: app.js) acima ou ao lado do bloco de código, dependendo do renderizador. E este site’ renderizador hugo não faz isso:

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

Nota: Isso não é suportado em todas as plataformas (ex: Markdown favorito do GitHub não suporta esse recurso atualmente).

2. Cabeçalho ou código inline acima do bloco de código

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 um cabeçalho ou código inline em negrito:

**`app.js`**

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

Ou:

#### `app.js`

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

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

3. Nome do arquivo como comentário no código

Alternativamente, você pode incluir o nome do arquivo como um comentário dentro do próprio bloco de código:

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

Isso é especialmente útil se quiser que o nome do arquivo seja visível ao copiar o código.

Resumo e melhores práticas

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

Links úteis

• Folha de dicas do Markdown - estruturas e comandos mais úteis
• Folha de dicas do Hugo
• Folha de dicas do Bash - comandos do Bash mais úteis
• Folha de dicas do LaTeX
• Temas mais populares para Hugo
• https://www.markdownguide.org/extended-syntax/
• https://docs.readme.com/rdmd/docs/code-blocks