أنشئ سلسلة منشورات باستخدام Pandoc و Docker

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

يمكنه تبسيط التوثيق والنشر بشكل كبير ، أو حتى فتح بعض إمكانيات الأتمتة الجديدة. أفضل ما في الأمر هو أن Pandoc يعتمد على Git-friendly Markdown ، مما يعني أنه يمكنك أيضًا تنفيذ نظام التحكم في الإصدار لوثائقك دون أي متاعب إضافية.

عند الحديث عن المتاعب ، سوف نعتمد على صورة Docker لتثبيت Pandoc و LaTeX بسحب بسيط. يمكن أن يستغرق تثبيت البرنامج وقتًا طويلاً ، كما أن إعداد بيئة برامج العمل من البداية عند بدء مشروع جديد أمر بالكاد يكون مثمراً. يساعد Docker في التخفيف من هذه المشكلات من خلال السماح للمستخدمين بإعداد كل شيء في دقائق ، بغض النظر عن النظام الأساسي.

بالإضافة إلى ذلك ، ليس من غير المألوف أن يطلب منك أصحاب العمل توفير أجهزة الكمبيوتر الخاصة بك. يُشار إلى هذا غالبًا باسم إحضار جهازك الخاص (BYOD) ، ولا ننسى أن جائحة COVID-19 جعل العمل من المنزل أكثر انتشارًا. بدون حلول مثل Docker ، سيكون من الصعب دعم التطبيقات التي تعمل على أجهزة وأنظمة تشغيل متنوعة مثل Windows و macOS و Linux.

لنبدأ بإلقاء نظرة فاحصة على حاويات Docker والصور قبل الانتقال إلى Pandoc.

عامل ميناء في الإنقاذ

يمكن أن يؤدي استخدام حاويات Docker إلى التخلص من الحاجة إلى تثبيت تطبيقات برمجية متعددة على جهاز جديد. تتوفر صور Docker سابقة البناء على Docker Hub لعدد كبير من التطبيقات. يوفر كل من مقدمي الخدمات السحابية الرائدين مثل AWS و Azure و Google سجلات حاويات. هناك العديد من سجلات الجهات الخارجية الأخرى بما في ذلك GitLab و Red Hat OpenShift.

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

حالة استخدام Pandoc: التوثيق

قد تكون الوثائق مطلوبة في عدة صيغ مختلفة. قد يلزم توفر نفس المستند بتنسيقات مختلفة مثل HTML للعروض التقديمية و PDF للنشرات. يمكن أن يكون التحويل بين تنسيقات الملفات مملاً ويتطلب الكثير من الوقت. الحل الجيد هو أن يكون لديك سلسلة نشر بمصدر واحد للحقيقة. يجب أن تكون جميع الوثائق مكتوبة بنفس اللغة. يجب أن تكون لغة نصية حيث يسهل إصدارها وتخزينها في مستودعات Git.

Markdown هو خيار جيد لخلق مصدر واحد للحقيقة. البرامج التي يمكنها تحويل مستندات Markdown إلى مجموعة متنوعة من التنسيقات الأخرى متاحة بسهولة وتميل إلى أن تكون موثوقة.

باندوك

Pandoc عبارة عن حزمة برامج يمكنها تحويل المستندات إلى تنسيقات مختلفة. على وجه الخصوص ، يمكنه تحويل Markdown إلى HTML و PDF وتنسيقات أخرى مستخدمة على نطاق واسع. يمكن تخصيص عملية التحويل باستخدام القوالب والبيانات الوصفية في مصدر Markdown.

يتطلب Pandoc تثبيت LaTeX لإنشاء ملفات PDF. يستغرق تثبيت Pandoc و LaTeX وقتًا طويلاً. لحسن الحظ ، هناك صورة Docker تسمى pandoc / latex ، والتي تلغي الحاجة إلى تثبيت أي شيء آخر غير Docker.

أوامر عامل ميناء

يجب إيجاد أو إنشاء صورة Docker مناسبة تحتوي على البرامج الضرورية. يُنصح بسحب الصورة إلى السجل المحلي حيث قد يستغرق التنزيل بعض الوقت.

 docker pull pandoc/latex

لتشغيل أمر في حاوية Docker يتطلب غلافًا لتشغيل حاوية Docker وتنفيذ أمر في الحاوية. الحل الجيد لذلك هو كتابة دالة shell على نظام macOS أو UNIX / Linux. يمكن وضع الوظيفة في أي برامج نصية لتسجيل الدخول أو في ملف منفصل مثل $HOME/.functions . من الممكن أيضًا كتابة نص أو اسم مستعار بنفس الوظيفة.

 function pandoc { echo pandoc $@ docker run -it --rm -v $PWD:/work -w /work pandoc/latex pandoc "$@" }

تقوم هذه الوظيفة بما يلي:

• يقوم بطباعة الأمر على الشاشة.
• يدير حاوية Docker من صورة pandoc/latex .
• يُنشئ الخيار -it جلسة طرفية تفاعلية ويجعل إخراج الأمر مرئيًا.
• يحذف الخيار --rm الحاوية بمجرد إنهاء الأمر.
• يعمل الخيار -v $PWD:/work على تحميل الدليل الحالي على المضيف إلى الدليل /work في الحاوية.
• -w /work يجعل دليل /work في الحاوية دليل العمل.
• يقوم pandoc "$@" بتشغيل أمر pandoc في الحاوية ويمرر جميع خيارات سطر الأوامر التي تم تمريرها إلى الوظيفة.

يحتاج الغلاف أو البرنامج النصي إلى تحميل الوظيفة في الذاكرة.

 . $HOME/.functions

أصبحت الوظيفة الآن أمرًا في حد ذاتها وتتصرف بنفس الطريقة كما لو تم تثبيت ثنائي pandoc محليًا. يمكن استخدام هذا الأسلوب لأي أمر متوفر في صورة Docker.

تخفيض السعر إلى HTML

لتحويل Markdown إلى HTML ، من الأفضل استخدام قالب وبيانات وصفية في Markdown.

بيانات وصفية Markdown

يمكن أن يحتوي مصدر Markdown على قسم رأس يمكن أن يحتوي على بيانات وصفية عشوائية. تأخذ البيانات الوصفية شكل أزواج مفتاح - قيمة. يمكن استبدال القيم في قالب HTML.

 --- title: Document title links: prev: index next: page002 ...

يبدأ العنوان بسطر يحتوي على ثلاث شرطات فقط --- . يتم إنهاؤها بخط يحتوي على ثلاث نقاط فقط ... المفاتيح هي كلمات مفردة متبوعة بنقطتين وقيمته. يمكن أن تتداخل المفاتيح. يوضح المثال تعريف المفاتيح التي تسمى title, links.prev و links.next .

يستخدم هذا الأسلوب ملفًا منفصلاً لكل صفحة. في المثال ، الصفحة السابقة هي index.md ، والصفحة الحالية هي page001.md ، والصفحة التالية هي page002.md . في الممارسة العملية ، سيتم استخدام أسماء ملفات أكثر وضوحًا بحيث يكون من السهل إعادة ترتيب الصفحات وإدراجها.

قالب HTML

قالب HTML هو ببساطة ملف HTML. يمكن إضافة استبدال البيانات الوصفية وهياكل التحكم البسيطة بين رموز الدولار. فيما يلي مثال بسيط على نموذج HTML لـ Pandoc:

 <html> <head> <meta charset="utf-8" /> <meta name="viewport" content="width=device-width, initial-scale=1.0"> <title>$title$</title> <link href="../css/style.css" type="text/css" rel="stylesheet" /> </head> <header> <h1>$title$</h1> </header> <body> $body$ </body> <footer> $if(links.prev)$ <a href="$links.prev$.html" class="previous">&laquo; Previous</a> $endif$ $if(links.next)$ <a href="$links.next$.html" class="next">Next &raquo;</a> $endif$ </footer> </html>

يوضح المثال نموذجًا. يتم استبدال $body$ بنص Markdown الذي تم تحويله إلى HTML. تقوم العبارات الشرطية بإنشاء ارتباط HTML فقط إذا تم تحديد البيانات الأولية في رأس Markdown.

إنشاء HTML من Markdown

يحتاج Pandoc فقط إلى إخباره باسم ملفات الإدخال والإخراج بالإضافة إلى أي ملفات قالب. تنسيق ملف الإدخال الافتراضي هو Markdown . يمكنه استنتاج تنسيق ملف الإخراج من امتداد ملف الإخراج المحدد.

يمكن أن تكون أوامر إنشاء المخرجات نصًا أو ملفًا makefile.

 dir=Project for input_file in ${dir}/*.md do output_file=HTML/${input_file%.md}.html if [[ ${input_file} -nt ${output_file} ]] then pandoc --data-dir . --template presentations.html -t html \ -o ${output_file} ${input_file} fi done

لكل ملف .md في دليل Project ، يقوم بإنشاء ملف .html مطابق في دليل HTML/Project إذا كان ملف الإخراج أقدم من ملف الإدخال أو غير موجود.

إنشاء Beamer PDF من Markdown

Beamer عبارة عن حزمة LaTeX لإنتاج العروض التقديمية. الإخراج هو عرض شرائح PDF.

يمكن استخدام نفس ملفات مصدر Markdown لإنشاء ملف PDF الخاص بجهاز تجميع الملفات.

 pandoc -t beamer -o PDF/Project.pdf -V theme:Boadilla -V colortheme:whale Project/index.md Project/page000.md

تفاصيل الأمر هي:

• يشير خيار -t beamer إلى استخدام LaTeX و beamer لإنشاء ملف PDF.
• يحدد الخيار -o ملف الإخراج.
• تحدد خيارات -V المشعاع وموضوع اللون.
• ينتهي الأمر بقائمة من ملفات Markdown التي سيتم تجميعها بالترتيب المحدد.

يتم تنفيذ جميع عمليات المعالجة داخل حاوية Docker.

تخفيض السعر إلى PDF

يعد تحويل مستند Markdown إلى مستند PDF أمرًا بسيطًا أيضًا. يتم إنشاء PDF دائمًا عن طريق تحويل Markdown إلى LaTeX أولاً. يمكن إضافة البيانات الأولية إلى رأس Markdown لتخصيص الإخراج مثل ضبط حجم الورق وحجم الهامش.

 --- title: Title of document papersize: a4 geometry: - margin=20mm ...

إنشاء ملف PDF من Markdown

أمر تحويل Markdown إلى PDF بسيط:

 pandoc -s Project/outline.md -o PDF/ProjectOutline.pdf

يقوم الخيار -s بإنشاء مستند مستقل.

خاتمة

لم يعد من الضروري قضاء عدة أيام في تثبيت البرنامج. يؤدي تشغيل أمر ما في حاوية Docker إلى التخلص من الحاجة إلى التثبيت. تحتوي العديد من التطبيقات على صور Docker مناسبة على Docker Hub. إذا احتاج البرنامج إلى التحديث ، فما عليك سوى سحب أحدث صورة لـ Docker.

إن إعداد جهاز كمبيوتر جديد هو مجرد مسألة تثبيت Docker ، وسحب الصور الضرورية ، وإنشاء بعض البرامج النصية.

لم يعد من الضروري إنشاء مستندات بتنسيقات مختلفة. يمكن استخدام تنسيق واحد مثل Markdown لجميع المستندات. يمكن لأدوات مثل Pandoc بعد ذلك إنشاء مستندات من Markdown إلى عدد كبير من التنسيقات المختلفة.

نظرًا لأن Markdown هو ملف نصي ، عند تسجيله في مستودع Git ، يتوفر سجل إصدار كامل. تعرض مستودعات Git أيضًا Markdown تلقائيًا وتسمح للأشخاص بالتعليق على التغييرات دون الحاجة إلى استخدام سجلات التغيير الفوضوي في ملف المستند نفسه.