markdown linting accessibility स्टाइल-गाइड documentation

Markdown लिंटिंग गाइड: 15 सामान्य समस्याएँ और उनके समाधान

छोड़े गए शीर्षकों, गायब छवि वैकल्पिक पाठ, नंगे यूआरएल, टूटे हुए कोड बाड़, असंगत सूचियां और विकृत तालिकाओं सहित सामान्य Markdown समस्याओं को ढूंढें और ठीक करें।

W
__पी_ए__ टीम
·

Markdown अनुमेय है।संरचनात्मक गलतियों वाला दस्तावेज़ अभी भी प्रस्तुत किया जा सकता है, जिससे उन गलतियों को तब तक नज़रअंदाज़ करना आसान हो जाता है जब तक कि कोई तालिका टूट न जाए, कोई शीर्षक नेविगेशन से गायब न हो जाए, या कोई छवि स्क्रीन-रीडर उपयोगकर्ता के लिए अर्थहीन न हो जाए।

Markdown लिंटिंग प्रकाशन से पहले संरचनात्मक, पहुंच और स्थिरता समस्याओं के लिए स्रोत पाठ की जांच करने की प्रक्रिया है।से शुरू करें Markdown लिंटर छोड़े गए शीर्षक स्तरों, गायब छवि वैकल्पिक पाठ, नंगे यूआरएल, बिना लेबल वाले या खुले कोड बाड़ और अनुगामी रिक्त स्थान को पकड़ने के लिए।फिर व्यापक संपादकीय समीक्षा के लिए इस गाइड में मैन्युअल चेकलिस्ट का उपयोग करें।

लिंटिंग मनमानी प्राथमिकताओं को लागू करने के बारे में नहीं है।एक उपयोगी नियम को वास्तविक पढ़ने, प्रतिपादन, रखरखाव, या पहुंच संबंधी समस्या को रोकना चाहिए।

त्वरित पूर्व-प्रकाशन चेकलिस्ट

जांचेंयह क्यों मायने रखता हैस्वचालित या मैनुअल?
शीर्षक पदानुक्रमदस्तावेज़ संरचना को सुरक्षित रखता हैलिंटर
छवि वैकल्पिक पाठछवियों को बिना देखे समझने योग्य बनाता हैलिंटर
वर्णनात्मक लिंकपहुंच और स्कैनिंग में सुधार करता हैलिंटर + मैनुअल समीक्षा
बंद कोड बाड़शेष पृष्ठ को कोड बनने से रोकता हैलिंटर
कोड भाषा लेबलउपयोगी सिंटैक्स हाइलाइटिंग सक्षम करता हैलिंटर
अनुगामी रिक्त स्थानअदृश्य, बोली-विशिष्ट व्यवहार से बचा जाता हैलिंटर
एक स्पष्ट पृष्ठ शीर्षकपृष्ठ उद्देश्य को स्पष्ट रखता हैमैनुअल समीक्षा
सुसंगत सूचियाँटूटे हुए घोंसले को रोकता हैमैनुअल समीक्षा
मान्य तालिकाएँस्तंभ संरचना को बरकरार रखता हैमैनुअल समीक्षा
अद्वितीय शीर्षकडुप्लिकेट एंकर भ्रम को रोकता हैमैनुअल समीक्षा
पोर्टेबल 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 रेंडरर्स और सामग्री वर्कफ़्लो भिन्न होते हैं।यदि कोई छवि पूरी तरह से सजावटी है, तो पहले पूछें कि क्या वह तकनीकी दस्तावेज में शामिल है।

लिंटर खाली ऑल्ट टेक्स्ट के साथ Markdown छवियों को फ़्लैग करता है।द छवि फ़ॉर्मैटर एक स्पष्ट वैकल्पिक और वैकल्पिक कैप्शन के साथ छवि मार्कअप उत्पन्न कर सकता है।

समस्या

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

नंगे यूआरएल को स्कैन करना कठिन होता है और जोर से पढ़ने पर अप्रिय हो सकता है।जेनेरिक लिंक टेक्स्ट ज्यादा बेहतर नहीं है:

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

ठीक करें

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

वर्णनात्मक लिंक पाठकों को बताते हैं कि वे क्या खोलेंगे।लिंक की सूची में निकाले जाने पर भी वे सार्थक बने रहते हैं।

लिंटर कई नंगे की पहचान करता है http:// and https:// यूआरएल, लेकिन लिंक टेक्स्ट उपयोगी है या नहीं, इसका निर्णय करने के लिए संपादकीय समीक्षा अभी भी आवश्यक है।

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 टीओसी जेनरेटर और लक्ष्य प्लेटफ़ॉर्म में एंकरों को सत्यापित करें।

12. अनुगामी व्हाईटस्पेस

पंक्ति के अंत में रिक्त स्थान अदृश्य हैं।कुछ Markdown बोलियों में, दो अनुगामी स्थान एक हार्ड लाइन ब्रेक बनाते हैं, जिसका अर्थ है कि एक आकस्मिक संपादक कार्रवाई प्रतिपादन को बदल सकती है।

लिंटर रिक्त स्थान के पीछे होने की रिपोर्ट करता है ताकि आप यह तय कर सकें कि यह जानबूझकर किया गया है या नहीं।अनुच्छेद पृथक्करण के लिए एक खाली पंक्ति को प्राथमिकता दें।यदि वास्तव में हार्ड लाइन ब्रेक की आवश्यकता है, तो परियोजना के चुने हुए सम्मेलन को लगातार दस्तावेजित करें और लागू करें।

संपादक आमतौर पर सेव करने पर स्वचालित रूप से पिछला व्हाइटस्पेस हटा सकते हैं, लेकिन जांच लें कि इससे लीगेसी सामग्री में जानबूझकर लाइन ब्रेक नहीं बदलता है।

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 विकी लिंक, 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 और प्लेटफ़ॉर्म एक्सटेंशन;
  • अधिकतम लाइन लंबाई, यदि टीम एक का उपयोग करती है;
  • लिंक कैसे जांचे जाते हैं;
  • कौन सा लिंटर नियम प्रकाशन को रोकता है।

उन नियमों से प्रारंभ करें जो वास्तविक दोषों को रोकते हैं।कोई नियम तभी जोड़ें जब टीम उस समस्या को समझ जाए जिसे वह हल कर रही है।

FAQ

क्या वैध Markdown स्वचालित रूप से पहुंच योग्य है?

नहीं। वैध सिंटैक्स में अभी भी खाली वैकल्पिक पाठ, अस्पष्ट लिंक, भ्रमित करने वाले शीर्षक, दुर्गम आरेख और खराब पढ़ने का क्रम हो सकता है।पहुंच के लिए संरचनात्मक और संपादकीय समीक्षा की आवश्यकता होती है।

क्या Markdown लिंटर मेरे दस्तावेज़ को फिर से लिखेगा?

WordToMD लिंटर लाइन-क्रमांकित समस्याओं की रिपोर्ट करता है।यह चुपचाप स्रोत को दोबारा नहीं लिखता है, इसलिए आप प्रत्येक सुधार पर नियंत्रण बनाए रखते हैं।

लिंटर एक नंगे यूआरएल की रिपोर्ट क्यों करता है?

वर्णनात्मक लिंक टेक्स्ट को स्कैन करना आसान है और सहायक तकनीक के लिए अधिक उपयोगी है।यूआरएल को एक सार्थक लेबल से बदलें, जब तक कि शाब्दिक पता पाठकों के लिए आवश्यक जानकारी न हो।

क्या बिना लेबल वाला कोड बाड़ हमेशा गलत होता है?

हमेशा नहीं, लेकिन एक सही भाषा पहचानकर्ता आमतौर पर स्पष्टता और वाक्यविन्यास हाइलाइटिंग में सुधार करता है।उपयोग करें text ।

क्या सभी परियोजनाओं में समान लिंटिंग नियमों का उपयोग किया जाना चाहिए?

संख्या A GitHub README, एक Obsidian वॉल्ट, एक API संदर्भ और एक प्रकाशन साइट में अलग-अलग परंपराएं हैं।संरचनात्मक और पहुंच नियमों का एक मुख्य सेट साझा करें, फिर गंतव्य-विशिष्ट जांच जोड़ें।

क्या लिंटिंग प्रूफरीडिंग की जगह ले सकती है?

नहीं। एक लिंटर पैटर्न का पता लगाता है।यह तकनीकी सत्यता, तर्क की गुणवत्ता, उपयोगकर्ता के इरादे, या संदर्भ में कोई वाक्य समझने योग्य है या नहीं, इसकी विश्वसनीय रूप से पुष्टि नहीं कर सकता है।

निष्कर्ष

अच्छा Markdown रेंडर करने वाले स्रोत से कहीं अधिक है।इसकी एक स्पष्ट रूपरेखा, सार्थक लिंक, सुलभ छवियां, पूर्ण कोड बाड़, सुसंगत सूचियां, वैध तालिकाएं और इसके प्रकाशन मंच के साथ एक परिभाषित संबंध है।

चलाएँ Markdown लिंटर का उपयोग करें Markdown संपादक , और केंद्रित फ़ॉर्मेटर केवल वहीं लागू करें जहां वे स्रोत को बनाए रखना आसान बनाते हैं।परिणाम Markdown है जो भविष्य के संपादनों में अधिक पोर्टेबल, सुलभ और भरोसेमंद है।