Pular para o conteúdo principal

Criando Arquivos Markdown com Blocos de Código

dica

Blocos de código bem formatados em Markdown tornam sua documentação mais legível e fácil de manter.

Blocos de Código Básicos​

Código Inline​

Use backticks simples para código inline:

  • Palavra única: variável
  • Múltiplas palavras: parâmetro de função
  • Com símbolos: npm install nome-do-pacote

Blocos de Código Delimitados​

Use triplos backticks para código multilinha:

Este é um bloco de código básico
Sem destaque de sintaxe

Destaque de Sintaxe Específico da Linguagem​

Adicione o nome da linguagem após os backticks de abertura:

const saudacao = 'Olá, Mundo!';
console.log(saudacao);
def saudar(nome):
    print(f"Olá, {nome}!")

Formatação Avançada​

Números de Linha​

Alguns processadores Markdown suportam números de linha:

// Esta linha está destacada
const x = 1;
// Estas linhas estão destacadas
// Esta também
const y = 2;

Barras de Título​

Adicione títulos aos seus blocos de código:

app.js
const express = require('express');
const app = express();

app.get('/', (req, res) => {
  res.send('Olá Mundo!');
});

Blocos de Diferença​

Mostre alterações de código com a sintaxe diff:

- const codigoAntigo = 'a ser removido';
+ const codigoNovo = 'a ser adicionado';
  const inalterado = 'permanece o mesmo';

Recursos MDX​

Blocos de Código Interativos​

// Exemplo JavaScript
function adicionar(a, b) {
  return a + b;
}

Exemplos de Código ao Vivo​

function Botao() {
  return (
    <button onClick={() => alert('Clicado!')}>
      Clique em mim
    </button>
  );
}

Linguagens Comuns​

Desenvolvimento Web​

index.html
<!DOCTYPE html>
<html>
<head>
    <title>Exemplo</title>
</head>
<body>
    <h1>Olá Mundo</h1>
</body>
</html>
styles.css
body {
    font-family: Arial, sans-serif;
    margin: 0;
    padding: 20px;
}
app.ts
interface Usuario {
    nome: string;
    idade: number;
}

const usuario: Usuario = {
    nome: "João",
    idade: 30
};

Desenvolvimento Backend​

Main.java
public class Main {
    public static void main(String[] args) {
        System.out.println("Olá, Mundo!");
    }
}
consulta.sql
SELECT usuarios.nome, pedidos.data_pedido
FROM usuarios
JOIN pedidos ON usuarios.id = pedidos.usuario_id
WHERE pedidos.status = 'concluído';

Melhores Práticas​

1. Formatação Consistente​

✅ Faça:

# Título

## Seção

\```javascript
// Código aqui
\```

❌ Não faça:

#Título
##Seção
\```javascript
//Código aqui
\```

2. Especificação Clara da Linguagem​

✅ Faça:

\```python
def exemplo():
    pass
\```

❌ Não faça:

\```
def exemplo():
    pass
\```

3. Indentação Correta​

✅ Faça:

- Item da lista
  \```javascript
  const x = 1;
  \```

❌ Não faça:

- Item da lista
\```javascript
const x = 1;
\```

Casos Especiais​

Comandos de Shell​

Para instruções de linha de comando:

# Comando com saída
$ npm install pacote
Instalando pacote...
Concluído!

Variáveis de Ambiente​

.env
API_KEY=sua_chave_api_aqui
DATABASE_URL=postgres://usuario:senha@localhost:5432/db

Arquivos de Configuração​

package.json
{
  "name": "projeto",
  "version": "1.0.0",
  "scripts": {
    "start": "node index.js"
  }
}

Solução de Problemas​

Problemas Comuns​

  1. Backticks dentro de Blocos de Código

    \`\`\`
    Use \` para código inline
    \`\`\`

  2. Quebras de Linha

    Isto requer dois espaços  
    para criar uma quebra de linha

  3. Caracteres de Escape

    \* Não é um item de lista
    \` Não é código inline

Integração com o Editor​

Atalhos do Cursor​

AçãoAtalho
Bloco de códigoCtrl + Shift + K
Código inlineCtrl + `
VisualizaçãoCtrl + Shift + V

Extensões​

Extensões Markdown recomendadas:

  • Markdown All in One
  • markdownlint
  • Markdown Preview Enhanced
dica

Use o recurso de visualização Markdown do Cursor para verificar sua formatação em tempo real!

Recursos Relacionados​