في المرة الأولى التي تجاوزت فيها README الخاصة بي ألف سطر، فعلت ما يفعله الجميع: لقد قمت بالتمرير. ثم قمت بالتمرير أكثر. في مكان ما حول الممر الرابع بحثًا عن "؛ النشر والاقتباس؛ القسم، استسلمت وبدأت في كتابة جدول محتويات يدويًا في أعلى الملف. وقد نجح ذلك حتى قمت بإعادة تسمية عنوان، ونسيت تحديث الرابط، وشحنت README حيث "؛ التكوين والاقتباس؛ لم يشير إلى شيء. يعد الرابط الموجود في الصفحة المعطل في وثائقك شيئًا صغيرًا، ولكنه نوع من الأشياء الصغيرة التي تخبر القارئ أنه لا أحد يهتم بالمتجر.
أقوم ببناء [Toolz.dev](/، مجموعة من أدوات المطورين المستندة إلى المتصفح، وأحتفظ بالكثير من Markdown: أدلة الأدوات، وملفات README، والمواصفات الداخلية، والمستندات التي تقرأها الآن. جدول المحتويات الذي يجب أن أحافظ عليه يدويًا هو جدول المحتويات الذي سيكذب في النهاية. لذلك قمت ببناء مولد ماركداون TOC للقيام بالجزء الممل بشكل صحيح في كل مرة، وهذا الدليل هو كل ما تعلمته عن روابط التثبيت أثناء بنائه.
ليرة تركية؛DR: جدول محتويات Markdown عبارة عن قائمة متداخلة من الروابط التي تنتقل إلى العناوين الموجودة في نفس الصفحة. تعمل الروابط لأن كل عنوان يحصل على معرف ربط تلقائي، ويتبع slug الذي يعينه GitHub قاعدة محددة: أحرف صغيرة من النص، وإسقاط علامات الترقيم بخلاف الواصلات، وتحويل المسافات إلى واصلات. الصق تخفيض السعر الخاص بك في المولد، واختر مستويات العناوين التي تريد تضمينها، وانسخ القائمة. تحسب الأداة عروض GitHub الدقيقة slugs، بما في ذلك
-1لاحقة للعناوين المكررة، لذلك لا ينكسر أي شيء عند لصقها مرة أخرى.
ما هو جدول محتويات Markdown؟
جدول المحتويات في Markdown ليس بناء جملة خاصًا. كومونمارك لا يحدد مثل هذا البناء، ولا يعرف أيضًا GitHub Flavored Markdown. إنها قائمة عادية حيث يكون كل عنصر رابطًا، وكل رابط يشير إلى مرساة داخل نفس المستند. عندما يقوم عارض Markdown مثل GitHub بتحويل عنوان إلى HTML، فإنه يعطي هذا العنوان أيضًا id سمة. عنوان مكتوب ك ## Getting Started يصبح تقريبا <h2 id="getting-started">Getting Started</h2>. بمجرد وجود هذا المعرف، يتم كتابة الرابط كـ [Getting Started](#getting-started) تمرير الصفحة إليها.
لذا فإن جدول المحتويات هو مجرد مجموعة من تلك الروابط، مع وضع مسافة بادئة لتعكس التسلسل الهرمي للعناوين
- [Getting Started](#getting-started)
- [Installation](#installation)
- [Configuration](#configuration)
- [Usage](#usage)
الحيلة بأكملها موجودة في كلمة واحدة من هذا المثال: المرساة. أخطأ في المرساة وفشل الرابط بصمت، ولا يتم التمرير في أي مكان. احصل عليه بشكل صحيح وتعمل كتلة المحتويات على GitHub، وفي معظم مولدات المواقع الثابتة، وداخل منصات التوثيق التي تتبع نفس التقليد. الجزء الصعب لا يكتب القائمة. الجزء الصعب هو التنبؤ بالمعرف الدقيق الذي سيخصصه كل عارض، ولهذا السبب يعد القيام بذلك يدويًا لعبة خاسرة على أي مستند يتغير.
كيف يتم إنشاء مراسي الرأس فعليًا؟
GitHub'؛s slug الخوارزمية حتمية وتستحق الحفظ، لأنه بمجرد معرفتها يمكنك التنبؤ بكل مرساة في الصفحة. الخطوات بالترتيب هي: تحويل نص العنوان إلى حرف صغير، وإزالة أي حرف ليس حرفًا أو رقمًا أو مسافة أو واصلة، ثم استبدال كل مسافة بواصلة. هذه هي القاعدة كلها.
العواقب هي حيث يسافر الناس. النظر في عنوان مثل ## Set Up & Config. الغلاف السفلي يعطي set up & config. إزالة علامة العطف (ولكن مع ترك المسافات حولها) يعطي set up config مع مساحتين حيث & اعتاد أن يكون. تحويل المساحات إلى واصلات ينتج set-up--config، مع واصلة مزدوجة. تبدو هذه الواصلة المزدوجة وكأنها خطأ، ولكنها بالضبط ما يقدمه GitHub، لذا فهي بالضبط ما يحتاجه الرابط الخاص بك. أداة "؛ ينظف ويقتبس؛ ستنتج الواصلة المزدوجة رابطًا لا يتم حله.
تنهار العناوين ذات علامات الترقيم الثقيلة أكثر مما تتوقع. ## C++ Guide يصبح c-guide، لأنه يتم تجريد علامتي الزائد وتصبح المساحة المتبقية واصلة واحدة. ## What's New? يصبح whats-new، لأن الفاصلة العليا وعلامة الاستفهام تختفي. الرموز التعبيرية ومعظم الرموز تختفي تمامًا. ال مولد ماركداون TOC يطبق حرف القاعدة هذا على الحرف بحيث يظهر لك slug المعرف الذي سيبنيه GitHub، دون أي تخمين.
ماذا يحدث عندما يكون العنوانان متماثلين؟
المستندات تكرر العناوين. قد تحتوي سجل التغيير على ثلاثة أقسام جميعها بعنوان ### Fixed. إذا قام كل واحد منهم بإنتاج slug fixed، الرابط الأول فقط هو الذي سيعمل. يقوم GitHub بحل هذه المشكلة عن طريق ترقيم التكرارات: الأول Fixed يحصل fixed، يحصل الثاني fixed-1، يحصل الثالث fixed-2، وهكذا في ترتيب الوثيقة. يتم إلحاق اللاحقة بعد القاعدة slug بواصلة.
يعد هذا أحد الأسباب الأكثر شيوعًا لعدم مزامنة جدول المحتويات المكتوب بخط اليد. إذا قمت بإضافة قسم ثانٍ بالاسم الذي استخدمته بالفعل، تصبح المرساة بهدوء -1، ويشير الرابط القديم الخاص بك الآن إلى المكان الخطأ أو إلى أي مكان على الإطلاق. يتتبع المولد كل slug ينبعث منه ويطبق نفس اللاحقة الرقمية، لذلك ترتبط العناوين المتكررة بالحدث الصحيح.
ما أنواع العناوين التي تقرأها الأداة؟
يحتوي Markdown على نمطين للعناوين، ويجب على المولد الكامل قراءة كليهما. المشترك هو ATX، حيث يبدأ السطر من واحد إلى ستة # الأحرف متبوعة بنص العنوان. عدد التجزئة هو المستوى، لذلك # هو H1 و ###### هو H6. النمط الثاني هو Setext، حيث يتم وضع خط من النص في السطر التالي مع علامات يساوي H1 أو واصلات لـ H2:
Document Title
==============
A Section
---------
ينتج كلا الأسلوبين عناوين بمعرفات ربط، لذا ينتمي كلاهما إلى جدول المحتويات. الجزء الصعب من Setext هو إخبار عنوان حقيقي تحته خط بصرف النظر عن القاعدة الأفقية، لأن سطر الواصلات يمكن أن يعني أيًا منهما. القاعدة التي يستخدمها المولد هي أن تسطير الواصلة يتم احتسابه كعنوان فقط عندما يكون السطر الموجود فوقه مباشرة نص فقرة عادي، وليس سطرًا فارغًا، أو عنصر قائمة، أو اقتباس كتلة، أو بناء كتلة آخر. أ --- يعد الجلوس بمفرده مع وجود أسطر فارغة حوله بمثابة استراحة موضوعية، ويتم تجاهله بشكل صحيح.
هناك فئة أخرى يجب التعامل معها، وهي الفئة التي تدمر الأدوات الساذجة بهدوء: العناوين داخل التعليمات البرمجية. إذا كان المستند الخاص بك يحتوي على كتلة تعليمات برمجية مسيجة تعرض أوامر shell، فستبدأ بعض هذه الأسطر بـ # كتعليقات. هذه ليست عناوين، ويجب ألا تظهر أبدًا في المحتويات. يتتبع المولد كتل التعليمات البرمجية المسيجة (تلك المحددة بواسطة علامات خلفية ثلاثية أو علامات تلدة ثلاثية) ويتخطى أيًا منها # خط داخلهم. تعليق شل مثل # install dependencies في المثال يبقى حيث ينتمي، في المثال.
كيف أتحكم في عمق جدول المحتويات؟
جدول المحتويات الذي يسرد كل عنوان وصولاً إلى H6 ليس جدول محتويات، بل هو نسخة ثانية من المستند. تقرأ معظم برامج README بشكل أفضل عندما تغطي المحتويات H2 وH3 فقط، مما يمنح القراء الأقسام الرئيسية وأطفالهم المباشرين دون إغراقهم بالتفصيل. يتيح لك المولد تعيين الحد الأدنى والحد الأقصى للمستوى، ويتضمن فقط العناوين التي تقع في هذا النطاق.
السلوك الدقيق هنا هو المسافة البادئة. إذا قمت بتضمين H2 إلى H4، فإن الاتجاه الأقل ضحالة الذي احتفظت به هو H2، ويجب أن يكون متساطحًا مع الهامش الأيسر بدلاً من وضع مسافة بادئة كما لو كان H1 غير مرئي فوقه. يقيس المولد عمق التداخل بالنسبة إلى الاتجاه الأقل ضحالة الذي يتضمنه بالفعل، لذا فإن كتلة المحتويات التي تبدأ عند H2 تبدأ بدون مسافة بادئة. هذا هو الفرق بين القائمة التي تبدو مقصودة وتلك التي تبدو وكأنها فقدت عمودها الأول.
يمكنك أيضًا اختيار علامة القائمة. تستخدم القائمة غير المرتبة رصاصة لكل إدخال، وهو المظهر التقليدي لـ README. تقوم القائمة المرتبة بترقيم الإدخالات، ويقوم المولد بإعادة تشغيل العد داخل كل مستوى تداخل بحيث يقرأ المخطط التفصيلي المرقم بشكل صحيح بدلاً من العد مباشرة من واحد إلى خمسين. يمكن أن تكون المسافة البادئة مسافتين أو أربع مسافات أو علامة تبويب، اعتمادًا على ما تستخدمه بقية المستند.
ماذا عن العناوين المميزة وغير اللاتينية؟
ليس كل عنوان باللغة الإنجليزية البسيطة، ويجب أن تتعامل قاعدة slug مع الأمر. يحتفظ GitHub بالحروف من الأبجديات الأخرى بدلاً من تجريدها، لذا فإن العنوان يشبه ## Configuración يحتفظ بأحرفه المميزة ويصبح configuración، والعنوان باللغة السيريلية أو اليونانية يحتفظ بهذه الحروف أيضًا. ما تتم إزالته هو علامات الترقيم والرموز، وليس الحروف، بغض النظر عن البرنامج النصي. يتبع المولد نفس المبدأ من خلال التعامل مع أي حرف أو رقم Unicode كحرف slug صالح، لذلك ينتج المستند متعدد اللغات نقاط ربط تتطابق مع ما يقدمه GitHub بدلاً من صف من الروابط الفارغة.
وهذا يهم أكثر مما يظهر لأول مرة. غالبًا ما تجد الفرق التي تكتب الوثائق باللغة الإسبانية أو الألمانية أو اليابانية أن أدوات slug الساذجة تشوه عناوينها إلى نقاط تثبيت غير قابلة للاستخدام، لأن هذه الأدوات تفترض ASCII. إذا لم تشر روابطك مطلقًا إلى أي شيء على README مترجم، فمن المؤكد تقريبًا أن slug الذي تجاهل الحروف غير ASCII بصمت هو السبب. يؤدي إنشاء كتلة المحتويات باستخدام أداة مدركة لـ Unicode إلى إزالة فئة الارتباط المعطل بأكملها، ويعني أن نفس المستند يمكنه الاحتفاظ بالعناوين بأكثر من لغة واحدة دون أن يفقد أي منها نقاط التثبيت الخاصة به.
متى يجب أن أستخدم جدول المحتويات الذي تم إنشاؤه مقابل جدول تلقائي؟
تقوم بعض الأنظمة الأساسية بإنشاء جدول محتويات لك. يدعم GitLab أ [[_TOC_]] الرمز المميز، تقوم بعض مواقع الويكي بإدخال مربع محتويات تلقائيًا، وتقوم أطر التوثيق مثل Docusaurus بعرض مخطط تفصيلي على الصفحة من عناوينك دون كتابة أي شيء. عندما تعمل داخل أحد هذه الأنظمة، استخدم الميزة المضمنة. يظل محدثًا دون أي جهد لأن النظام الأساسي يقوم بتجديده في كل عرض.
المولد يكسب مكانه في كل مكان آخر، و"؛ في كل مكان آخر"؛ مكان كبير. لا تقوم GitHub READMEs بإنشاء كتلة محتويات تلقائيًا، لذا تحتاج الصفحة المقصودة للمستودع إلى قائمة Markdown حقيقية مخصصة في الملف. يحتاج Markdown الذي يتم تحويله إلى شيء آخر، أو إرساله عبر البريد الإلكتروني، أو لصقه في مشكلة، أو عرضه بواسطة الحد الأدنى من العارض إلى كتلة محتويات ثابتة لأنه لا يوجد محرك لبناء واحدة بسرعة. يوضح الجدول أدناه المكان المناسب لكل نهج.
| حالة | أفضل نهج | لماذا |
|---|---|---|
| جيثب التمهيدي | قائمة ثابتة تم إنشاؤها | يعرض GitHub معرفات العناوين ولكنه لا يقوم بإدخال TOC تلقائيًا |
| GitLab ويكي أو المستندات | [[_TOC_]] رمز مميز |
أصلي، حالي دائمًا |
| صفحة دوكوصور / MkDocs | مخطط مدمج | الإطار يعرضه من العناوين |
| ملف Markdown عادي للتصدير | قائمة ثابتة تم إنشاؤها | لا يوجد عارض لبناء واحدة في وقت العرض |
| إصدار أو سحب وصف الطلب | قائمة ثابتة تم إنشاؤها | تعمل المراسي، ولكن لا شيء يقوم بإنشاء القائمة تلقائيًا |
القاعدة الأساسية: إذا كان الشيء الذي يعرض Markdown الخاص بك يمكنه إنشاء المحتويات بنفسه، فدعه. إذا كان من الممكن قراءة Markdown الخاص بك في مكان لا يمكنه ذلك، فقم بإنشاء القائمة والالتزام بها. عندما تقوم بالتحويل بين التنسيقات، فإن تخفيض السعر إلى محول HTML و ال محول HTML إلى Markdown قم بالاقتران بشكل طبيعي مع كتلة المحتويات التي تم إنشاؤها، لأن المراسي تنجو من الرحلة ذهابًا وإيابًا.
كيف يتناسب هذا مع بقية سير عمل Markdown؟
جدول المحتويات هو جزء واحد من الحفاظ على المستندات الطويلة قابلة للقراءة، ويعمل بشكل أفضل جنبًا إلى جنب مع بعض العادات. حافظ على ثبات نص العنوان الخاص بك بمجرد نشر الروابط إليه، لأن إعادة تسمية العنوان تغير slug الخاص به وتكسر كل رابط يشير إليه. عند إعادة التسمية، قم بإعادة إنشاء المحتويات بدلاً من تحرير الرابط الوحيد الذي تتذكره، نظرًا لأن إعادة التسمية غالبًا ما تؤدي إلى تغيير ترقيم اللاحقة المكررة إلى أسفل الملف.
يستفيد المحتوى المنظم من أدوات أخرى في نفس العائلة. عندما يعتمد المستند على البيانات الجدولية، فإن مولد الجدول يقوم بإنشاء جداول أنابيب محاذاة بشكل صحيح بحيث لا يصبح الجدول المكتوب يدويًا صحيحًا أبدًا. عندما ترث HTML الفوضوي الذي يحتاج إلى أن يصبح HTML نظيفًا، أو Markdown نظيفًا يحتاج إلى أن يصبح HTML، فإن المحولات تتعامل مع الترجمة مع الحفاظ على بنية العنوان. وإذا كنت تقوم بمراجعة مستند لمعرفة الطول أو توازن الكلمات الرئيسية، فإن عداد الكلمات يمنحك الأرقام دون لصق مسودتك في أي شيء قائم على السحابة.
كل شيء يعمل في المتصفح، وهو أمر مهم أكثر مما يبدو. غالبًا ما يحتوي برنامج README على أسماء ميزات أو عناوين URL داخلية أو تفاصيل العميل لم يتم إصدارها، ولا ينبغي تحميل أي منها إلى خادم طرف ثالث فقط لإنشاء قائمة من الروابط. يقوم المولد بتوزيع Markdown الخاص بك باستخدام JavaScript من جانب العميل، وبالتالي لا يغادر المستند جهازك أبدًا. إذا كانت الخصوصية في أدوات المطورين شيئًا تفكر فيه، فقم بالكتابة عليه خصوصية البيانات والأدوات عبر الإنترنت يغطي سبب كون المعالجة المحلية هي الإعداد الافتراضي الصحيح، و مجموعة أدوات مطور الويب قم بتجميع بقية المرافق التي أصل إليها يوميًا.
مثال سريع العمل
لنفترض أن لديك هذه الوثيقة:
# Payment Service
## Getting Started
### Requirements
### Local Setup
## API Reference
### Authentication
### Errors
## Deployment
اضبط النطاق على H2 إلى H3، واختر قائمة نقطية، واترك روابط التثبيت قيد التشغيل. ينتج المولد:
- [Getting Started](#getting-started)
- [Requirements](#requirements)
- [Local Setup](#local-setup)
- [API Reference](#api-reference)
- [Authentication](#authentication)
- [Errors](#errors)
- [Deployment](#deployment)
يتم استبعاد عنوان H1 لأنه يقع فوق النطاق، وأقسام H2 متدفقة إلى اليسار، ويتم وضع مسافة بادئة لأطفال H3 بمستوى واحد. لصق الكتلة الموجودة أسفل العنوان مباشرةً في برنامج README الخاص بك وينتقل كل إدخال إلى القسم الخاص به على GitHub. هذه هي المهمة بأكملها، التي يتم إنجازها في الوقت الذي تستغرقه قراءة هذه الجملة، وتظل صحيحة لأن الآلة قامت بحساب slugs بدلاً منك.
الأسئلة المتداولة
كيف يعمل جدول محتويات Markdown؟
جدول محتويات Markdown عبارة عن قائمة من الروابط التي تشير إلى مثبتات العناوين داخل نفس الصفحة. يتم إعطاء كل عنوان في مستند Markdown معرفًا تلقائيًا ورابطًا مكتوبًا كـ قسم ينتقل إليه. تقرأ هذه الأداة عناوينك، وتبني المراسي المطابقة، وتجمع القائمة المتداخلة لك.
كيف يتم إنشاء روابط الربط؟
تتبع المراسي قاعدة GitHub slug: يتم إزالة نص العنوان بأحرف صغيرة، وتتم إزالة علامات الترقيم بخلاف الواصلات، وتصبح المسافات واصلات. "؛ ضبط &؛ التكوين والاقتباس؛ يصبح إعداد المعرف--التكوين. عندما ينتج عن عنوانين نفس slug، يحصل الثاني على لاحقة -1، والثالث -2، وهكذا، لمطابقة كيفية عرض GitHub لهما.
هل يعمل مع ملفات GitHub README؟
نعم. تعكس الخوارزمية slug الخوارزمية التي يستخدمها GitHub لعرض معرفات العناوين، بحيث يتم حل روابط جدول المحتويات بشكل صحيح داخل README على github.com. الصق برنامج README الخاص بك، واختر مستويات العناوين الخاصة بك، وقم بإسقاط القائمة التي تم إنشاؤها أسفل العنوان.
هل يمكنني اختيار مستويات العناوين التي تظهر؟
نعم. قم بتعيين الحد الأدنى والحد الأقصى للمستوى، على سبيل المثال من H2 إلى H4، ويتم تضمين العناوين الموجودة في هذا النطاق فقط. يتم قياس عمق التعشيش بالنسبة للعنوان المضمن الأقل عمقًا، لذلك لا يبدأ المخطط أبدًا بمسافة بادئة فارغة كبيرة.
هل يتم تضمين العناوين داخل كتل التعليمات البرمجية؟
لا. يتم التعامل مع الخطوط التي تبدأ بالرقم # داخل كتلة التعليمات البرمجية المسيجة (المحددة بعلامات خلفية ثلاثية أو علامات ثلاثية) كرمز، وليس كعناوين، لذلك لا تظهر مقتطفات الأمثلة وتعليقات الصدفة أبدًا في جدول المحتويات.
ما الفرق بين TOC المطلوبة وغير المرتبة؟
يستخدم جدول المحتويات غير المرتب علامات نقطية مثل واصلة لكل إدخال، بينما يستخدم الجدول المرتب أرقامًا تتزايد داخل كل مستوى تداخل. اختر مرتبًا عندما يستفيد القراء من مخطط تفصيلي مرقم، وغير مرتب لكتلة محتويات أخف وأكثر تقليدية.
هل تدعم الأداة عناوين Setext؟
نعم. يقرأ كلا من عناوين ATX التي تبدأ بـ # وعناوين Setext، حيث يتم وضع خط تحت سطر النص بعلامات متساوية لـ H1 أو واصلات لـ H2. يتم تحويل كلا الأسلوبين إلى روابط ربط بنفس الطريقة.
هل مولد Markdown TOC مجاني وخاص؟
نعم. إنه مجاني تمامًا بدون تسجيل ولا حدود. تتم جميع عمليات التحليل في متصفحك باستخدام JavaScript من جانب العميل، لذا فإن Markdown الذي تقوم بلصقه لا يترك جهازك أبدًا وتستمر الأداة في العمل دون اتصال بالإنترنت بمجرد تحميل الصفحة.
