GitHub Flavored Markdown (GFM)

GitHub Flavored Markdown (GFM) là phiên bản Markdown nâng cao của GitHub với các tính năng bổ sung được thiết kế đặc biệt cho phát triển phần mềm và cộng tác. Hướng dẫn này bao gồm tất cả các phần mở rộng cú pháp đặc biệt có sẵn trên GitHub.

GitHub Flavored Markdown (GFM) là gì?

GitHub Flavored Markdown mở rộng cú pháp Markdown cơ bản với các tính năng giúp nó hữu ích hơn cho:

Tài liệu (READMEs, wikis)
Theo dõi vấn đề (issues)
Pull requests
Xem xét code
Quản lý dự án

Các tính năng GFM cốt lõi

1. Khối code có rào chắn

GFM hỗ trợ các khối code có rào chắn với cú pháp highlight riêng cho từng ngôn ngữ:

```javascript
function calculateSum(numbers) {
  return numbers.reduce((sum, num) => sum + num, 0);
}

const result = calculateSum([1, 2, 3, 4, 5]);
console.log(result); // Output: 15
```

javascript

function calculateSum(numbers) {
  return numbers.reduce((sum, num) => sum + num, 0);
}

const result = calculateSum([1, 2, 3, 4, 5]);
console.log(result); // Output: 15

2. Highlight cú pháp

GitHub hỗ trợ highlight cú pháp cho hàng trăm ngôn ngữ. Một số ngôn ngữ phổ biến bao gồm:

bash

# Bash script
echo "Hello GitHub!"

python

# Python script
def greet(name):
    return f"Hello, {name}!"

java

// Java code
public class HelloWorld {
    public static void main(String[] args) {
        System.out.println("Hello GitHub!");
    }
}

3. Danh sách task

Tạo danh sách task tương tác với các hộp kiểm:

markdown

- [x] Hoàn thành xác thực người dùng
- [x] Triển khai các API endpoints
- [ ] Viết unit tests
  - [ ] Backend tests
  - [ ] Frontend tests
- [ ] Deploy lên production

[x] Hoàn thành xác thực người dùng
[x] Triển khai các API endpoints
[ ] Viết unit tests
- [ ] Backend tests
- [ ] Frontend tests
[ ] Deploy lên production

4. Bảng

GFM cung cấp cú pháp đơn giản để tạo bảng:

markdown

| Tính năng         | Hỗ trợ | Mô tả                          |
|-------------------|--------|--------------------------------|
| Fenced Code       | ✅     | Highlight riêng cho ngôn ngữ   |
| Task Lists        | ✅     | Hộp kiểm tương tác             |
| Tables            | ✅     | Hiển thị dữ liệu có cấu trúc   |
| Mentions          | ✅     | Thông báo người dùng và nhóm  |
| Emoji             | ✅     | Biểu hiện trực quan            |

Tính năng	Hỗ trợ	Mô tả
Fenced Code	✅	Highlight riêng cho ngôn ngữ
Task Lists	✅	Hộp kiểm tương tác
Tables	✅	Hiển thị dữ liệu có cấu trúc
Mentions	✅	Thông báo người dùng và nhóm
Emoji	✅	Biểu hiện trực quan

5. Mentions

Đề cập người dùng hoặc nhóm để thông báo cho họ:

markdown

@username - Đề cập một người dùng cụ thể
@team-name - Đề cập một nhóm

6. Emoji

Thêm emoji bằng cách sử dụng shortcodes:

markdown

:smile: - 😊
:thumbsup: - 👍
:heart: - ❤️
:rocket: - 🚀
:warning: - ⚠️

😄 - 😊 👍 - 👍 ❤️ - ❤️ 🚀 - 🚀 ⚠️ - ⚠️

7. Liên kết tự động

GFM tự động liên kết một số loại nội dung nhất định:

Số Issue và Pull Request

markdown

#123 - Liên kết đến issue 123
PR #456 - Liên kết đến pull request 456

Hash SHA

markdown

a1b2c3d - Liên kết đến commit với SHA này

Đề cập người dùng trong Issues/PRs

markdown

@username - Tự động liên kết đến hồ sơ người dùng

URLs

markdown

https://github.com - Tự động trở thành liên kết

8. Gạch ngang

GFM hỗ trợ văn bản gạch ngang:

markdown

~~Văn bản này bị gạch ngang~~

~~Văn bản này bị gạch ngang~~

9. Tham chiếu liên kết tự động

GFM tự động tạo liên kết cho:

HTTP/HTTPS URLs
Địa chỉ email
Số issue/PR của GitHub
Commit SHAs

markdown

https://github.com/markdownlang/markdownlang.com
user@example.com
#123
PR #456
a1b2c3d4e5f6

10. Highlight dòng khối code

Highlight các dòng cụ thể trong khối code:

```javascript{2,4}
function calculateSum(numbers) {
  return numbers.reduce((sum, num) => sum + num, 0); // Highlighted
}

const result = calculateSum([1, 2, 3, 4, 5]); // Highlighted
console.log(result);
```

javascript

function calculateSum(numbers) {
  return numbers.reduce((sum, num) => sum + num, 0); // Highlighted
}

const result = calculateSum([1, 2, 3, 4, 5]); // Highlighted
console.log(result);

11. Highlight cú pháp Diff

Highlight các thay đổi trong code với cú pháp diff:

```diff
- const oldFunction = () => {
-   return "old value";
- };
+
+ const newFunction = () => {
+   return "new value";
+ };
```

diff

- const oldFunction = () => {
-   return "old value";
- };
+
+ const newFunction = () => {
+   return "new value";
+ };

12. Đánh dấu cụ thể của GitHub

Cảnh báo

Sử dụng cú pháp đặc biệt cho cảnh báo trong tài liệu GitHub:

markdown

> [!NOTE]
> Đây là cảnh báo ghi chú.

> [!TIP]
> Đây là cảnh báo mẹo.

> [!IMPORTANT]
> Đây là cảnh báo quan trọng.

> [!WARNING]
> Đây là cảnh báo cảnh báo.

> [!CAUTION]
> Đây là cảnh báo thận trọng.

NOTE

Đây là cảnh báo ghi chú.

TIP

Đây là cảnh báo mẹo.

IMPORTANT

Đây là cảnh báo quan trọng.

WARNING

Đây là cảnh báo cảnh báo.

CAUTION

Đây là cảnh báo thận trọng.

Liên kết tương đối

Sử dụng liên kết tương đối để điều hướng giữa các tệp trong cùng một repository:

markdown

[README](/README.md)
[Hướng dẫn đóng góp](/CONTRIBUTING.md)
[Tài liệu API](/docs/api.md)

Liên kết hình ảnh với văn bản hover

markdown

![GitHub Logo](/images/github-logo.png "GitHub Logo - Văn bản hover")

Sử dụng GFM nâng cao

1. Danh sách lồng nhau với danh sách task

Kết hợp danh sách lồng nhau với danh sách task:

markdown

## Lộ trình dự án

### Giai đoạn 1: Lập kế hoạch
- [x] Xác định phạm vi dự án
- [x] Xác định yêu cầu
  - [x] Yêu cầu chức năng
  - [x] Yêu cầu phi chức năng
- [x] Tạo dòng thời gian

### Giai đoạn 2: Phát triển
- [x] Thiết lập cấu trúc dự án
- [ ] Triển khai các tính năng cốt lõi
  - [x] Xác thực
  - [ ] Dashboard
  - [ ] Tích hợp API

2. Bảng với emoji và liên kết

Nâng cao bảng với emoji và liên kết:

markdown

| Thành phần | Trạng thái | Người duy trì |
|------------|------------|---------------|
| Xác thực | ✅ Ổn định | @johndoe |
| Cơ sở dữ liệu | ⚠️ Cần cập nhật | @janedoe |
| API | 🚧 Đang thực hiện | @bobsmith |
| UI | ✅ Ổn định | @alicesmith |

Thành phần	Trạng thái	Người duy trì
Xác thực	✅ Ổn định	@johndoe
Cơ sở dữ liệu	⚠️ Cần cập nhật	@janedoe
API	🚧 Đang thực hiện	@bobsmith
UI	✅ Ổn định	@alicesmith

3. Khối code trong danh sách

Bao gồm các khối code trong danh sách:

markdown

1. Cài đặt dependencies:

   ```bash
   npm install

Chạy development server:
bash
```
npm run dev
```
Build cho production:
bash
```
npm run build
```


### 4. Khối trích dẫn với code

Kết hợp trích dẫn với khối code:

```markdown
> **Mẹo chuyên nghiệp:** Sử dụng lệnh sau để nhanh chóng kiểm tra trạng thái Git của bạn:
>
> ```bash
> git status
> ```

Mẹo chuyên nghiệp: Sử dụng lệnh sau để nhanh chóng kiểm tra trạng thái Git của bạn:
bash
git status

GFM trong các ngữ cảnh GitHub khác nhau

Tệp README

Các tệp README hỗ trợ tất cả các tính năng GFM và tự động được hiển thị trên các trang repository.

Issues và Pull Requests

Sử dụng danh sách task để theo dõi tiến độ
Đề cập thành viên trong nhóm để cộng tác
Bao gồm các đoạn code với highlight cú pháp
Tham chiếu các issues/PRs liên quan bằng cú pháp #123

Bình luận

Sử dụng emoji để phản ứng nhanh
Tham chiếu các dòng trong code với bình luận dòng
Sử dụng khối trích dẫn để phản hồi các điểm cụ thể

Wikis

Tổ chức nội dung với các trang lồng nhau
Sử dụng bảng cho dữ liệu có cấu trúc
Bao gồm các ví dụ code với highlight cú pháp

Thực hành tốt nhất

1. Phong cách code

markdown

<!-- ✅ Tốt -->
```javascript
// Sử dụng tên hàm mô tả
function calculateTotal(items) {
  return items.reduce((sum, item) => sum + item.price, 0);
}

javascript

function f(i){return i.reduce((a,b)=>a+b.p,0)}```

2. Thiết kế bảng

markdown

<!-- ✅ Tốt -->
| Tính năng | Mô tả | Trạng thái |
|-----------|-------|------------|
| Tính năng 1 | Mô tả ngắn | ✅ |
| Tính năng 2 | Mô tả khác | 🚧 |

<!-- ❌ Tránh -->
| Tính năng | Mô tả | Trạng thái | | | |
|-----------|-------|------------|---|---|---|
| Tính năng 1 | Mô tả này quá dài và làm cho bảng khó đọc trên thiết bị di động | ✅ | | | |

3. Sử dụng danh sách task

markdown

<!-- ✅ Tốt -->
## Sprint Backlog
- [x] Hoàn thành trang hồ sơ người dùng
- [ ] Triển khai chức năng tìm kiếm
  - [x] Backend API
  - [ ] Frontend component
- [ ] Viết tài liệu

<!-- ❌ Tránh -->
- [ ] Task 1
- [ ] Task 2
- [ ] Task 3
- [ ] Task 4
- [ ] Task 5
(Quá nhiều task mà không có tổ chức)

GFM so với Markdown tiêu chuẩn

Tính năng	Markdown tiêu chuẩn	GitHub Flavored Markdown
Fenced Code Blocks	❌	✅
Highlight cú pháp	❌	✅
Danh sách task	❌	✅
Bảng	❌	✅
Gạch ngang	❌	✅
Emoji	❌	✅
Mentions	❌	✅
Liên kết tự động	Hạn chế	Rộng rãi

Công cụ làm việc với GFM

Trình soạn thảo cục bộ

Visual Studio Code - Xem trước GFM và các tiện ích mở rộng
Typora - Hiển thị GFM thời gian thực
Mark Text - Hỗ trợ GFM

Công cụ trực tuyến

GitHub Gist - Tạo và chia sẻ các đoạn GFM
Dillinger - Trình soạn thảo GFM trực tuyến
StackEdit - Hỗ trợ GFM với đồng bộ đám mây

Công cụ dòng lệnh

glow - Trình hiển thị GFM terminal
pandoc - Chuyển đổi GFM sang các định dạng khác
marked - Trình phân tích cú pháp GFM Node.js

Các vấn đề phổ biến và cách khắc phục

1. Khối code không highlight

Vấn đề: Khối code không hiển thị highlight cú pháp

Khắc phục: Đảm bảo bạn đang chỉ định đúng ngôn ngữ:

markdown

<!-- ✅ Đúng -->
```javascript
console.log("Hello");

jsx

console.log("Hello"); // Sử dụng jsx thay vì javascript cho code không phải JSX


### 2. Hộp kiểm danh sách task không hoạt động

**Vấn đề:** Hộp kiểm danh sách task không tương tác

**Khắc phục:** Đảm bảo cú pháp đúng (có khoảng trắng giữa `-` và `[ ]`):

```markdown
<!-- ✅ Đúng -->
- [ ] Task

<!-- ❌ Sai -->
-[ ] Task (không có khoảng trắng)
-[x] Task (không có khoảng trắng)

3. Bảng không hiển thị đúng

Vấn đề: Các cột bảng không thẳng hàng

Khắc phục: Đảm bảo các dấu pipe được căn chỉnh đúng:

markdown

<!-- ✅ Đúng -->
| Column 1 | Column 2 |
|----------|----------|
| Data 1   | Data 2   |

<!-- ❌ Sai -->
|Column 1|Column 2|
|--|--|
|Data 1|Data 2|

Các bước tiếp theo

GitHub Flavored Markdown là một công cụ mạnh mẽ cho giao tiếp và cộng tác trong phát triển phần mềm. Bằng cách thành thạo các tính năng này, bạn có thể tạo tài liệu hiệu quả hơn, theo dõi issues tốt hơn và cộng tác hiệu quả hơn với nhóm của bạn.

GitHub Flavored Markdown (GFM) ​