Markdown: Sintaxe de Código Markdown e Blocos de Código

Código é o coração da documentação técnica — o Markdown oferece uma maneira elegante de apresentá-lo para que os leitores possam tanto ler quanto executar.

1. O Que Você Vai Aprender

• Sintaxe de código inline e casos de uso
• Blocos de código delimitados e realce de sintaxe
• Escrevendo tags de linguagem corretas para blocos de código
• Escape e tratamento de caracteres especiais em blocos de código
• Incorporando código dentro de listas e citações em bloco

2. A História Real de uma Desenvolvedora

(1) Problema: O Código Copiado Pelos Leitores Dá Erro

Nina publicava tutoriais de Python em seu blog de tecnologia, mas os leitores reclamavam que copiar e executar o código dava erro. Ao investigar, ela descobriu que os blocos de código da plataforma de blog não tinham realce de sintaxe — vírgulas e pontos pareciam idênticos, e algumas pessoas copiavam ( como （ (parênteses de largura completa). Pior ainda, alguns blocos de código não tinham rótulo de linguagem, então o código aparecia sem nenhuma diferenciação de cor.

(2) Solução: Padronizar a Formatação de Blocos de Código

Nina passou a usar blocos de código delimitados com tags de linguagem adequadas e testava cada trecho de código em um ambiente real antes de publicar. Ela também adicionou um botão "Copiar Código". Após a mudança, os relatos de erro dos leitores caíram 90%. O blog dela ganhou reconhecimento de vários veículos de mídia de tecnologia graças às suas amostras de código altamente reproduzíveis.

3. Código Inline

(1) Sintaxe Básica

Coloque o texto entre um acento grave ` para criar código inline:

Use a função `print()` para exibir texto.

Execute `npm install express` no terminal.

A tag `<div>` é o contêiner mais básico em HTML.

(2) Caracteres Especiais em Código Inline

Para exibir o próprio acento grave, coloque-o entre acentos graves duplos:

Use `` ` `` para representar o caractere de acento grave.

Em uma frase, use `código` e `` `acento grave` `` juntos.

Dica: Código inline é principalmente para mencionar nomes de funções, nomes de variáveis, caminhos de arquivos, atalhos de teclado e comandos curtos. Para código mais longo, use um bloco de código.

▶ Exemplo: Uso Correto de Código Inline

No arquivo utils/helpers.py, uma função formatar_data() é definida.
Passe um objeto datetime para ela e ela retorna uma string formatada.

Pressione F5 para atualizar a página.

Dica: O texto dentro do código inline permanece como está — até mesmo ** não o tornará negrito. Isso garante que o código seja apresentado exatamente como escrito.

4. Blocos de Código Delimitados

(1) Sintaxe Básica

Envolva um bloco de código com três acentos graves ``` e, opcionalmente, especifique uma tag de linguagem para realce de sintaxe:

```python
def saudar(nome):
    return f"Olá, {nome}!"

print(saudar("Alice"))
```

Aviso: Deve haver linhas em branco antes e depois de um bloco de código, caso contrário, alguns analisadores podem não reconhecê-lo corretamente. Esta é uma das regras mais negligenciadas ao escrever documentação.

(2) O Papel das Tags de Linguagem

# Código Python com realce de sintaxe
def fibonacci(n):
    """Calcula o enésimo termo da sequência de Fibonacci"""
    if n <= 1:
        return n
    return fibonacci(n-1) + fibonacci(n-2)

print(fibonacci(10))  # Saída: 55

5. Blocos de Código Identados

Além dos blocos de código delimitados, o Markdown também suporta blocos de código identados. Indente cada linha com 4 espaços ou 1 tab:

Este é um parágrafo.

    // indentação de 4 espaços transforma isso em um bloco de código
    function ola() {
        console.log("Olá!");
    }

De volta ao texto normal.

Aviso: Blocos de código identados não suportam realce de sintaxe e não possuem tags de linguagem. Sempre prefira blocos de código delimitados (```) — eles são mais poderosos e mais claros.

▶ Exemplo: Blocos de Código Delimitados vs Identados

Blocos de código delimitados usam três acentos graves e suportam tags de linguagem e realce de sintaxe.
Blocos de código identados usam 4 espaços no início da linha, têm boa compatibilidade mas sem realce de sintaxe.
Use blocos de código delimitados sempre que possível.

6. Tratamento Especial em Blocos de Código

(1) Escapando Acentos Graves em Blocos de Código

Se seu próprio código contiver três acentos graves, envolva-o com mais acentos graves:

````text
```python
print("Olá")
```
````

Dica: O envoltório externo usa ```` (quatro acentos graves), para que o ``` interno seja exibido como texto simples.

(2) Quebrando Linhas Longas de Código

# Recomendado: mantenha cada linha dentro de 80 caracteres
const resultado = await api.obterDadosUsuario(idUsuario)
  .then(dados => processarDados(dados))
  .catch(erro => tratarErro(erro));

# Evite: linhas super longas sem quebra
const resultado = await api.obterDadosUsuario(idUsuario).then(dados => processarDados(dados)).catch(erro => tratarErro(erro));

▶ Exemplo: Marcadores de Erro Comuns em Blocos de Código

❌ Abordagem errada:
Blocos de código sem tags de linguagem aparecem como texto preto sobre fundo branco

✅ Abordagem correta:
Blocos de código com tag de linguagem python exibem realce de sintaxe colorido

Aviso: Blocos de código sem tags de linguagem são ignorados pelos realçadores de sintaxe como Prism.js, sendo exibidos como texto preto sobre fundo branco — difícil de ler.

7. Incorporando Código em Listas e Citações em Bloco

(1) Blocos de Código Dentro de Listas

Blocos de código dentro de listas precisam de uma indentação extra de 8 espaços (ou dois tabs):

- Execute os testes:

        npm test -- --coverage

- Verifique a formatação:

        npx eslint src/ --fix

Dica: Você também pode usar blocos de código delimitados dentro de listas, mas precisa de uma linha em branco antes e depois do bloco de código com indentação consistente.

(2) Blocos de Código Dentro de Citações em Bloco

> **Implementação principal:**
>
> ```python
> def processar_dados(df):
>     return df.dropna().groupby("categoria").sum()
> ```
>
> O código acima limpa valores nulos e depois agrupa e resume.

8. Exemplo Completo: Uma Página de Documentação de Código

Visão Geral do Script de Processamento de Dados

Instalar dependências: pip install pandas numpy matplotlib

Função carregar_dados(): carrega dados de um arquivo CSV
Função limpar_dados(): remove valores nulos e linhas duplicadas

Fluxo de trabalho completo:
1. Carregar dados - carregar_dados("vendas.csv")
2. Limpar - limpar_dados(dados)
3. Exibir estatísticas - imprimir contagem de linhas e nomes das colunas

Resultado esperado: Um documento técnico limpo com código e explicações alternando suavemente, tags de linguagem corretas e uma divisão clara de trabalho entre código inline e blocos de código.

❓ Perguntas Frequentes

P: Como escolher entre código inline e blocos de código? R: Use código inline para 2-3 palavras ou menos; use blocos de código para qualquer coisa com mais de uma linha. Nomes de funções, nomes de variáveis, nomes de arquivos e atalhos vão em código inline. Programas de múltiplas linhas, configurações e comandos vão em blocos de código.

P: Por que meu bloco de código não está mostrando realce de sintaxe? R: A razão mais comum — falta a tag de linguagem. Verifique se a linha de abertura do bloco de código tem um nome de linguagem como python ou javascript.

P: Posso usar formatação Markdown dentro de um bloco de código? R: Não. Tudo dentro de um bloco de código é exibido como texto bruto. Asteriscos não se tornarão negrito, sinais de hash não se tornarão cabeçalhos.

P: Como exibo acentos graves dentro de um bloco de código? R: Use mais acentos graves para o envoltório externo. Por exemplo, para exibir três acentos graves, envolva com quatro acentos graves.

P: Os espaços iniciais em um bloco de código serão preservados? R: Sim. Toda indentação dentro de um bloco de código é preservada exatamente. Isso é intencional — Python, YAML e outras linguagens dependem de indentação.

📖 Resumo

• Código inline usa um único acento grave; blocos de código usam três acentos graves
• Sempre adicione uma tag de linguagem aos blocos de código para realce de sintaxe
• Blocos de código identados (4 espaços) não são mais recomendados — prefira o estilo delimitado
• Blocos de código dentro de listas precisam de indentação extra
• Escape acentos graves dentro de blocos de código envolvendo com mais acentos graves
• Toda indentação e espaçamento em blocos de código é totalmente preservado

📝 Exercícios

1. Básico: Escreva uma seção em Markdown que inclua 3 trechos de código inline (nome de arquivo, nome de função, atalho de teclado) e 1 bloco de código com tag de linguagem.

2. Intermediário: Crie uma estrutura aninhada em seu documento Markdown — incorpore um bloco de código dentro de um item de lista não ordenada e incorpore um bloco de código dentro de uma citação em bloco.

3. Desafiador: Escreva uma seção em Markdown com três níveis de aninhamento de acentos graves (demonstrando como exibir um bloco de código que por sua vez exibe um bloco de código), e use quatro acentos graves para o envoltório externo para garantir a renderização correta.

Equipe Técnica Web-Tutorial

Uma plataforma de tutoriais mantida por diversos desenvolvedores. Cada tutorial é escrito e revisado por profissionais da área correspondente. Trabalhamos para manter nosso conteúdo preciso e confiável — se encontrar algum problema, avise-nos.

Sobre Nós