كيفية إنشاء ملف Markdown GitHub من Microsoft Word باستخدام TypeScript

ماذا؟ لماذا قد يرغب المرء في إنشاء ملف MD من مستند Microsoft Word؟ إذا كان هذا هو أول ما فكرت به بعد قراءة هذا العنوان ، دعني أقدم لك حالة استخدام قوية.

ضع في اعتبارك موقفًا تستخدم فيه Git أو أي نظام تحكم في الإصدار (VCS) لمصادر مشروعك بالإضافة إلى عناصره الفنية. الآن ، مثل معظم المشاريع ، قررت استخدام Microsoft word للتوثيق والتحقق من ذلك في Git. مرة أخرى ، يقوم العديد من أعضاء الفريق بتحرير نفس المستند. بعد التحرير ، يقومون بإيداع المستند في المستودع.

الآن ، سيكون Git قادرًا على الاحتفاظ بمحفوظات المستند. كيف ستتمكن من إلقاء نظرة على التغييرات التي تم إجراؤها على المستند منذ آخر مرة قمت فيها بإيداعه؟ نعم ، يمكنك استخدام وضع تغيير المسار في Microsoft Word ، لكن أليس هذا فوضويًا؟ أو من أجل الجنة ، هل ستتمكن من استخدام أداة Git diff للتحقق من الاختلافات بسرعة؟ أود أن أقول ، لا.

ثم ما هو الحل؟ هل يجب عليك التوقف عن استخدام Microsoft Word للتوثيق؟ أم يجب عليك التبديل إلى بعض VCS الأخرى؟

لن أقول أيا منهما. ماذا عن الاحتفاظ بوثائقك في Microsoft Word؟ ثم قم بتغييره إلى ملف markdown (MD) (من الناحية العادية ، ملف نصي) أثناء مرحلة البناء وتحقق في؟ إذا كان هذا الحل يثيرك ، فاستمر في القراءة.

ولكن قبل الانتقال مباشرة إلى التحويل ، دعني أخبرك أولاً ما هو بالضبط ملف تخفيض السعر.

ما هو تخفيض السعر أو ملف MD؟

Markdown هي لغة نحوية تهدف إلى سهولة قراءة وكتابة نص منظم. علاوة على ذلك ، من السهل التعلم ، ولا يتطلب الأمر سوى محرر نصوص لإنشاء مستند.

الآن ، هناك تطبيقات متعددة للغة (مثل GFM ويعرف أيضًا باسم Markdown بنكهة Github). كل من هذه التطبيقات لها تحسينات وميزات خاصة بها والتي لا تتوافق بالضرورة مع بعضها البعض.

يدعم كل تطبيق العديد من الميزات المشتركة مثل الفقرات والاقتباسات والعناوين والقوائم. يساعد ذلك في الحفاظ على النص بطريقة منظمة مثل Microsoft Word. ولكن بدلاً من استخدام الرموز الثنائية الداخلية ، تستخدم ملفات MD أحرفًا ذات نص عادي لهذه الميزات. هذا يجعل ملف MD ملفًا نصيًا وليس ملفًا ثنائيًا مثل ملف docx.

على سبيل المثال ، في نكهة Markdown الخاصة بـ GitHub ، إليك الميزات المختلفة وطرق تمثيلها في شكل نص مقارنة بمستند Word.

للحصول على المزايا التفصيلية لملفات MD على مستندات Word ، يمكنك أيضًا الرجوع إلى هذه المقالة.

حسنا! أنا مقتنع. أرني الرمز.

إخلاء المسؤولية: هذا المشروع مستوحى من شفرة مصدر TypeScript. أثناء التصفح ، وجدت فكرة تحويل مستند Word إلى ملف MD. يمكنك رؤية كود المصدر الخاص به هنا.

للتبسيط ، قمت بإزالة بضعة أقسام من التعليمات البرمجية في مستودعي. كان الهدف من الكود الأصلي هو تحويل وثائق مواصفات TypeScript إلى ملف MD. يحتوي هذا الملف على الكثير من الأنماط المخصصة. لذلك ، بمجرد الانتهاء من هذه المقالة ، يمكنك الانتقال إلى رمز محول TypeScript وتقدير قدرته على إجراء تحويلات أكثر تعقيدًا.

يمكن الرجوع إلى الكود الكامل المذكور في هذه المقالة هنا. يمكن تقسيم الكود بأكمله إلى 3 أقسام:

  1. تكوينات الجلبة.
  2. تنفيذ CScript.
  3. وظيفة TypeScript الرئيسية

كما ذكرنا سابقًا ، يمكنك تحويل مستند Word إلى ملف MD أثناء مرحلة الإنشاء. يمكن القيام بذلك عن طريق أي عداء مهمة. هنا ، لقد اخترت البلع.

في تكوينات Gulp ، قمت بتحديد 3 مهام. الأول هو تنظيف دليل البناء الذي يعتبر قياسيًا جدًا. الثاني هو تجميع كود TypeScript. وآخرها هو استدعاء CScript لتنفيذ JavaScript.

ما هو CScript؟

CScript.exe (موجود في C: \ Windows \ System32) هو ملف تنفيذي قائم على وحدة التحكم لمضيف البرمجة النصية المستخدمة لتشغيل البرامج النصية. يمكنه تفسير لغات البرمجة النصية مثل VB Script أو JavaScript. وبالمثل ، لدينا WScript ولكنه يُستخدم لتطبيقات Windows. في هذا ، لا يتم توصيل وحدة التحكم. لذلك إذا كان لديك متطلبات لإنشاء تطبيق قائم على وحدة التحكم ، فيمكننا استخدام CScript.

الآن ، في مشروعنا ، تتمثل المهمة الرئيسية لـ CScript في توفير بيئة وقت تشغيل للبرنامج النصي الخاص بنا ، مثل JavaScript. الآن ، يجب أن تفكر ، لماذا لم أستخدم العقدة بدلاً من CScript لتشغيل JavaScript الخاص بي.

كلاهما يوفر بيئة وقت تشغيل لجافا سكريبت. يوفر CScript دعمًا متأصلًا لتقنية نموذج كائن مكون Windows. لذلك إذا حاولت تشغيل هذا البرنامج النصي عبر Node ، فستتلقى خطأ مثل هذا.

var fileStream = ActiveXObject جديد (“ADODB.Stream”) ؛ الخطأ المرجعي: لم يتم تعريف ActiveXObject

الآن ، ما هي تقنية نموذج الكائن المكون؟

نموذج كائن المكون هو تقنية تم تطويرها بواسطة Microsoft. إنها ليست لغة بل معيار ثنائي. حسب التعريف ،

Microsoft Component Object Model (COM) هو نظام مستقل وموزع وموجه نحو الكائن لإنشاء مكونات برامج ثنائية يمكنها التفاعل. COM هي التقنية الأساسية لـ Microsoft OLE (المستندات المركبة) و ActiveX (المكونات التي تدعم الإنترنت) ، بالإضافة إلى آخرين.

بعبارات عامة ، كائنات COM هي واجهات للعديد من كائنات وقت التشغيل. (هذا هو السبب في أن التعريف له مصطلح يسمى "مكونات البرامج الثنائية"). إنها ليست لغة ، لكنها تقنية لغة برمجة حيادية.

متطلب اللغة الوحيد لـ COM هو أن يتم إنشاء التعليمات البرمجية بلغة يمكنها إنشاء هياكل من المؤشرات. بشكل صريح أو ضمني ، استدعاء الوظائف من خلال المؤشرات. توفر اللغات الموجهة للكائنات مثل C ++ و Smalltalk آليات البرمجة التي تبسط تنفيذ كائنات COM

بعد ذلك ، يمكننا استخدام أي لغة أخرى مثل Java أو VB أو JavaScript للتفاعل مع كائنات COM تلك. سيتيح لنا هذا الوصول إلى تطبيقات وقت التشغيل. في حالتنا ، لتطبيقات Microsoft Word.

إذن ، هل تقول أنه لا يمكننا استخدام Node على الإطلاق هنا؟

لا، هذا ليس صحيحا. يمكننا استخدام Node أيضًا بدلاً من CScript. ولكن لدعم COM ، سنحتاج إلى تثبيت حزمة أخرى تسمى win32com لدعم COM. يمكن العثور على التفاصيل هنا.

الكود النهائي

الآن ، من أجل التفاعل مع تطبيق الكلمات ، تم استخدام العديد من واجهات برمجة التطبيقات. وبما أننا نستخدم نموذج كائن COM ، فقد أشرت إلى نموذج كائن الكلمة.

يوفر Word مئات الكائنات التي يمكنك التفاعل معها. يتم تنظيم هذه الكائنات في تسلسل هرمي يتبع عن كثب واجهة المستخدم. في الجزء العلوي من التسلسل الهرمي يوجد كائن التطبيق. يمثل هذا الكائن المثيل الحالي لـ Word. يحتوي كائن التطبيق على كائنات المستند والتحديد والإشارة المرجعية والنطاق. لكل من هذه الكائنات العديد من الأساليب والخصائص التي يمكنك الوصول إليها للتعامل مع الكائن والتفاعل معه.

الآن ، في البرنامج النصي الخاص بنا ، أنشأنا أولاً كائن تطبيق Word باستخدام ActiveXObject. بمجرد الحصول على كائن التطبيق ، يتم إنشاء كائن المستند بتمرير اسم المستند (تم الحصول عليه من وسيطات سطر الأوامر لاستدعاء cscript).

الآن ، هذا يمثل الكائن النشط للمستند الفعلي. هذا الكائن قادر على الاعراب وكذلك التلاعب في كلمة وثيقة. ومع ذلك ، في حالة الاستخدام الخاصة بنا ، نحتاج فقط إلى تحليل المستند وكتابة ملف نصي.

هذا الرمز عام للغاية ، ويستخدم لتحويل الميزات الأساسية جدًا لمستند Word مثل المراجع التبادلية والقوائم والنصوص المنخفضة والأحرف الغامقة والمائلة وما إلى ذلك إلى تنسيق GFM. ومع ذلك ، يمكنك كتابة التعليمات البرمجية الخاصة بك لتحويل الأنماط المخصصة الخاصة بك من مستند Word إلى التنسيق المطلوب.

يمكنك العثور على رمز الكتابة الفعلي هنا. الشفرة سهلة القراءة. فيما يلي بعض النقاط البارزة الرئيسية:

  1. أولاً ، يتم تمرير كائن مستند إلى دالة convertDocumentToMarkdown التي تُرجع النص المراد كتابته في ملف MD.
  2. علاوة على ذلك ، في convertDocumentToMarkdown ، يتم استدعاء أساليب وخصائص كائن المستند للعثور على ميزات الكلمات ذات الصلة واستبدالها ببنية لغة GFM المقابلة. على سبيل المثال ، يتم البحث أولاً عن النصوص المكتوبة بخط غامق ومائل. بعد ذلك ، يتم استبدال النص برمز خاص بـ GFM. وأخيرًا ، تمت إزالة أنماط الكلمات. كل هذا يتم هنا.
  3. بعد ذلك ، يتم استبدال المراجع الترافقية. ومع ذلك ، هذا أمر صعب. أولاً ، يتم استدعاء وظيفة toggleShowCodes. هذا له تأثير مماثل مثل alt + F9 في مستند Word. هذا يستبدل جميع المراجع التبادلية في مستند بالرمز. بعد ذلك ، يتم استدعاء طريقة البحث والاستبدال للبحث عن كافة المراجع التبادلية واستبدالها بأسلوب GFM. هنا ، يتم تمرير "19 REF" كوسيطة للدالة. هذا معيار بحث قياسي للعثور على جميع المراجع التبادلية في مستند Word. أخيرًا ، بعد الاستبدال ، يتم استدعاء وظيفة toggleShowCodes لإعادة المستند إلى شكله الأصلي.
  4. أخيرًا ، يتم استدعاء وظيفة writeDocument التي تؤدي المهمة الرئيسية. يقرأ فقرة الوثيقة فقرة ثم ، باستخدام حالة التبديل ، يبحث عن أنماط الفقرات (مثل ما إذا كان عنوانًا أو جدولًا أو فقرة قائمة أو صورة). الآن ، اعتمادًا على النمط الذي تم العثور عليه ، يتم كتابة النص المطلوب في ملف MD.

كلمة أو كلمتين حول تضمين الصور: يعد تضمين الصور في ملف MD أمرًا صعبًا بعض الشيء.

أولاً ، تحتاج إلى تخزين الصور في مستودع git الخاص بك. ثم يجب تقديم الرابط في ملف MD لتضمينه فيه. بناء الجملة هو! [نص بديل] (مسار / في / مستودع / صورة 1.jpg).

الآن ، من أجل إنشاء هذا الرابط تلقائيًا لصورة أثناء تحويل كلمة إلى ملف MD ، يتم إنشاء نص مخفي (بعد الصورة بدون أي مساحة) مع المحتوى باعتباره الرابط نفسه. ثم في الكود ، يتم تجريد هذا النص المخفي وإدراجه في ملف MD.

الآن ، قد تجد الكود الفعلي للقيام بكل هذه الأشياء مملاً للغاية ، ولكن هذا كله وفقًا لواجهة برمجة التطبيقات التي يعرضها تطبيق Word. لذلك لا تقلق بشأن ذلك. يمكنك بالتأكيد إحالة الكود الخاص بي أو رمز TypeScript الأصلي. كلاهما سيكون بداية جيدة لمشروعك القادم.

اه انتظر!! هذا هو. هل فعلت ذلك حتى النهاية؟ حسنا اذن ؟ تهانينا! ؟ وإذا أعجبك هذا المقال ، يرجى أن تصفق؟ الزر أدناه. سيعني ذلك الكثير بالنسبة لي وسيساعد الآخرين على رؤية القصة. في صحتك! ؟