CommonMark: مواصفات رسمية لعملية Markdown

CommonMark هو نسخة منطقية من بناء جملة Markdown مع محدد هدفه إزالة الغموض وعدم الاتساق المحيط بمواصفات Markdown الأصلية. يقدم مواصفات قياسية تحدد البنية العامة للغة جنبًا إلى جنب مع مجموعة من الاختبارات الشاملة للتحقق من صحة تطبيقات Markdown مقابل هذه المواصفات.

يستخدم GitHub Markdown كلغة ترميز لمحتوى المستخدم الخاص به.

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

- "مواصفات رسمية لـ GitHub Flavored Markdown ،" مدونة GitHub

في عام 2012 ، شرعت GitHub في إنشاء نكهة خاصة بها لـ Markdown - GitHub Flavored Markdown (GFM) - لمكافحة الافتقار إلى معايير Markdown ، وتوسيع بناء الجملة لاحتياجاتها. تم إنشاء GFM فوق Sundown ، وهو محلل تم إنشاؤه خصيصًا بواسطة GitHub لحل بعض أوجه القصور في موزعي Markdown الحاليين في ذلك الوقت. بعد خمس سنوات ، في عام 2017 ، أعلنت عن إهمال Sundown لصالح مكتبة تحليل وعرض CommonMark ، cmark في مواصفات رسمية لـ GitHub Flavored Markdown.

في قسم الأسئلة الشائعة في Markdown و Visual Studio Code ، تم توثيق أن Markdown في VSCode يستهدف مواصفات CommonMark Markdown باستخدام مكتبة markdown ، والتي تتبع في حد ذاتها مواصفات CommonMark.

تم اعتماد وتنفيذ CommonMark على نطاق واسع (انظر قائمة تطبيقات CommonMark) للاستخدام في لغات مختلفة مثل C (مثل cmark) و C # (مثل CommonMark.NET) و JavaScript (مثل markdown-it) وما إلى ذلك. هذه أخبار جيدة كمطورين وينتقل المؤلفون تدريجيًا إلى حدود جديدة تتمثل في قدرتهم على استخدام Markdown ببنية متسقة ومواصفات موحدة.

ملاحظة قصيرة على موزعي Markdown

تقع موزعي Markdown في قلب عملية تحويل نص Markdown إلى HTML ، بشكل مباشر أو غير مباشر.

لا يقوم المحللون مثل cmark و commonmark.js بتحويل Markdown إلى HTML مباشرة ، وبدلاً من ذلك ، يقومون بتحويله إلى شجرة بناء مجردة (AST) ، ثم يعرضون AST على هيئة HTML ، مما يجعل العملية أكثر دقة وعرضة للتلاعب. بين التحليل - إلى AST - والعرض - إلى HTML - على سبيل المثال ، يمكن تمديد نص Markdown.

دعم Markdown الخاص بـ CommonMark

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

يمكن أن يكون دعم بناء جملة CommonMark محدودًا في البداية ، على سبيل المثال ، لا يدعم بناء جملة هذا الجدول ، ولكن من المهم معرفة أن هذا حسب التصميم حيث يوضح هذا التعليق في سلسلة المحادثات هذه: أن البنية المدعومة صارمة وقولها لتكون البنية الأساسية للغة نفسها - كما حددها منشئها ، جون جروبر في Markdown: Syntax.

في وقت كتابة هذا التقرير ، يوجد عدد من الصيغ المدعومة:

1. الفقرات وفواصل الأسطر ،
2. رؤوس ،
3. تأكيد وتأكيد قوي ،
4. القواعد الأفقية
5. القوائم ،
6. الروابط ،
7. الصور
8. كتلة الاقتباس،
9. رمز،
10. كتل التعليمات البرمجية.

لمتابعة الأمثلة ، يُنصح باستخدام محرر Commonmark.js dingus لتجربة بناء الجملة والحصول على المعاينة المعروضة ، و HTML المُنشأ ، و AST.

الفقرات وفواصل الأسطر

في Markdown ، الفقرات عبارة عن أسطر متصلة من النص مفصولة بسطر فارغ على الأقل.

تحدد القواعد التالية فقرة:

1. يتم عرض فقرات Markdown في HTML كعنصر الفقرة ، <p>.
2. يتم فصل الفقرات المختلفة بسطر فارغ واحد أو أكثر بينهما.
3. بالنسبة لفاصل الأسطر ، يجب إصلاح الفقرة لاحقًا بمسافتين فارغتين (أو ما يعادلها من علامة الجدولة) ، أو شرطة مائلة للخلف ( \ ).

• برنامج تعليمي تفاعلي للتعرف على الفقرات.
• Dingus Permalink تحقق من المثال الكامل مع المعاينة و AST.
• تعرف على المزيد حول الفقرات.

العناوين

تمثل العناوين في Markdown أحد عناصر عناوين HTML. هناك طريقتان لتحديد العناوين:

1. عنوان ATX.
2. عنوان Setext.

تحدد القواعد التالية عناوين ATX:

1. يتم دعم مستوى العنوان 1 ( h1 ) ، وصولاً إلى مستوى العنوان 6 ، ( h6 ).
2. تكون عناوين Atx-style مسبوقة برمز التجزئة ( # ).
3. يجب أن تكون هناك مسافة فارغة على الأقل تفصل بين النص ورمز التجزئة ( # ).
4. عدد التجزئات يعادل الرقم الأصلي للعنوان. تجزئة واحدة هي h1 ، تجزئتان ، h2 ، 6 تجزئات ، h6 .
5. من الممكن أيضًا إلحاق عدد عشوائي من رمز (رموز) التجزئة بالعناوين ، على الرغم من أن هذا لا يسبب أي تأثير (على سبيل المثال ، # Heading 1 # )

تحدد القواعد التالية عناوين Setext:

1. يتم دعم مستوى العنوان 1 (h1) ومستوى العنوان 2 (h2) فقط.
2. يتم تعريف Setext-style باستخدام رموز المساواة (=) والشرطة على التوالي.
3. باستخدام Setext ، يلزم وجود رمز يساوي أو رمز شرطة واحد على الأقل.

• برنامج تعليمي تفاعلي للتعرف على العناوين.
• Dingus الرابط الثابت للتحقق من المثال الكامل مع المعاينة و AST.
• تعرف على المزيد حول عناوين ATX.
• تعرف على المزيد حول عناوين Setext.

توكيد وتأكيد قوي

يمكن أن يكون التركيز في Markdown إما مائلًا أو جريئًا (تركيز قوي).

تحدد القواعد التالية التركيز:

1. يتم عرض التركيز العادي والقوي في HTML كعنصر التوكيد ، <em> ، والقوي ، <strong> ، على التوالي.
2. سيكون النص المحدد بعلامة النجمة المفردة ( * ) أو الشرطة السفلية ( _ ) بمثابة تأكيد.
3. سيكون النص المحدد بعلامات نجمية مزدوجة أو شرطة سفلية تركيزًا قويًا.
4. يجب أن تتطابق الرموز المحيطة (العلامات النجمية أو الشرطة السفلية).
5. يجب ألا تكون هناك مسافة بين الرموز والنص المرفق.

• البرنامج التعليمي التفاعلي لمعرفة المزيد عن التركيز.
• Dingus الرابط الثابت للتحقق من المثال الكامل مع المعاينة و AST.
• تعرف على المزيد حول التركيز والتركيز القوي.

قاعدة افقية

يتم إنشاء المسطرة الأفقية ، <hr /> بثلاثة أو أكثر من العلامات النجمية ( * ) ، أو الواصلات ( - ) ، أو الشرطات السفلية ( _ ) ، على سطر جديد. الرموز مفصولة بأي عدد من المسافات ، أو لا يتم فصلها على الإطلاق.

• Dingus الرابط الثابت للتحقق من المثال الكامل مع المعاينة و AST.
• تعرف على المزيد حول الفواصل المواضيعية.

القوائم

القوائم في Markdown إما قائمة ذات تعداد نقطي (غير مرتبة) أو قائمة مرتبة.

تحدد القواعد التالية قائمة:

1. يتم تقديم قوائم الرموز النقطية بتنسيق HTML كعنصر قائمة غير مرتب ، <ul>.
2. يتم عرض القوائم المرتبة بتنسيق HTML كعنصر قائمة مرتبة ، <ol>.
3. تستخدم قوائم التعداد النقطي العلامات النجمية والإيجابيات والواصلات كعلامات.
4. تستخدم القوائم المرتبة أرقامًا متبوعة بنقاط أو أقواس إغلاق.
5. يجب أن تكون العلامات متسقة (يجب عليك فقط استخدام العلامة التي تبدأ بها لبقية تعريف عناصر القائمة).

• برنامج تعليمي تفاعلي للتعرف على القوائم.
• Dingus الرابط الثابت للتحقق من المثال الكامل مع المعاينة و AST.
• تعرف على المزيد حول قوائم العناصر.

الروابط

يتم دعم الروابط بالتنسيق المضمن والمرجع .

تحدد القواعد التالية ارتباطًا:

1. يتم تقديم الروابط كعنصر ارتساء HTML ، <a>.
2. يحتوي التنسيق المضمن على بناء الجملة: [value](URL "optional-title") بدون مسافة بين القوسين.
3. يحتوي تنسيق المرجع على بناء الجملة: [value][id] للمرجع ، و [id]: href "optional-title" لتسمية الارتباط التشعبي ، مفصولاً بسطر على الأقل.
4. id هو معرف التعريف وقد يتكون من أحرف وأرقام ومسافات وعلامات ترقيم.
5. معرفات التعريف ليست حساسة لحالة الأحرف.
6. يوجد أيضًا دعم للارتباطات التلقائية ، حيث يكون عنوان URL محددًا برمز أقل من (<) وأكبر من (>) ، ويتم عرضه حرفياً.

 <!--Markdown--> [Google](https://google.com “Google”) <!--Rendered HTML--> <a href="https://google.com" title="Google">Google</a> <!--Markdown--> [Google](https://google.com) <!--Rendered HTML--> <a href="https://google.com">Google</a> <!--Markdown--> [Comparing Styling Methods in Next.js](/2020/09/comparing-styling-methods-next-js) <!--Rendered HTML--> <a href="/2020/09/comparing-styling-methods-next-js">Comparing Styling Methods In Next.js</a> <!--Markdown--> [Google][id] <!--At least a line must be in-between--> <!--Rendered HTML--> <a href="https://google.com" title="Google">Google</a> <!--Markdown--> <https://google.com> <!--Rendered HTML--> <a href="https://google.com">google.com</a> <!--Markdown--> <[email protected]> <!--Rendered HTML--> <a href="mailto:[email protected]">[email protected]</a>

• برنامج تعليمي تفاعلي للتعرف على الروابط.
• Dingus الرابط الثابت للتحقق من المثال الكامل مع المعاينة و AST.
• تعرف على المزيد حول الروابط.

الصور

تتبع الصور في Markdown التنسيقات المضمنة والمرجعية للروابط.

تحدد القواعد التالية الصور:

1. يتم تقديم الصور كعنصر صورة HTML ، <img>.
2. يحتوي التنسيق المضمن على بناء الجملة ![alt text](image-url "optional-title") .
3. يحتوي تنسيق المرجع على بناء الجملة ![alt text][id] للمرجع ، و [id]: image-url "optional-title" لتسمية الصورة. يجب فصل كلاهما بسطر فارغ على الأقل.
4. عنوان الصورة اختياري ، ويمكن أن يكون عنوان url للصورة نسبيًا.

 <!--Markdown--> ![alt text](image-url "optional-title") <!--Rendered HTML--> <img src="image-url" alt="alt text" title="optional-title" /> <!--Markdown--> ![alt text][id] <!--At least a line must be in-between--> <!--Markdown--> <!--Rendered HTML--> <img src="image-url" alt="alt text" title="optional-title" />

• برنامج تعليمي تفاعلي للتعرف على الصور.
• Dingus الرابط الثابت للتحقق من المثال الكامل مع المعاينة و AST.
• تعرف على المزيد حول الصور.

كتلة الاقتباس

يمكن إنشاء عنصر اقتباس كتلة HTML ، <blockquote> ، عن طريق إضافة بادئة إلى سطر جديد بالرمز أكبر من ( > ).

 <!--Markdown--> > This is a blockquote element > You can start every new line > with the greater than symbol. > That gives you greater control > over what will be rendered. <!--Rendered HTML--> <blockquote> <p>This is a blockquote element You can start every new line with the greater than symbol. That gives you greater control over what will be rendered.</p> </blockquote>

يمكن أن تتداخل Blockquotes:

 <!--Markdown--> > Blockquote with a paragraph >> And another paragraph >>> And another <!--Rendered HTML--> <blockquote> <p>Blockquote with a paragraph</p> <blockquote> <p>And another paragraph</p> <blockquote> <p>And another</p> </blockquote> </blockquote> </blockquote>

يمكن أن تحتوي أيضًا على عناصر Markdown أخرى ، مثل الرؤوس والتعليمات البرمجية وعناصر القائمة وما إلى ذلك.

 <!--Markdown--> > Blockquote with a paragraph > # Heading 1 > Heading 2 > - > 1. One > 2. Two <!--Rendered HTML--> <blockquote> <p>Blockquote with a paragraph</p> <h1>Heading 1</h1> <h2>Heading 2</h2> <ol> <li>One</li> <li>Two</li> </ol> </blockquote>

• برنامج تعليمي تفاعلي للتعرف على الاقتباسات المحظورة.
• Dingus الرابط الثابت للتحقق من المثال الكامل مع المعاينة و AST.
• تعرف على المزيد حول Blockquotes.

رمز

عنصر HTML Inline Code ، <code> ، مدعوم أيضًا. لإنشاء واحدة ، حدد النص بعلامات التجزئة الخلفية (`) ، أو علامات التجزئة المزدوجة إذا كانت هناك حاجة إلى علامة خلفية حرفية في النص المرفق.

 <!--Markdown--> `inline code snippet` <!--Rendered HTML--> <code>inline code snippet</code> <!--Markdown--> `<button type='button'>Click Me</button>` <!--Rendered HTML--> <code><button type='button'>Click Me</button></code> <!--Markdown--> `` There's an inline back-tick (`). `` <!--Rendered HTML--> <code>There's an inline back-tick (`).</code>

• برنامج تعليمي تفاعلي للتعرف على التعليمات البرمجية.
• Dingus الرابط الثابت للتحقق من المثال الكامل مع المعاينة و AST.
• تعرف على المزيد حول امتدادات التعليمات البرمجية.

كتل التعليمات البرمجية

عنصر نص HTML المنسق مسبقًا ، <pre> ، مدعوم أيضًا. يمكن القيام بذلك باستخدام ثلاثة على الأقل وعدد متساوٍ من العلامات الخلفية ( ` ) ، أو علامة التلدة ( ~ ) - يشار إليها عادةً باسم السياج الكود ، أو مسافة بادئة جديدة للسطر لا تقل عن 4 مسافات.

 <!--Markdown--> ``` const dedupe = (array) => [...new Set(array)]; ``` <!--Rendered HTML--> <pre><code>const dedupe = (array) => [...new Set(array)];</code></pre> <!--Markdown--> const dedupe = (array) => [...new Set(array)]; <!--Rendered HTML--> <pre><code>const dedupe = (array) => [...new Set(array)];</code></pre>

• برنامج تعليمي تفاعلي للتعرف على التعليمات البرمجية.
• Dingus الرابط الثابت للتحقق من المثال الكامل مع المعاينة و AST.
• تعرف على المزيد حول كتل التعليمات البرمجية المسيجة والمسافة البادئة.

باستخدام Inline HTML

وفقًا لملاحظة المواصفات الأصلية لـ John Grubers حول HTML المضمّن ، فإن أي ترميز لا يشمله بناء جملة Markdown ، يمكنك ببساطة استخدام HTML نفسه ، مع القيود الوحيدة هي عناصر HTML على مستوى الكتلة - على سبيل المثال <div> ، <table> ، <pre> ، <p> ، وما إلى ذلك - يجب فصلها عن المحتوى المحيط بأسطر فارغة ، ويجب عدم وضع مسافة بادئة بين علامتي البداية والنهاية للكتلة بعلامات تبويب أو مسافات.

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

للمضي قدما

CommonMark هو عمل مستمر قيد التقدم مع آخر تحديث لمواصفاته في 6 أبريل 2019. هناك عدد من التطبيقات الشائعة التي تدعمه في مجموعة أدوات Markdown. مع إدراك جهود CommonMark نحو التوحيد القياسي ، أعتقد أنه يكفي أن نستنتج أنه في بساطة Markdown ، هناك الكثير من العمل الجاري خلف الكواليس وأنه أمر جيد لجهود CommonMark أن المواصفات الرسمية لـ GitHub Flavored Markdown يعتمد على المواصفات.

لا يمنع التحرك نحو جهود توحيد CommonMark إنشاء النكهات لتوسيع بناء الجملة المدعوم ، وبما أن CommonMark تستعد للإصدار 1.0 مع المشكلات التي يجب حلها ، فهناك بعض الموارد المثيرة للاهتمام حول الجهد المستمر الذي يمكنك استخدامه من أجل تمعن.

موارد

• تقديم Markdown بواسطة John Gruber
• موقع CommonMark الرسمي
• GitHub Flavored Markdown المواصفات
• الريبو الرسمي cmark
• شوكة جيثب من cmark
• Markdown على ويكيبيديا
• دليل Markdown