Sintaxe de código

Código é essencial em documentação técnica. O Markdown permite exibir código em linha e em blocos, com ou sem realce de sintaxe.

Código inline

Sintaxe básica

Usa crases ` a envolver o código:

markdown

Este é um exemplo de `código inline`.
Use a função `console.log()` para exibir informações.

Resultado:

Este é um exemplo de código inline. Use a função console.log() para exibir informações.

Código contendo crases

Se o código tiver crases, use duas crases:

markdown

``usar `console.log()` na função``

Resultado:

usar `console.log()` na função

Várias crases

markdown

```código contendo várias crases `` ` ``` aqui```

Resultado:

código contendo várias crases `` ` aqui```

Blocos de código

Bloco indentado

Usa 4 espaços ou 1 tabulação:

markdown

    function hello() {
        console.log("Hello, World!");
    }

Resultado:

function hello() {
    console.log("Hello, World!");
}

Bloco cercado (fenced)

Usa três crases ``` ou tildes ~~~:

markdown

```
function hello() {
    console.log("Hello, World!");
}
```

Resultado:

function hello() {
    console.log("Hello, World!");
}

Especificar linguagem

Indica a linguagem após as crases para ativar o destaque:

markdown

```javascript
function hello(name) {
    console.log(`Hello, ${name}!`);
}
```

Resultado:

javascript

function hello(name) {
    console.log(`Hello, ${name}!`);
}

Exemplos de linguagens

JavaScript

markdown

```javascript
// Exemplo de função assíncrona
async function fetchData(url) {
    try {
        const response = await fetch(url);
        const data = await response.json();
        return data;
    } catch (error) {
        console.error('Error:', error);
    }
}
```

渲染效果：

javascript

// 异步函数示例
async function fetchData(url) {
    try {
        const response = await fetch(url);
        const data = await response.json();
        return data;
    } catch (error) {
        console.error('Error:', error);
    }
}

Python

markdown

```python
# Exemplo de classe
class Calculator:
    def __init__(self):
        self.result = 0
    
    def add(self, x, y):
        return x + y
    
    def multiply(self, x, y):
        return x * y

# Exemplo de uso
calc = Calculator()
print(calc.add(5, 3))
```

渲染效果：

python

# 类定义示例
class Calculator:
    def __init__(self):
        self.result = 0
    
    def add(self, x, y):
        return x + y
    
    def multiply(self, x, y):
        return x * y

# 使用示例
calc = Calculator()
print(calc.add(5, 3))

HTML

markdown

```html
<!DOCTYPE html>
<html lang="pt-PT">
<head>
    <meta charset="UTF-8">
    <title>Página de exemplo</title>
</head>
<body>
    <h1>Bem‑vindo ao Markdown</h1>
    <p>Este é um parágrafo de exemplo.</p>
</body>
</html>
```

渲染效果：

html

<!DOCTYPE html>
<html lang="zh-CN">
<head>
    <meta charset="UTF-8">
    <title>示例页面</title>
</head>
<body>
    <h1>欢迎使用 Markdown</h1>
    <p>这是一个示例段落。</p>
</body>
</html>

CSS

markdown

```css
/* Exemplo responsivo */
.container {
    max-width: 1200px;
    margin: 0 auto;
    padding: 0 20px;
}

@media (max-width: 768px) {
    .container {
        padding: 0 10px;
    }
}

.button {
    background-color: #007bff;
    color: white;
    border: none;
    padding: 10px 20px;
    border-radius: 4px;
    cursor: pointer;
}

.button:hover {
    background-color: #0056b3;
}
```

渲染效果：

css

/* 响应式布局示例 */
.container {
    max-width: 1200px;
    margin: 0 auto;
    padding: 0 20px;
}

@media (max-width: 768px) {
    .container {
        padding: 0 10px;
    }
}

.button {
    background-color: #007bff;
    color: white;
    border: none;
    padding: 10px 20px;
    border-radius: 4px;
    cursor: pointer;
}

.button:hover {
    background-color: #0056b3;
}

Bash/Shell

markdown

```bash
#!/bin/bash

# Exemplo: processamento em lote
for file in *.txt; do
    if [ -f "$file" ]; then
        echo "Processing $file"
        cp "$file" "backup_$file"
    fi
done

# Função
function check_dependencies() {
    command -v git >/dev/null 2>&1 || {
        echo "Git is required but not installed."
        exit 1
    }
}

check_dependencies
echo "All dependencies satisfied."
```

渲染效果：

bash

#!/bin/bash

# 脚本示例：批量处理文件
for file in *.txt; do
    if [ -f "$file" ]; then
        echo "Processing $file"
        cp "$file" "backup_$file"
    fi
done

# 函数定义
function check_dependencies() {
    command -v git >/dev/null 2>&1 || {
        echo "Git is required but not installed."
        exit 1
    }
}

check_dependencies
echo "All dependencies satisfied."

JSON

markdown

```json
{
  "name": "markdown-tutorial",
  "version": "1.0.0",
  "description": "Markdown 中文教程",
  "main": "index.js",
  "scripts": {
    "dev": "vitepress dev docs",
    "build": "vitepress build docs",
    "preview": "vitepress preview docs"
  },
  "dependencies": {
    "vitepress": "^1.0.0"
  },
  "author": "Your Name",
  "license": "MIT"
}
```

渲染效果：

json

{
  "name": "markdown-tutorial",
  "version": "1.0.0",
  "description": "Markdown 中文教程",
  "main": "index.js",
  "scripts": {
    "dev": "vitepress dev docs",
    "build": "vitepress build docs",
    "preview": "vitepress preview docs"
  },
  "dependencies": {
    "vitepress": "^1.0.0"
  },
  "author": "Your Name",
  "license": "MIT"
}

高级代码块功能

行号显示

某些 Markdown 处理器支持显示行号：

markdown

```javascript {1}
// Esta é a primeira linha
function example() {
    console.log("Hello");
}
```

行高亮

Destacar linhas específicas:

markdown

```javascript {2-3}
function example() {
    console.log("linha em destaque");  // destaque
    return true;                        // destaque
}
```

文件名显示

Exibir nome do ficheiro:

markdown

```javascript title="app.js"
const express = require('express');
const app = express();

app.get('/', (req, res) => {
    res.send('Hello World!');
});
```

Erros comuns e soluções

1. 反引号数量不匹配

markdown

❌ Incorreto:
```javascript
function hello() {
    console.log("Hello");
}
``  ← número de crases incorreto

✅ Correto:
```javascript
function hello() {
    console.log("Hello");
}
```

2. 缩进不一致

markdown

❌ Incorreto: bloco indentado
    Primeira linha (4 espaços)
  Segunda linha (2 espaços)  ← indentação inconsistente

✅ Correto: bloco indentado
    Primeira linha (4 espaços)
    Segunda linha (4 espaços)

3. 语言名称错误

markdown

❌ Incorreto:
```js  ← usa javascript
function hello() {}
```

✅ Correto:
```javascript
function hello() {}
```

Lista de linguagens suportadas

Identificadores comuns:

| Linguagem | Identificador | Exemplo | | JavaScript | javascript, js | function(){} | | Python | python, py | def function(): | | Java | java | public class{} | | C++ | cpp, c++ | #include <iostream> | | C# | csharp, cs | public class{} | | Go | go | func main(){} | | Rust | rust, rs | fn main(){} | | TypeScript | typescript, ts | interface{} | | PHP | php | <?php | | Ruby | ruby, rb | def method | | SQL | sql | SELECT * FROM | | HTML | html | <div></div> | | CSS | css | .class{} | | XML | xml | <root></root> | | YAML | yaml, yml | key: value | | Markdown | markdown, md | # Title | | Bash | bash, sh | #!/bin/bash | | PowerShell | powershell, ps1 | Get-Process | | Dockerfile | dockerfile | FROM ubuntu |

Boas práticas

1) Escolhe o formato adequado

markdown

✅ Recomenda‑se: inline para trechos curtos
Usa `Array.map()` para processar arrays.

✅ Recomenda‑se: bloco para trechos longos
function processArray(arr) {
    return arr.map(item => item * 2);
}

2) Comentários úteis

markdown

✅ Recomenda‑se: comentários explicativos
```javascript
// Calcula a média dos elementos
function calculateAverage(numbers) {
    const sum = numbers.reduce((acc, num) => acc + num, 0);
    return sum / numbers.length;
}
```

3) Linguagem correta

markdown

✅ Recomenda‑se: indicar linguagem correta
```typescript
interface User {
    id: number;
    name: string;
}
```

❌ Evitar: linguagem ambígua
```text
interface User {
    id: number;
    name: string;
}
```

4) Mantém o código conciso

markdown

✅ Recomenda‑se: só a lógica central
```javascript
// 用户认证
function authenticate(token) {
    return validateToken(token);
}
```

❌ Evitar: detalhes irrelevantes
```javascript
// 这里是很长的代码，包含了很多不相关的细节...
```

Saída HTML

Conversão para HTML:

markdown

`código inline`

Converte para:

html

<code>código inline</code>

Bloco de código:

markdown

```javascript
function hello() {}
```

Converte para:

html

<pre><code class="language-javascript">
function hello() {}
</code></pre>

Exemplos práticos

Documentação de API

markdown

## Login de utilizador

Faz POST para `/api/login`:

```bash
curl -X POST https://api.example.com/login \
  -H "Content-Type: application/json" \
  -d '{
    "email": "user@example.com",
    "password": "password123"
  }'
```

Resposta:

```json
{
  "success": true,
  "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "user": {
    "id": 1,
    "email": "user@example.com",
    "name": "Zhang"
  }
}
```

Ficheiros de configuração

markdown

## Configuração do projeto

Cria o ficheiro `config.json`:

```json
{
  "database": {
    "host": "localhost",
    "port": 5432,
    "name": "myapp"
  },
  "server": {
    "port": 3000,
    "host": "0.0.0.0"
  }
}
```

Atualiza os scripts no `package.json`:

```json
{
  "scripts": {
    "start": "node server.js",
    "dev": "nodemon server.js",
    "test": "jest"
  }
}
```

Guia de instalação

markdown

## Ambiente

1. Instalar Node.js:

```bash
# macOS (Homebrew)
brew install node

# Ubuntu/Debian
sudo apt update
sudo apt install nodejs npm

# Windows (Chocolatey)
choco install nodejs
```

2. Verificar:

```bash
node --version
npm --version
```

3. Inicializar projeto:

```bash
mkdir my-project
cd my-project
npm init -y
```

Sintaxe relacionada

Exercícios

Cria:

Um conjunto com várias linguagens
Um tutorial de API (request e response)
Um guia de instalação por SO
Um template de configuração com comentários

Sintaxe de código ​

Código inline ​

Sintaxe básica ​

Código contendo crases ​

Várias crases ​

Blocos de código ​

Bloco indentado ​

Bloco cercado (fenced) ​

Especificar linguagem ​

Exemplos de linguagens ​

JavaScript ​

Python ​

HTML ​

CSS ​

Bash/Shell ​

JSON ​

高级代码块功能 ​

行号显示 ​

行高亮 ​

文件名显示 ​

Erros comuns e soluções ​

1. 反引号数量不匹配 ​

2. 缩进不一致 ​

3. 语言名称错误 ​

Lista de linguagens suportadas ​

Boas práticas ​

1) Escolhe o formato adequado ​

2) Comentários úteis ​

3) Linguagem correta ​

4) Mantém o código conciso ​

Saída HTML ​

Exemplos práticos ​

Documentação de API ​

Ficheiros de configuração ​

Guia de instalação ​

Sintaxe relacionada ​

Exercícios ​

Sintaxe de código

Código inline

Sintaxe básica

Código contendo crases

Várias crases

Blocos de código

Bloco indentado

Bloco cercado (fenced)

Especificar linguagem

Exemplos de linguagens

JavaScript

Python

HTML

CSS

Bash/Shell

JSON

高级代码块功能

行号显示

行高亮

文件名显示

Erros comuns e soluções

1. 反引号数量不匹配

2. 缩进不一致

3. 语言名称错误

Lista de linguagens suportadas

Boas práticas

1) Escolhe o formato adequado

2) Comentários úteis

3) Linguagem correta

4) Mantém o código conciso

Saída HTML

Exemplos práticos

Documentação de API

Ficheiros de configuração

Guia de instalação

Sintaxe relacionada

Exercícios