इनक्लूड

पृष्ठों के बीच सामग्री का पुनः उपयोग करें — साझा Markdown, MDX या कोड फ़ाइलों को include सिंटैक्स के साथ किसी भी पृष्ठ में जोड़ें।

एक स्निपेट एक बार लिखें और उसे किसी भी पृष्ठ में जोड़ दें। अपनी स्वयं की पंक्ति पर लिखा गया <include> कथन बिल्ड समय पर किसी दूसरी फ़ाइल को इस प्रकार एम्बेड करता है, मानो उसकी सामग्री इनलाइन लिखी गई हो — शीर्षक पृष्ठ की विषय-सूची में जुड़ जाते हैं, पाठ खोज द्वारा अनुक्रमित होता है, और सामग्री पृष्ठ के .md मिरर तथा llms-full.txt में दिखाई देती है। यदि कोई फ़ॉर्मैटर किसी कथन को कई पंक्तियों में तोड़ देता है, तब भी वह जुड़ जाता है। जिस कथन को Blume पार्स नहीं कर पाता, वह कच्चे टैग के रूप में रेंडर नहीं होता। इसके बजाय वह अपनी पंक्ति पर BLUME_INCLUDE_MALFORMED चेतावनी देता है।

<include>./_snippets/prerequisites.mdx</include>

पथ को इनक्लूड करने वाली फ़ाइल के सापेक्ष हल किया जाता है। / से आरंभ होने वाले पथ आपके कंटेंट रूट से हल होते हैं, जिससे गहराई में नेस्ट किए गए पृष्ठ ../../.. की श्रृंखलाओं के बिना साझा स्निपेट्स का संदर्भ ले सकते हैं:

<include>/_snippets/prerequisites.mdx</include>

यह सिंटैक्स Fumadocs के include सिंटैक्स से मेल खाता है, इसलिए माइग्रेट की गई सामग्री बिना किसी बदलाव के काम करती है।

यह रहा इसका जीवंत उदाहरण — नीचे दिया गया यह कॉलआउट एक साझा स्निपेट से जोड़ा गया है:

पार्शियल्स

ऐसी कोई भी फ़ाइल जिसका नाम (या फ़ोल्डर) अंडरस्कोर से आरंभ होता है, रूटिंग, नेविगेशन, खोज और साइटमैप से बाहर रखी जाती है — यही परिपाटी साझा स्निपेट्स के लिए स्वाभाविक स्थान है। आप content.exclude में जो पैटर्न जोड़ते हैं, वे इस नियम को प्रतिस्थापित नहीं करते बल्कि इसमें जुड़ जाते हैं। फिर भी अंडरस्कोर वाली फ़ाइलें प्रकाशित करने के लिए exclude में "!**/_*" जोड़ें:

docs/
  _snippets/
    prerequisites.mdx
    cli-flags.md
  guides/
    quickstart.mdx   ← <include>../_snippets/prerequisites.mdx</include>
  index.mdx

पार्शियल एक सामान्य Markdown या MDX फ़ाइल होती है। जोड़े जाने पर उसका फ़्रंट मैटर हटा दिया जाता है (इनक्लूड करने वाले पृष्ठ का फ़्रंट मैटर मान्य होता है), और शेष सब कुछ — कॉलआउट, कोड फ़ेंस, कंपोनेंट, गणितीय व्यंजक — ठीक वैसे ही रेंडर होता है जैसे इनलाइन होने पर होता। पार्शियल्स अन्य पार्शियल्स को इनक्लूड कर सकते हैं; चक्रीय इनक्लूड को त्रुटि के रूप में रिपोर्ट किया जाता है।

लिंक संदर्भ परिभाषाएँ ([pep 508]: https://peps.python.org/pep-0508/) भी इनक्लूड्स के पार काम करती हैं, इसलिए कोई पार्शियल साइट की साझा लिंक परिभाषाएँ रख सकता है: पृष्ठ और उसके अन्य पार्शियल्स किसी पार्शियल की परिभाषा का संदर्भ ([PEP 508]) दे सकते हैं, और कोई पार्शियल पृष्ठ की परिभाषा का संदर्भ दे सकता है। जब पृष्ठ और कोई पार्शियल दोनों एक ही लेबल परिभाषित करते हैं, तो प्रत्येक अपनी स्वयं की परिभाषा का उपयोग करता है।

पार्शियल के भीतर सापेक्ष छवि संदर्भ काम करते रहते हैं: उन्हें इनक्लूड करने वाले पृष्ठ के अनुसार पुनः आधारित किया जाता है, इसलिए पार्शियल के साथ रखी गई ![diagram](./diagram.png) या <Card img="./cover.png"> वहाँ भी हल हो जाती है जहाँ भी पार्शियल जोड़ा जाए। किसी छवि का पथ चाहे जिस भी रूप में लिखा गया हो, उसे पुनः आधारित किया जाता है: कोण कोष्ठकों में (![diagram](<./my diagram.png>)), एस्केप किए गए कोष्ठकों के साथ, या किसी भी प्रकार के उद्धरण चिह्नों में लिखे शीर्षक के साथ। पार्शियल के साथ रखी किसी अन्य फ़ाइल का लिंक ([spec](./spec.pdf), या उसे इंगित करने वाला <img src> या <a href>) भी पार्शियल के साथ स्थानांतरित होता है। किसी पृष्ठ का लिंक इनक्लूड करने वाले पृष्ठ से हल होता है, मानो वह वहीं लिखा गया हो।

blume dev के चलते समय किसी पार्शियल का संपादन उन सभी पृष्ठों को पुनः लोड कर देता है जो उसे इनक्लूड करते हैं।

प्रॉप्स

किसी पार्शियल में मान एट्रिब्यूट्स के रूप में पास करें, और पार्शियल के भीतर उन्हें {{name}} के साथ पढ़ें — यह वही सिंटैक्स है जो वेरिएबल्स के लिए उपयोग होता है। इस प्रकार एक ही पार्शियल उन सभी पृष्ठों के काम आता है जिन्हें उसके किसी भिन्न रूप की आवश्यकता होती है:

Upgrade to the **{{plan}}** plan to use {{feature}}.

<include plan="Enterprise" feature="SSO">
  ./_snippets/upgrade.mdx
</include>

प्रॉप इनक्लूड की गई फ़ाइल पर लागू होता है और उन सभी फ़ाइलों पर भी जिन्हें वह आगे इनक्लूड करती है, तथा समान नाम वाले साइट-व्यापी वेरिएबल पर प्राथमिकता रखता है। lang और meta को छोड़कर प्रत्येक एट्रिब्यूट एक प्रॉप है; एट्रिब्यूट नाम लोअरकेस में होते हैं, और मान उद्धरण चिह्नों में लिखा गया सादा पाठ होते हैं। प्रॉप्स केवल Markdown और MDX पार्शियल्स तक पहुँचते हैं: इनक्लूड की गई किसी कोड फ़ाइल में मौजूद {{name}} को प्रॉप द्वारा प्रतिस्थापित नहीं किया जाता।

कोड फ़ाइलें इनक्लूड करना

ऐसा लक्ष्य जो .md/.mdx नहीं है, उसे फ़ेंस्ड कोड ब्लॉक के रूप में एम्बेड किया जाता है, जिसमें भाषा का अनुमान एक्सटेंशन से लगाया जाता है। भाषा को ओवरराइड करने के लिए (या किसी Markdown फ़ाइल को जोड़ने के बजाय स्रोत के रूप में दिखाने के लिए) lang का उपयोग करें, और शीर्षक जैसी फ़ेंस मेटा स्ट्रिंग पास करने के लिए meta का:

<include>./examples/config.ts</include>

<include meta='title="config.ts"'>./examples/config.ts</include>

<include lang="mdx">./_snippets/prerequisites.mdx</include>

नियम और डायग्नोस्टिक्स

इनक्लूड कथनों को अपनी स्वयं की पंक्ति पर होना चाहिए — वे ब्लॉक-स्तरीय होते हैं, इनलाइन नहीं। फ़ेंस्ड कोड ब्लॉक के भीतर मौजूद कथनों को अछूता छोड़ दिया जाता है, इसलिए आप स्वयं इस सिंटैक्स का दस्तावेज़ीकरण कर सकते हैं (जैसा यह पृष्ठ करता है)।

लक्ष्य आपके कंटेंट रूट के भीतर होने चाहिए: उसके बाहर की कोई फ़ाइल संस्करण स्नैपशॉट्स और इजेक्ट किए गए प्रोजेक्ट्स से चुपचाप अनुपस्थित हो जाएगी, इसलिए blume उसे जोड़ने के बजाय BLUME_INCLUDE_OUTSIDE_ROOT रिपोर्ट करता है। जो लक्ष्य मौजूद ही नहीं है वह BLUME_INCLUDE_NOT_FOUND है, और इनक्लूड्स का चक्र BLUME_INCLUDE_CYCLE है — तीनों blume build को विफल कर देते हैं (फिर भी बिल्ड करने के लिए --no-strict पास करें) और blume validate में दिखाई देते हैं।

किसी पार्शियल के भीतर टूटे हुए लिंक उस पार्शियल फ़ाइल के विरुद्ध रिपोर्ट किए जाते हैं, न कि उन पृष्ठों के विरुद्ध जो उसे जोड़ते हैं, ताकि आप उन्हें वहीं ठीक करें जहाँ वे मौजूद हैं।

पार्शियल को इनक्लूड करने वाले पृष्ठ के फ़ॉर्मैट में पढ़ा जाता है, इसलिए जिस .md पार्शियल को कोई .mdx पृष्ठ इनक्लूड करता है, उसे MDX के रूप में पढ़ा जाता है। MDX में HTML टिप्पणियाँ नहीं होतीं, इसलिए पार्शियल की <!-- … --> टिप्पणियाँ MDX टिप्पणियों ({/* … */}) के रूप में जोड़ी जाती हैं और छिपी रहती हैं। वहाँ मौजूद अन्य HTML का मान्य JSX होना आवश्यक है: समापन स्लैश के बिना लिखा गया <img …> या <br> पार्शियल में अपने बाद की सारी सामग्री को अपने भीतर ले लेता है, और कोई त्रुटि नहीं दिखाई जाती। Blume इसके लिए पार्शियल की संबंधित पंक्ति पर BLUME_MDX_UNCLOSED_ELEMENT चेतावनी देता है; इसे <br /> के रूप में बंद करें। जोड़े जाने के बाद पार्शियल में कोई अन्य सामग्री, जैसे कोई अकेला {, MDX पार्स नहीं कर पाता, तो पार्शियल की संबंधित पंक्ति पर BLUME_MDX_SYNTAX चेतावनी मिलती है। जब यह त्रुटि बिल्ड को विफल करती है, तो बिल्ड भी उसे वहीं रिपोर्ट करता है, न कि उस पृष्ठ पर जो पार्शियल को इनक्लूड करता है।