Word ถึง GitHub Markdown: การจัดรูปเอกสารสําหรับ GitHub READMEs และปัญหา

GitHub ใช้ภาษา Markdown เรียกว่า GitHub รสชาติ 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 รสชาติ Markdown?

GFM คือ GitHubs ขยายของ CommonMark. การเพิ่มที่สําคัญที่สุดเมื่อแปลงจาก Word คือ:

โบล็อกโค้ดที่ติดรั้ว พร้อมกับตัวจําแนกภาษา (```python)
ตาราง การใช้คําประโยคท่อ
รายการการทํางาน using - [ ] and - [x]
สตรีคทรู using ~~text~~
การเชื่อมต่ออัตโนมัติ URL เปลือย จะสามารถคลิกได้

แปลงเอกสาร Word ของคุณที่ WordToMD และคุณจะได้รับการออกแบบที่สอดคล้องกับ GFM โดย default.

Word สไตล์ → GFM องค์ประกอบ

Word องค์ประกอบ	GFM ผลิต
หมวด 1	`# H1`
หมวด 2	`## H2`
กล้าหาญ	`bold`
อักษรอักษร	`italic`
ตาราง	โต๊ะท่อ
รายการที่มีลูกบอก	`- item`
รายการที่มีเลข	`1. item`
ไฮเปอร์ลิงค์	`[text](url)`
แฟนทับเดียว	`code`
สตรีคทรู	`~~text~~`

GitHub-คุณสมบัติเฉพาะที่จะเพิ่มหลังจากการแปลง

รายการการทํางาน

Word ไม่มีองค์ประกอบรายการงานพื้นบ้าน. ถ้าคุณมีช่องเช็คใน Word doc ของคุณ พวกเขาจะแปลงเป็นข้อความเรียบ หลังจากการแปลง, แฟอร์เมทมันเป็นรายการการทํางาน GFM:

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

เหล่านี้ทําเป็นช่องเช็คที่ปฏิสัมพันธ์ในไฟล์ GitHub Issues, Pull Requests, และโครงการ README

โบล็อกโค้ดที่ขั้วด้วยการเร่งสัญญากลาง

ข้อความในระยะเดียวจาก Word เปลี่ยนเป็นโค้ดในเส้น สําหรับบล็อคโค้ดหลายแถวบน GitHub ใช้คําบรรยายที่ติดขอบด้วยตัวจําแนกภาษา:

```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.

หากเอกสาร Word ของคุณมีกล่องการเรียกหรือข้อความที่เร่งเรือง, เปลี่ยนแปลงมันไปยังการตักเตือน GFM สารานุกรมนี้หลังจากการแปลงครั้งแรก.

การจัดโครงสร้าง README จากเอกสาร Word

โปรแกรมเฉพาะ README ตามโครงสร้างนี้:

# Project Name

Short description.

## Installation

## Usage

## Configuration

## Contributing

## License

หากเอกสาร Word ของคุณเป็นรายละเอียดโครงการหรือร่างเอกสาร, แผนผังส่วนของมันกับหัวข้อ README เหล่านี้. การใช้ WordToMD เพื่อแปลงเนื้อหาแหลม แล้วจัดใหม่และเพิ่มองค์ประกอบเฉพาะ GitHub

ตารางใน GitHub Markdown

ตาราง Word เปลี่ยนเป็น ตารางท่อ GFM โดยตรง นี่คือว่าตารางที่แปลงออกมาเป็นอย่างไร:

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

GitHub ยังสนับสนุนการปรับคอลัมน์:

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

สําหรับทุกอย่างเกี่ยวกับตาราง Markdown ดู Markdown ตาราง: คู่มือที่ครบวงจร.

รูปภาพใน GitHub Repositories

GitHub ทําการแสดงภาพจากเส้นทางสัมพันธ์ใน repo:

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

หากเอกสาร Word มีภาพที่รองรับ, ดาวน์โหลด Markdown + รูปภาพ ZIP, ย้ายไฟล์ภาพที่บรรจุเข้า docs/images/, และปรับปรุงเส้นทางที่เกี่ยวข้องหากคลังของคุณใช้โครงสร้างโฟลเดอร์ที่แตกต่าง

สําหรับภาพที่โฮสต์โดย GitHub.com คุณยังสามารถใช้ URL ที่สมบูรณ์ได้:

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

GitHub หน้าวิกิ

GitHub วีกิสนับสนุนสเปคเต็ม GFM กระบวนการทํางานของการแปลงเป็นเช่นเดียวกับสําหรับ README:

แปลงเอกสาร Word ของคุณด้วย WordToMD
เพิ่มการจัดรูปแบบเฉพาะ GFM (รายการงานงาน, เงื่อนไขรหัส, การแจ้งเตือน)
สร้างหน้าวิกิใหม่และติด Markdown

ID หัวข้อและลิงค์แก่น

GitHub สร้างตัวเลข anchor จากบทความหัวข้อโดยอัตโนมัติ หัวข้อ ## Installation ได้รับบัตรประจําตัว #installation. You can link to it from elsewhere in the same document:

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

นี้เป็นประโยชน์สําหรับ README ยาว ๆ ที่มีตารางเนื้อหา หลังจากการแปลง, เพิ่ม TOC บนด้านบน:

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

FAQ

GitHub ทําให้ HTML ใน Markdown ได้หรือไม่? GitHub ยอมให้มีแท็ก HTML ใน Markdown แต่จะถอนคุณสมบัติการออกแบบส่วนใหญ่ ติดต่อกับการออกคํานวณ Markdown เพื่อผลดีที่สุด

โต๊ะผมมีคอลัมน์มากเกินไป และดูแคบมากในมือถือ ฉันควรจะทํายังไง? พิจารณาการแบ่งตารางขนาดใหญ่ออกเป็นตารางขนาดเล็กๆ หรือใช้ HTML <details> แท็กสําหรับส่วนที่พับได้

ผมสามารถใช้ Word เพื่อเขียน GitHub Issues ได้หรือไม่? ใช่แล้ว เปลี่ยน Word doc เป็น Markdown ด้วย WordToMD และติดผลิตตรงเข้าในคําอธิบาย GitHub Issue หรือ Pull Request

วิธีการแปลง whole Word เซ็ตเอกสารเป็น wiki GitHub ได้อย่างไร? แปลงไฟล์ Word แต่ละครั้ง และสร้างหน้าวิกิหนึ่งต่อเอกสาร ดู Batch Convert Word เป็น Markdown สําหรับการเขียนนี้ด้วย Pandoc

การสรุป

การแปลง Word เป็น GitHub Markdown ใช้ง่าย WordToMD เพื่อได้รับฐาน Markdown, จากนั้นผิวบน GFM-คุณสมบัติเฉพาะ เช่น รายการงานงาน, แผงรั้วรหัส, และการเตือนการเรียก. ด้วยโครงสร้างที่สะอาดในเอกสาร Word ของคุณ (สไตล์หัวข้อใน, ตารางที่เหมาะสม) การแปลงผลิตจะเกือบพร้อมที่จะผลักดันไป GitHub.