Cú pháp mã

Mã nguồn là thành phần quan trọng trong tài liệu kỹ thuật. Markdown cung cấp nhiều cách để hiển thị mã, bao gồm mã nội tuyến và khối mã.

Mã nội tuyến

Cú pháp cơ bản

Bao quanh đoạn mã bằng dấu backtick `:

markdown

Đây là một ví dụ về `mã nội dòng`.
Sử dụng hàm `console.log()` để xuất thông tin.

Kết quả hiển thị:

Đây là một ví dụ về mã nội dòng. Sử dụng hàm console.log() để xuất thông tin.

Mã có chứa backtick

Khi bản thân đoạn mã có chứa backtick, dùng hai backtick để bao quanh:

markdown

``Sử dụng hàm `console.log()```

Kết quả hiển thị:

``Sử dụng hàm `console.log()```

Xử lý nhiều backtick

markdown

```Mã chứa nhiều dấu backtick `` ` ``` ở đây```

Kết quả hiển thị:

Mã chứa nhiều dấu backtick `` ` ở đây```

Khối mã

Khối mã dùng thụt đầu dòng

Dùng 4 dấu cách hoặc 1 tab để thụt đầu dòng:

markdown

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

Kết quả hiển thị:

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

Khối mã fenced

Dùng ba backtick ``` hoặc ba ký hiệu ngã ~~~ để bao quanh mã:

markdown

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

Kết quả hiển thị:

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

Chỉ định ngôn ngữ lập trình

Chỉ định tên ngôn ngữ sau ``` để bật tô sáng cú pháp:

markdown

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

Kết quả hiển thị:

javascript

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

Ví dụ các ngôn ngữ lập trình phổ biến

JavaScript

markdown

```javascript
// Ví dụ hàm bất đồng bộ
async function fetchData(url) {
    try {
        const response = await fetch(url);
        const data = await response.json();
        return data;
    } catch (error) {
        console.error('Error:', error);
    }
}
```

Kết quả hiển thị:

javascript

// Ví dụ hàm bất đồng bộ
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
# Ví dụ định nghĩa lớp
class Calculator:
    def __init__(self):
        self.result = 0
    
    def add(self, x, y):
        return x + y
    
    def multiply(self, x, y):
        return x * y

# Ví dụ sử dụng
calc = Calculator()
print(calc.add(5, 3))
```

Kết quả hiển thị:

python

# Ví dụ định nghĩa lớp
class Calculator:
    def __init__(self):
        self.result = 0
    
    def add(self, x, y):
        return x + y
    
    def multiply(self, x, y):
        return x * y

# Ví dụ sử dụng
calc = Calculator()
print(calc.add(5, 3))

HTML

markdown

```html
<!DOCTYPE html>
<html lang="vi">
<head>
    <meta charset="UTF-8">
    <title>Trang ví dụ</title>
</head>
<body>
    <h1>Chào mừng đến với Markdown</h1>
    <p>Đây là một đoạn văn ví dụ.</p>
</body>
</html>
```

Hiệu ứng hiển thị:

html

<!DOCTYPE html>
<html lang="vi">
<head>
    <meta charset="UTF-8">
    <title>Trang ví dụ</title>
</head>
<body>
    <h1>Chào mừng đến với Markdown</h1>
    <p>Đây là một đoạn văn ví dụ.</p>
</body>
</html>

CSS

markdown

```css
/* Ví dụ bố cục responsive */
.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;
}
```

Kết quả hiển thị:

css

/* Ví dụ bố cục responsive */
.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

# Ví dụ script: xử lý hàng loạt tệp
for file in *.txt; do
    if [ -f "$file" ]; then
        echo "Processing $file"
        cp "$file" "backup_$file"
    fi
done

# Định nghĩa hàm
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."
```

Kết quả hiển thị:

bash

#!/bin/bash

# Ví dụ script: xử lý hàng loạt tệp
for file in *.txt; do
    if [ -f "$file" ]; then
        echo "Processing $file"
        cp "$file" "backup_$file"
    fi
done

# Định nghĩa hàm
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": "Hướng dẫn Markdown (tiếng Trung)",
  "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"
}
```

Kết quả hiển thị:

json

{
  "name": "markdown-tutorial",
  "version": "1.0.0",
"description": "Hướng dẫn Markdown (tiếng Trung)",
  "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"
}

Tính năng nâng cao cho khối mã

Hiển thị số dòng

Một số bộ xử lý Markdown hỗ trợ hiển thị số dòng:

markdown

```javascript {1}
// Đây là dòng đầu tiên
function example() {
    console.log("Hello");
}
```

Tô sáng dòng

Tô sáng các dòng cụ thể:

markdown

```javascript {2-3}
function example() {
    console.log("Dòng này được tô sáng");  // tô sáng
    return true;                              // tô sáng
}
```

Hiển thị tên tệp

Hiển thị tên tệp mã nguồn:

markdown

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

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

Lỗi thường gặp và cách khắc phục

1. Số lượng backtick không khớp

markdown

❌ Sai:
```javascript
function hello() {
    console.log("Hello");
}
``  ← Số lượng backtick không khớp

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

2. Thụt đầu dòng không nhất quán

markdown

❌ Sai: Khối mã thụt đầu dòng
    Dòng 1 (4 dấu cách)
  Dòng 2 (2 dấu cách)  ← Thụt đầu dòng không nhất quán

✅ Đúng: Khối mã thụt đầu dòng
    Dòng 1 (4 dấu cách)
    Dòng 2 (4 dấu cách)

3. Tên ngôn ngữ không đúng

markdown

❌ Sai:
```js  ← Nên dùng "javascript"
function hello() {}
```

✅ Đúng:
```javascript
function hello() {}
```

Danh sách ngôn ngữ được hỗ trợ

Các định danh ngôn ngữ thường dùng:

Ngôn ngữ	Định danh	Ví dụ
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`

Thực hành tốt

1. Chọn định dạng mã phù hợp

markdown

✅ Khuyến nghị: Đoạn mã ngắn dùng định dạng nội tuyến
Sử dụng phương thức `Array.map()` để xử lý mảng.

✅ Khuyến nghị: Đoạn mã dài dùng khối mã
function processArray(arr) {
    return arr.map(item => item * 2);
}

2. Thêm chú thích phù hợp

markdown

✅ Khuyến nghị: Có chú thích giải thích
```javascript
// Tính trung bình các phần tử trong mảng
function calculateAverage(numbers) {
    const sum = numbers.reduce((acc, num) => acc + num, 0);
    return sum / numbers.length;
}
```

3. Dùng định danh ngôn ngữ chính xác

markdown

✅ Khuyến nghị: Chỉ định ngôn ngữ rõ ràng
```typescript
interface User {
    id: number;
    name: string;
}
```

❌ Không khuyến nghị: Định danh ngôn ngữ mơ hồ
```text
interface User {
    id: number;
    name: string;
}
```

4. Giữ mã nguồn đơn giản

markdown

✅ Khuyến nghị: Trình bày logic cốt lõi
```javascript
// Xác thực người dùng
function authenticate(token) {
    return validateToken(token);
}
```

❌ Không khuyến nghị: Quá nhiều chi tiết không cần thiết
```javascript
// Đoạn mã rất dài chứa nhiều chi tiết không liên quan...
```

Đầu ra HTML

Mã trong Markdown chuyển thành HTML:

markdown

`mã nội tuyến`

Chuyển thành:

html

<code>mã nội tuyến</code>

Khối mã:

markdown

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

Chuyển thành:

html

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

Ví dụ thực tiễn

Tài liệu API

markdown

## Đăng nhập người dùng

Gửi yêu cầu POST tới `/api/login`:

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

Ví dụ phản hồi:

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

Ví dụ tệp cấu hình

markdown

## Cấu hình dự án

Tạo tệp `config.json`:

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

Cập nhật các script trong `package.json`:

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

Hướng dẫn cài đặt

markdown

## Cấu hình môi trường

1. Cài đặt Node.js:

```bash
# macOS (dùng Homebrew)
brew install node

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

# Windows (dùng Chocolatey)
choco install nodejs
```

2. Kiểm tra cài đặt:

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

3. Khởi tạo dự án:

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

Cú pháp liên quan

Khối mã fenced - Tính năng mã mở rộng
Cú pháp nhấn mạnh - Định dạng văn bản
Cú pháp liên kết - Tạo liên kết
Ký tự thoát - Xử lý ký tự đặc biệt

Bài tập

Hãy thử tạo các nội dung sau:

Một bộ sưu tập ví dụ mã cho nhiều ngôn ngữ lập trình
Một hướng dẫn sử dụng API, bao gồm mã yêu cầu và phản hồi
Một hướng dẫn cài đặt, bao gồm lệnh cho các hệ điều hành khác nhau
Một mẫu tệp cấu hình, có chú thích chi tiết

Cú pháp mã ​

Mã nội tuyến ​

Cú pháp cơ bản ​

Mã có chứa backtick ​

Xử lý nhiều backtick ​

Khối mã ​

Khối mã dùng thụt đầu dòng ​

Khối mã fenced ​

Chỉ định ngôn ngữ lập trình ​

Ví dụ các ngôn ngữ lập trình phổ biến ​

JavaScript ​

Python ​

HTML ​

CSS ​

Bash/Shell ​

JSON ​

Tính năng nâng cao cho khối mã ​

Hiển thị số dòng ​

Tô sáng dòng ​

Hiển thị tên tệp ​

Lỗi thường gặp và cách khắc phục ​

1. Số lượng backtick không khớp ​

2. Thụt đầu dòng không nhất quán ​

3. Tên ngôn ngữ không đúng ​

Danh sách ngôn ngữ được hỗ trợ ​

Thực hành tốt ​

1. Chọn định dạng mã phù hợp ​

2. Thêm chú thích phù hợp ​

3. Dùng định danh ngôn ngữ chính xác ​

4. Giữ mã nguồn đơn giản ​

Đầu ra HTML ​

Ví dụ thực tiễn ​

Tài liệu API ​

Ví dụ tệp cấu hình ​

Hướng dẫn cài đặt ​

Cú pháp liên quan ​

Bài tập ​

Cú pháp mã

Mã nội tuyến

Cú pháp cơ bản

Mã có chứa backtick

Xử lý nhiều backtick

Khối mã

Khối mã dùng thụt đầu dòng

Khối mã fenced

Chỉ định ngôn ngữ lập trình

Ví dụ các ngôn ngữ lập trình phổ biến

JavaScript

Python

HTML

CSS

Bash/Shell

JSON

Tính năng nâng cao cho khối mã

Hiển thị số dòng

Tô sáng dòng

Hiển thị tên tệp

Lỗi thường gặp và cách khắc phục

1. Số lượng backtick không khớp

2. Thụt đầu dòng không nhất quán

3. Tên ngôn ngữ không đúng

Danh sách ngôn ngữ được hỗ trợ

Thực hành tốt

1. Chọn định dạng mã phù hợp

2. Thêm chú thích phù hợp

3. Dùng định danh ngôn ngữ chính xác

4. Giữ mã nguồn đơn giản

Đầu ra HTML

Ví dụ thực tiễn

Tài liệu API

Ví dụ tệp cấu hình

Hướng dẫn cài đặt

Cú pháp liên quan

Bài tập