Mac पर Obsidian में संपादित और GitHub पर पढ़े जाने वाले Markdown नोट के लिए, मानक Markdown लिंक और विशिष्ट, लोअरकेस शीर्षक नाम इस्तेमाल करें। setup जैसे एकल शब्द दोनों रेंडरर को एक ही लक्ष्य देते हैं; रिक्त स्थान वाले शीर्षकों पर अधिक ध्यान देना पड़ता है।

यह मार्गदर्शिका किसी नोट के भीतर और दो Markdown फ़ाइलों के बीच नेविगेशन पर केंद्रित है। व्यावहारिक लक्ष्य एक ऐसा पठनीय दस्तावेज़ बनाए रखना है, जिसमें यह न मान लिया जाए कि हर Markdown रेंडरर शीर्षक गंतव्यों की व्याख्या एक जैसे करता है।

कोई वैध Markdown लिंक अपने शीर्षक तक क्यों नहीं पहुँच सकता?

शीर्षक लिंक की दो अलग-अलग ज़रूरतें होती हैं: Markdown पार्सर को लिंक पहचानना चाहिए, और रेंडरर को उसका गंतव्य निर्धारित करना चाहिए। क्लिक करने योग्य लिंक पहली ज़रूरत पूरी होने का प्रमाण है। इच्छित सेक्शन तक पहुँचना दूसरी ज़रूरत पूरी होने का प्रमाण है।

CommonMark शीर्षक सिंटैक्स और फ़्रैगमेंट वाले लिंक परिभाषित करता है, जिनमें [link](#fragment) भी शामिल है। उसके शीर्षक उदाहरण शीर्षक-ID बनाने का कोई सार्वभौमिक एल्गोरिदम तय नहीं करते। यही अंतर बताता है कि केवल वैध Markdown सिंटैक्स से अलग-अलग ऐप्लिकेशन में सेक्शन नेविगेशन के मेल की गारंटी क्यों नहीं मिलती। CommonMark शीर्षक विनिर्देश और लिंक विनिर्देश देखें।

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

Obsidian अपने एक्सटेंशन के साथ CommonMark और GitHub Flavored Markdown का समर्थन करता है। इस समर्थन का अर्थ यह नहीं कि ऐप्लिकेशन-विशिष्ट हर लिंक हर जगह काम करेगा: Obsidian स्पष्ट रूप से चेतावनी देता है कि कुछ एक्सटेंशन अन्य ऐप्स में सादे टेक्स्ट के रूप में दिख सकते हैं। इसका विवरण Markdown संगतता दस्तावेज़ में है।

कौन-सी शीर्षक परंपरा दोनों रेंडरर को एक ही लक्ष्य देती है?

नए साझा नोट के लिए, ऐसे विशिष्ट शीर्षक नाम चुनें जो लोअरकेस ASCII अक्षरों से बने हों; जहाँ संभव हो, एक ही शब्द रखें। लंबे नामों के लिए desk-layout जैसा रूप उपयोगी है: दिखने वाला शीर्षक-पाठ पहले से ही GitHub-शैली के फ़्रैगमेंट से मेल खाता है।

यह दस्तावेज़ीकृत नियमों से निकली परंपरा है, कोई अलग संगतता सुविधा नहीं। setup में किसी भी रेंडरर के लिए अलग तरह से समझने हेतु रिक्त स्थान, बड़े अक्षर या फ़ॉर्मैटिंग नहीं हैं। दिखने वाले शीर्षक और गंतव्य की तुलना करना आसान रहता है।

फ़ाइल में शीर्षक Obsidian शीर्षक-पाठ गंतव्य, URL-एन्कोड किया हुआ GitHub द्वारा बनाया गया गंतव्य
## setup #setup #setup
## desk-layout #desk-layout #desk-layout
## Desk Layout #Desk%20Layout #desk-layout

तालिका Obsidian के शीर्षक-पाठ और URL-एन्कोडिंग संबंधी निर्देश और GitHub एंकर नियमों पर आधारित है। इसमें यह मानकर नहीं चला गया है कि Obsidian GitHub के सामान्यीकृत हर फ़्रैगमेंट को स्वीकार करता है।

इसका एक दिखने वाला समझौता है: desk-layout पारंपरिक सेक्शन शीर्षक के बजाय किसी पहचानकर्ता जैसा अधिक लगता है। अगर स्वाभाविक शीर्षक अधिक मायने रखते हैं, तो उन्हें बनाए रखें और दोनों ऐप्लिकेशन में बने लिंक जाँचें। पाठकों के लिए कौन-सा समझौता बेहतर है, यह तय करने से पहले पूरे दस्तावेज़ का नाम न बदलें।

आज़माने के लिए एक पूरा नोट

desk-notes.md नाम का नोट बनाएँ और उसमें नीचे दिया Markdown पेस्ट करें। यह कृत्रिम सामग्री वाला एक पूरा नमूना दस्तावेज़ है; फ़ेंस केवल स्रोत दिखाने के लिए है।

Desk notes

Jump to [setup](#setup), [materials](#materials), or
[desk layout](#desk-layout).

## setup

Place the notebook beside the keyboard.

## materials

Use a notebook, a pencil, and a desk tray.

## desk-layout

Keep the tray beside the notebook.

Return to [setup](#setup).

ध्यान दें कि लिंक लेबल में सामान्य रिक्त स्थान हो सकते हैं: [desk layout](#desk-layout) गंतव्य को जस का तस रखते हुए पठनीय टेक्स्ट दिखाता है। हर नेविगेशन लेबल को शीर्षक पहचानकर्ता जैसा बनाने की ज़रूरत नहीं है।

किसी वास्तविक नोट में, सेक्शन में इतनी सामग्री रखें कि नेविगेशन का असर दिखाई दे। बहुत छोटे दस्तावेज़ में सफल जंप से बहुत कम बदलाव दिख सकता है, क्योंकि पूरा नोट पहले से ही विंडो में समा जाता है।

Mac पर Obsidian को कैसे कॉन्फ़िगर और जाँचें?

पहले नोट की जाँच करें, फिर यह तय करें कि Obsidian आगे के लिंक कैसे बनाएगा। ये अलग-अलग जाँचें हैं: लिंक बनाने की प्राथमिकता बदलने से पहले से मौजूद Markdown की जाँच करने की ज़रूरत खत्म नहीं होती।

  1. साइडबार से Settings खोलें।
  2. Files and links के अंतर्गत, Use Wikilinks बंद करें ताकि बनाए गए लिंक Markdown सिंटैक्स इस्तेमाल करें।
  3. साझा फ़ाइलों के बीच लिंक के लिए New link format को Relative path to file पर सेट करें।
  4. नई सेटिंग पर निर्भर होने से पहले मौजूदा गंतव्यों की जाँच करें।

Obsidian डेस्कटॉप सेटिंग तक पहुँचने का तरीका और लिंक बनाने की दोनों प्राथमिकताएँ Settings में बताता है। यहाँ रिलेटिव पाथ उपयोगी विकल्प है, क्योंकि इससे साझा फ़ोल्डर संरचना स्पष्ट रहती है।

नमूना नोट को Command+E से Reading view में बदलें, फिर हर नेविगेशन लिंक पर क्लिक करें। Obsidian macOS के लिए इस शॉर्टकट का दस्तावेज़ देता है और बताता है कि रीडिंग व्यू Markdown सिंटैक्स छिपाता है। नेविगेशन की बार-बार होने वाली जाँच के लिए इसी व्यू का उपयोग करें, ताकि संपादन के हावभाव और नेविगेशन परीक्षण आपस में न मिलें। Views and editing mode देखें।

इसके बाद GitHub पर रेंडर की गई फ़ाइल देखें। किसी शीर्षक पर माउस ले जाकर उसके लिंक आइकन पर क्लिक करें, ताकि वास्तविक फ़्रैगमेंट देखा जा सके। उस फ़्रैगमेंट की तुलना अपने स्रोत लिंक में # के बाद के टेक्स्ट से करें। GitHub यह जाँचने का तरीका Section links में बताता है।

एक छोटी स्वीकृति-जाँच सूची अपनाएँ: लिंक, लिंक के रूप में दिखाई दे; इच्छित फ़ाइल चुने; और इच्छित शीर्षक तक पहुँचे। एक साथ कई शीर्षक बदलने के बजाय, विफलताओं को गंतव्य के अनुसार दर्ज करें। इससे पता लगाना आसान होता है कि सुधार फ़ाइलनाम, पाथ या फ़्रैगमेंट में से किसके लिए काम आया।

किसी दूसरी फ़ाइल के शीर्षक का लिंक कैसे दें?

पहला उदाहरण सरल रखें: दो फ़ाइलें एक-दूसरे के बगल में रखें। desk-notes.md वाले फ़ोल्डर में index.md बनाएँ, फिर उसमें यह पूरी सामग्री डालें:

Desk index

Read the [setup notes](desk-notes.md#setup).

Review the [desk layout](desk-notes.md#desk-layout).

गंतव्य के दो हिस्से हैं: desk-notes.md फ़ाइल चुनता है और #setup सेक्शन चुनता है। GitHub रिलेटिव फ़ाइल लिंक को मौजूदा फ़ाइल के स्थान के सापेक्ष हल करता है; Obsidian रिलेटिव पाथ बनाने की सेटिंग देता है। दस्तावेज़ीकृत ये व्यवहार इसी फ़ोल्डर में फ़ाइलें रखने की व्यवस्था के लिए उपयुक्त हैं। GitHub रिलेटिव लिंक और Obsidian लिंक सेटिंग देखें।

इन दस्तावेज़ों को जहाँ भी पढ़ें, फ़ाइलों की यही रिलेटिव व्यवस्था बनाए रखें। अगर आप केवल index.md को किसी सबफ़ोल्डर में ले जाते हैं, तो उसका मौजूदा सहोदर फ़ाइल वाला गंतव्य आपकी नई व्यवस्था का वर्णन नहीं करेगा। शीर्षक की जाँच करने से पहले पाथ फिर से तय करें।

साझा फ़ाइल लिंक में .md एक्सटेंशन स्पष्ट रूप से रखें। रिक्त स्थान वाले फ़ाइलनामों के लिए, Markdown गंतव्यों में Obsidian के URL-एन्कोडिंग निर्देश के अनुसार %20 इस्तेमाल करें। रिक्त स्थान एन्कोड करने से वह रिक्त स्थान बना रहता है; इससे शीर्षक GitHub के हाइफ़न वाले एंकर में नहीं बदलता।

मौजूदा शीर्षकों और टूटे लिंक के साथ क्या करें?

प्लगइन या अतिरिक्त एंकर तरीके अपनाने से पहले यह निदान क्रम आज़माएँ। इससे दस्तावेज़ के सबसे छोटे विफल हिस्से का पता चलता है।

  1. शीर्षक का स्रोत जाँचें। पुष्टि करें कि लक्ष्य वास्तव में Markdown शीर्षक है, जैसे ## setup, और शुरुआती हैश के बाद रिक्त स्थान है। टेक्स्ट वाले शीर्षक के लिए CommonMark इस रिक्त स्थान की माँग करता है। ATX शीर्षक देखें।
  2. लिंक सिंटैक्स जाँचें। [setup](#setup) इस्तेमाल करें। बंद करने वाला वर्गाकार ब्रैकेट खुलते कोष्ठक के ठीक पास रखें; CommonMark लिंक नियमों के अनुसार [setup] (#setup) इनलाइन लिंक नहीं है।
  3. फ़ाइल का समाधान और सेक्शन का समाधान अलग-अलग जाँचें। किसी दूसरी फ़ाइल का लिंक काम न करे, तो फ़्रैगमेंट हटाकर फ़ाइल का लिंक अस्थायी रूप से जाँचें। अगर वह विफल हो, तो पहले पाथ ठीक करें।
  4. शीर्षक-पाठ की तुलना फ़्रैगमेंट से करें। Desk Layout जैसे स्वाभाविक शीर्षक के लिए ऊपर रेंडरर तुलना देखें। %20 को - में बदलने से लक्ष्य तय करने का तरीका बदलता है।
  5. दोहराए गए लक्ष्यों की जाँच करें। notebook-setup और tray-setup जैसे अलग नाम चुनें। GitHub के संख्यात्मक प्रत्यय डुप्लिकेट एंकरों के क्रम पर निर्भर करते हैं, इसलिए क्रम बदलने पर गंतव्य बदल सकते हैं। GitHub सेक्शन लिंक देखें।

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

जब भी आप कोई शीर्षक बदलें, उस सेक्शन की ओर आने वाले लिंक फिर से जाँचें। Obsidian की Automatically update internal links सेटिंग फ़ाइल का नाम बदलने पर लिंक अपडेट होने का वर्णन करती है; केवल इस विवरण से यह साबित नहीं होता कि शीर्षक संपादित करने पर उसके आने वाले हर लिंक अपने-आप ठीक हो जाएँगे। Obsidian की सेटिंग का विवरण देखें।

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

स्रोत