Word đến GitHub Markdown: Định dạng tài liệu cho GitHub READMEs và các vấn đề

GitHub sử dụng một phương ngữ Markdown được gọi là GitHub Có hương vị Markdown (GFM). It’s mostly standard Markdown with a few extras — fenced code blocks with syntax highlighting, task lists, tables, and automatic link detection. If you’re converting a Word document into a GitHub README or wiki page, here’s what you need to know.

GitHub có hương vị Markdown là gì?

GFM là GitHubs mở rộng của CommonMark. Các bổ sung quan trọng nhất khi chuyển đổi từ Word là:

Các khối mã được bao vây với mã nhận dạng ngôn ngữ (```python)
Bảng sử dụng ngữ pháp pipe
Danh sách nhiệm vụ using - [ ] and - [x]
Đánh qua using ~~text~~
Các liên kết tự động URL trần trở thành có thể nhấp vào

Chuyển đổi tài liệu Word của bạn tại WordToMD và bạn sẽ nhận được GFM tương thích đầu ra theo mặc định.

Word Styles → GFM Elements

Word Nguyên tố	GFM Sản lượng
Nhóm 1	`# H1`
Nhóm 2	`## H2`
Dũng cảm	`bold`
Đọc theo đường nét	`italic`
Bảng	Bàn ống
Danh sách dấu chấm	`- item`
Danh sách được đánh số	`1. item`
Hyperlink	`[text](url)`
Phông chữ một không gian	`code`
Đánh qua	`~~text~~`

GitHub-Các tính năng cụ thể để thêm sau khi chuyển đổi

Danh sách nhiệm vụ

Word không có một phần tử danh sách tác vụ bản địa. Nếu bạn có hộp kiểm trong Word doc, chúng sẽ chuyển đổi thành văn bản đơn giản. Sau khi chuyển đổi, định dạng chúng thành danh sách nhiệm vụ GFM:

- [x] Completed item
- [ ] Pending item
- [ ] Another pending item

Chúng được hiển thị như hộp kiểm tương tác trong các tệp GitHub Issues, Pull Requests và project README.

Các khối mã được bao vây với đánh dấu cú pháp

Văn bản không gian đơn từ Word chuyển đổi thành mã nội tuyến. Đối với các khối mã nhiều dòng trên GitHub, sử dụng cú pháp được bao vây với một mã nhận dạng ngôn ngữ:

```javascript
function greet(name) {
  return `Hello, ${name}!`;
}


GitHub supports dozens of languages. See [Markdown Code Blocks Guide](/blog/markdown-code-blocks-guide) for the full language list and syntax rules.

### Alerts (GitHub-Specific Callouts)

GitHub renders special blockquote syntax as colored callout boxes:

```markdown
> [!NOTE]
> This is a note callout.

> [!WARNING]
> This is a warning.

> [!TIP]
> This is a helpful tip.

Nếu tài liệu Word của bạn có hộp gọi hoặc ghi chú được làm nổi bật, chuyển đổi chúng thành cú pháp cảnh báo GFM này sau khi chuyển đổi ban đầu.

Cấu trúc README từ Word Tài liệu

Một phần mềm README điển hình tuân theo cấu trúc này:

# Project Name

Short description.

## Installation

## Usage

## Configuration

## Contributing

## License

Nếu tài liệu Word của bạn là một quy định dự án hoặc bản thảo tài liệu, so sánh các phần của nó với các tiêu đề README này. Sử dụng WordToMD để chuyển đổi nội dung thô, sau đó sắp xếp lại và thêm GitHub các yếu tố cụ thể.

Bảng trong GitHub Markdown

Word bảng chuyển đổi trực tiếp thành GFM bảng ống. Đây là cách một bảng được chuyển đổi trông như thế nào:

| Feature | Status | Notes |
|---|---|---|
| Authentication | ✅ Done | JWT-based |
| File upload | 🚧 In progress | S3 target |
| API docs | ❌ Pending | — |

GitHub cũng hỗ trợ sắp xếp cột:

| Left | Center | Right |
|:---|:---:|---:|
| text | text | text |

Đối với tất cả mọi thứ về Markdown bảng, xem Markdown Bảng: Hướng dẫn đầy đủ.

Hình ảnh trong GitHub Repository

GitHub hiển thị hình ảnh từ các đường dẫn tương đối trong repo:

![Architecture diagram](docs/images/architecture.png)

Nếu tài liệu Word chứa hình ảnh được hỗ trợ, tải xuống Markdown + hình ảnh ZIP, di chuyển các tập tin hình ảnh đóng gói vào docs/images/, và cập nhật các đường dẫn tương đối nếu kho lưu trữ của bạn sử dụng cấu trúc thư mục khác.

Đối với hình ảnh được lưu trữ bởi GitHub.com, bạn cũng có thể sử dụng URL tuyệt đối:

![Screenshot](https://github.com/user/repo/raw/main/screenshot.png)

GitHub Trang Wiki

GitHub wiki hỗ trợ toàn bộ GFM spec. Phương trình chuyển đổi tương tự như cho README:

Chuyển đổi tài liệu Word của bạn bằng WordToMD
Thêm định dạng cụ thể GFM (danh sách tác vụ, hàng rào mã, cảnh báo)
Tạo một trang wiki mới và dán Markdown

ID tiêu đề và liên kết neo

GitHub tự động tạo ID neo từ văn bản tiêu đề. Tiêu đề ## Installation nhận được ID #installation. You can link to it from elsewhere in the same document:

See the [Installation section](#installation) below.

Điều này rất hữu ích cho các README dài với bảng nội dung. Sau khi chuyển đổi, thêm TOC ở đầu:

## Table of Contents
- [Installation](#installation)
- [Usage](#usage)
- [Contributing](#contributing)

FAQ

GitHub có thể hiển thị HTML trong Markdown không? GitHub cho phép một số thẻ HTML trong Markdown nhưng loại bỏ hầu hết các thuộc tính tạo kiểu. Dựa vào Markdown tổng hợp cho kết quả tốt nhất.

Bàn của tôi có quá nhiều cột và trông chật hẹp trên điện thoại di động. Tôi phải làm gì? Xem xét việc chia các bảng lớn thành các bảng tập trung nhỏ hơn, hoặc sử dụng HTML <details> thẻ cho các phần gập.

Tôi có thể sử dụng Word để viết GitHub vấn đề? Đúng rồi! Chuyển đổi Word doc thành Markdown với WordToMD và dán đầu ra trực tiếp vào mô tả GitHub Issue hoặc Pull Request.

Làm thế nào để tôi chuyển đổi toàn bộ tập hợp tài liệu Word thành wiki GitHub? Chuyển đổi mỗi tệp Word một cách riêng biệt và tạo một trang wiki cho mỗi tài liệu. Xem thêm Batch Convert Word to Markdown vì đã viết kịch bản này với Pandoc.

Kết luận

Chuyển đổi Word thành GitHub Markdown là đơn giản sử dụng WordToMD để có được cơ sở Markdown, sau đó lớp trên GFM đặc tính như danh sách nhiệm vụ, code hàng rào, và cảnh báo gọi. Với một cấu trúc sạch trong tài liệu Word của bạn (các kiểu tiêu đề tích hợp, bảng thích hợp), đầu ra chuyển đổi sẽ gần như sẵn sàng để đẩy đến GitHub.