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 متوافق الخروج الافتراضي.

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 مستودعات

GitHub يعرض الصور من المسارات النسبية في النسخة:

![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

هويات العناوين والروابط المربكة

GitHub ينشئ تلقائيًا هويات المرساة من نص العنوان. العنوان ## Installation يحصل على الهوية #installation. You can link to it from elsewhere in the same document:

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

هذا مفيد لـ READMEs الطويلة مع جدول المحتوى. بعد التحويل، إضافة 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 مسألة أو وصف طلب سحب.

كيف يمكنني تحويل مجموعة وثائق Word بأكملها إلى ويكي GitHub؟ تحويل كل ملف Word بشكل فردي وخلق صفحة ويكي واحدة لكل وثيقة. انظر تحويل الدفعة Word إلى Markdown لكتابة هذا مع Pandoc.

النتيجة

تحويل Word إلى (بـ (بـ (بـ (بـ (بـ استخدام بسيط WordToMD للحصول على قاعدة Markdown، ثم طبقة على GFM-ميزات محددة مثل قوائم المهام، والأسوار الرمز، وتنبيهات الاستدعاء. مع هيكل نظيف في مستندك Word (أساليب العناوين المدمجة ، الجداول المناسبة) ، إنتاج التحويل سيكون جاهز تقريباً للدفع إلى GitHub.