इनक्लूड

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

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

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

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

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

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

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

पार्शियल्स

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

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

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

पार्शियल के भीतर सापेक्ष छवि संदर्भ काम करते रहते हैं: उन्हें इनक्लूड करने वाले पृष्ठ के अनुसार पुनः आधारित किया जाता है, इसलिए पार्शियल के साथ रखी गई ![आरेख](./diagram.png) वहाँ भी हल हो जाती है जहाँ भी पार्शियल जोड़ा जाए।

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

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

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

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

<include lang="ts" meta='title="blume.config.ts"'>
  ../blume.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 में दिखाई देते हैं।

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