markdown linting accessibility دليل الأسلوب documentation

دليل فحص Markdown: 15 مشكلة شائعة وكيفية إصلاحها

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

W
WordToMD الفريق
·

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

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

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

قائمة المراجعة السريعة لما قبل النشر

فحصلماذا يهمآلي أم يدوي؟
التسلسل الهرمي للعناوينيحافظ على بنية الوثيقةلينتر
نص بديل للصورةيجعل الصور مفهومة بدون البصرلينتر
روابط وصفيةيحسن إمكانية الوصول والمسح الضوئيلينتر + مراجعة يدوية
أسوار الكود المغلقةيمنع أن تصبح بقية الصفحة رمزًالينتر
تسميات لغة الكودتمكين تمييز بناء الجملة المفيدلينتر
مسافة بيضاء زائدةيتجنب السلوك غير المرئي الخاص باللهجةلينتر
عنوان صفحة واحد واضحيحافظ على غرض الصفحة واضحًاالمراجعة اليدوية
قوائم متسقةيمنع التداخل المكسورالمراجعة اليدوية
جداول صالحةيحافظ على بنية العمود سليمةالمراجعة اليدوية
عناوين فريدةيمنع ارتباك المرساة المكررالمراجعة اليدوية
الاستخدام المحمول HTMLيتجنب حالات الفشل الخاصة بالعارضالمراجعة اليدوية
فقرات قابلة للقراءةيحسن الفهمالمراجعة اليدوية

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

1. تم تخطي مستويات العناوين

مشكلة

# Deployment Guide

### Configure credentials

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

إصلاح

# Deployment Guide

## Configure credentials

استخدم العناوين لوصف التسلسل الهرمي، وليس لاختيار حجم مرئي.إذا كان "تكوين بيانات الاعتماد" ينتمي حقًا إلى قسم مفقود، فأضف هذا القسم:

# Deployment Guide

## Preparation

### Configure credentials

المجلس مدقق Markdown يُبلغ عن عنوان يقفز بأكثر من مستوى واحد.

2. عناوين H1 المتعددة أو المفقودة

يجب أن تحتوي الصفحة عادةً على عنوان واحد واضح.تقوم بعض أنظمة التوثيق بتوليد H1 من المادة الأمامية، بينما يتوقع البعض الآخر وجوده في الجسم Markdown.تعرف على الاتفاقية التي يستخدمها موقعك.

مصدر غامض

# Installation

# Configuration

مصدر واضح

# Product setup

## Installation

## Configuration

إذا تم عرض قالب موقعك title: Product setup كصفحة H1، قد يبدأ النص بـ H2 بدلاً من ذلك.القاعدة ليست "يجب أن يحتوي كل ملف Markdown على ملف واحد بالضبط #.” The rule is “the rendered page needs one unambiguous primary heading.”

3. العناوين المستخدمة فقط للتأكيد

يقوم هذا المصدر بإنشاء إدخال مخطط تفصيلي غير ضروري:

#### Important!

إذا كان النص لا يقدم قسمًا، فاستخدم النثر أو وسيلة الشرح المناسبة:

**Important:** Back up the database before continuing.

يجب أن تساعد العناوين القراء على التنقل.تجعل العناوين المزخرفة جدول المحتويات صاخبًا وتقلل من فائدة التنقل المساعد.

4. الصور بدون نص بديل

مشكلة

![](architecture.png)

لا تحتوي الصورة على نص بديل.القارئ الذي لا يستطيع رؤيتها لا يتلقى أي تفسير، ولا يستطيع أي شخص يتصفح الصور المعطلة أو المعطلة تحديد الغرض منها.

إصلاح

![Request flow from the browser through the API gateway to the orders service](architecture.png)

وصف المعلومات التي تساهم بها الصورة، وليس مظهرها وحده.تجنب عبارات مثل "صورة" ما لم تكن الوسيلة مهمة.

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

تضع علامة linter على الصور Markdown بنص بديل فارغ.ال منسق الصور يمكنه إنشاء علامة للصورة باستخدام بديل واضح وتسمية توضيحية اختيارية.

مشكلة

Visit https://example.com/docs/setup for more information.

من الصعب فحص عناوين URL العارية ويمكن أن تكون غير سارة عند قراءتها بصوت عالٍ.نص الرابط العام ليس أفضل بكثير:

[Click here](https://example.com/docs/setup).

إصلاح

Read the [service setup guide](https://example.com/docs/setup).

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

يحدد الوبر العديد من العاري http:// and https:// عناوين URL، لكن المراجعة التحريرية لا تزال مطلوبة للحكم على ما إذا كان نص الارتباط مفيدًا أم لا.

6. أسوار الكود غير المغلقة

مشكلة

```javascript
const status = 'ready';

## Next section

بدون سياج إغلاق، قد يتعامل العارض مع بقية الصفحة كرمز.

إصلاح

```javascript
const status = 'ready';
```

## Next section

يمكن للسياج غير المغلق أن يكسر جزءًا كبيرًا من مستند صالح.يُبلغ اللينتر عن الخط الذي يبدأ منه السياج الذي لا مثيل له.

7. أسوار الكود بدون معرفات اللغة

أقل فائدة

```
npm run build
```

أفضل

```bash
npm run build
```

يتيح معرف اللغة تمييز بناء الجملة وإيصال نوع المحتوى الذي يراه القارئ.استخدم المعرفات الشائعة مثل javascript, typescript, json, html, css, bash, powershell, yamlأو markdown.

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

8. المسافة البادئة للقائمة غير متناسقة

مشكلة

- Install dependencies
    - Production packages
  * Development packages
	- Optional tools

من الصعب مراجعة علامات التبويب والمسافات والعلامات المختلطة وقد يتم عرضها على مستويات مختلفة.

إصلاح

- Install dependencies
  - Production packages
  - Development packages
  - Optional tools

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

استخدم منسق القوائم المتداخلة لتطبيع التعداد النقطي المختلط والترقيم وعلامات التبويب والمسافات البادئة قبل المراجعة النهائية.

9. التسلسلات الرقمية المكتوبة يدويًا

صيانة القوائم المرقمة الطويلة مكلفة:

1. Download the package.
2. Verify the checksum.
3. Install the package.
4. Restart the service.

يسمح العديد من عارضي Markdown باستخدام كل عنصر 1. مع استمرار عرض التسلسل المرتب:

1. Download the package.
1. Verify the checksum.
1. Install the package.
1. Restart the service.

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

لا تقم بدمج الأرقام المكتوبة وعلامات القائمة المرتبة ونص الفقرة.قم بتأكيد النتيجة المقدمة بعد تحرير الخطوات المتداخلة.

10. الجداول المشوهة

مشكلة

| Name | Status | Owner |
| --- | --- |
| Search | Ready | Maya |
| Billing | Review |

لا يحتوي الفاصل وصفوف البيانات على نفس العدد المنطقي من الأعمدة.

إصلاح

| Name | Status | Owner |
| --- | --- | --- |
| Search | Ready | Maya |
| Billing | Review | Unassigned |

تحقق أيضًا من وجود أحرف توجيه الإخراج غير القابلة للإلغاء داخل الخلايا:

| Command | Description |
| --- | --- |
| `test \| deploy` | Run the matching stage |

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

11. العناوين المكررة وتصادمات الارتساء

يمكن للمستند تكرار عنوان مرئي بشكل قانوني مثل "أمثلة"، ولكن قد تصبح معرفات الربط التي تم إنشاؤها تلقائيًا #examples, #examples-1و #examples-2.تختلف القاعدة الدقيقة حسب العارض.

العناوين المتكررة تجعل الروابط اليدوية هشة:

- [API examples](#examples)
- [CLI examples](#examples)

تفضيل العناوين الوصفية:

## API examples

## CLI examples

ثم قم بإنشاء جدول محتويات باستخدام ملف Markdown مولد TOC والتحقق من نقاط التثبيت في المنصة المستهدفة.

12. مسافة بيضاء زائدة

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

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

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

13. الخام HTML الذي يقلل من قابلية النقل

Markdown غالبًا ما يسمح بـ HTML المضمن:

<div class="warning-panel">
  Restarting the service ends active sessions.
</div>

قد تعمل هذه الكتلة على موقع ويب واحد ويتم التخلص منها أو تطهيرها أو تصميمها بشكل غير صحيح في مكان آخر.تفضل المحمولة Markdown عندما يمكنها التعبير عن نفس المعنى:

> **Warning:** Restarting the service ends active sessions.

استخدم HTML عمدًا للميزات Markdown التي لا يمكن التعبير عنها، مثل التحكم في حجم الصورة أو دعمها <details> كتلة.احتفظ بقائمة بالوجهات التي يجب أن يتم عرض المحتوى فيها واختبار كل واحدة منها.

المجلس منشئ وسائل الشرح بناء جملة خاص بالمنصة لـ GitHub، Obsidian، وMkDocs عندما تكون قابلية النقل أقل أهمية من العرض التقديمي الأصلي.

14. الفقرات الطويلة وضعف إمكانية المسح

Markdown يمكن أن تكون صالحة من الناحية الهيكلية ولا تزال صعبة القراءة.يجب إعادة تنظيم جدار النص الذي يحتوي على العديد من القرارات والتحذيرات والإجراءات.

الاستخدام:

  • فقرات قصيرة لفكرة رئيسية واحدة؛
  • عناوين وصفية للملاحة؛
  • قوائم للعناصر المتوازية؛
  • جداول للحقول القابلة للمقارنة فعليًا؛
  • كتل التعليمات البرمجية للإدخال والإخراج الحرفي؛
  • وسائل شرح لعدد صغير من الاستثناءات المهمة.

لا تحول كل جملة إلى رصاصة.تعمل القوائم بشكل أفضل عندما يكون للعناصر نفس الدور النحوي والمفاهيمي.

الاستخدام عدد الكلمات ووقت القراءة لفحص عدد الفقرات وعدد العناوين وطول القراءة، ولكن التعامل مع الإحصائيات كإشارات وليس كأهداف.

15. بناء الجملة الخاص بالعارض بدون خطة توافق

GitHub قوائم المهام، Obsidian روابط wiki، MkDocs التحذيرات، الحواشي السفلية، قوائم التعريفات، والمواد الأمامية كلها مفيدة، ولكنها غير مدعومة بشكل مماثل في كل مكان.

على سبيل المثال:

> [!NOTE]
> This callout is useful in destinations that recognize the syntax.

قبل اعتماد التمديد، أجب عن ثلاثة أسئلة:

  1. ما هو العارض الذي يمتلك المخرجات النهائية؟
  2. هل يحتاج المحتوى إلى النقل إلى مكان آخر لاحقًا؟
  3. ماذا سيراه القراء عندما يكون الامتداد غير مدعوم؟

احتفظ بأساس Markdown محمول وأضف بناء جملة النظام الأساسي عند حافة النشر عندما يكون ذلك ممكنًا.

سير عمل عملي للفحص

الخطوة 1: التحقق من الهيكل

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

الخطوة 2: تطبيع العناصر الصعبة

استخدم الأدوات المركزة للتنظيف الميكانيكي:

تنتج التغييرات المركزة اختلافات أصغر وأسهل في المراجعة مقارنة بالمنسق الواسع الذي يعيد كتابة الملف بأكمله.

الخطوة 3: معاينة الوثيقة

افتح المصدر في Markdown المحرر وقارن Markdown بالمخرجات المقدمة.تحقق:

  • العناوين وجدول المحتويات؛
  • القوائم وقوائم المهام؛
  • الجداول على شاشة ضيقة؛
  • الصور والروابط؛
  • كتل التعليمات البرمجية والتعليمات البرمجية المضمنة؛
  • وسائل الشرح أو الخام HTML.

الخطوة 4: اختبار الوجهة الحقيقية

لا يمكن للمعاينة العامة إعادة إنتاج كل عارض.افتح الملف في GitHub، Obsidian، GitLab، MkDocs، أو موقع التوثيق الفعلي قبل النشر.

الخطوة 5: مراجعة المعنى، وليس بناء الجملة فقط

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

توصيات دليل أسلوب الفريق

تعتبر الاتفاقية القصيرة الموثقة أكثر فعالية من عشرات التفضيلات غير المعلنة.تحديد:

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

ابدأ بالقواعد التي تمنع العيوب الحقيقية.أضف قاعدة فقط عندما يفهم الفريق المشكلة التي يحلها.

FAQ

هل يمكن الوصول إلى Markdown صالح تلقائيًا؟

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

هل سيقوم جهاز Markdown Linter بإعادة كتابة المستند الخاص بي؟

يُبلغ linter WordToMD عن مشكلات مرقمة.ولا يقوم بإعادة كتابة المصدر بصمت، لذلك يمكنك الاحتفاظ بالتحكم في كل تصحيح.

لماذا يُبلغ linter عن عنوان URL مجرد؟

نص الارتباط الوصفي أسهل في المسح وأكثر فائدة للتكنولوجيا المساعدة.استبدل عنوان URL بتسمية ذات معنى ما لم يكن العنوان الحرفي هو المعلومات التي يحتاجها القراء.

هل سياج الكود غير المسمى خاطئ دائمًا؟

ليس دائمًا، ولكن معرف اللغة الصحيح عادةً ما يعمل على تحسين الوضوح وإبراز بناء الجملة.استخدم text للإخراج العادي عند دعمه بدلاً من تعيين لغة برمجة غير دقيقة.

هل يجب على جميع المشاريع استخدام نفس قواعد الفحص؟

رقم. A GitHub README، وObsidian قبو، ومرجع API، وموقع النشر لها اتفاقيات مختلفة.قم بمشاركة مجموعة أساسية من القواعد الهيكلية وقواعد إمكانية الوصول، ثم قم بإضافة عمليات التحقق الخاصة بالوجهة.

هل يمكن أن يحل البطانة محل التدقيق اللغوي؟

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

النتيجة

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

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