फ़ोल्डर मेटा

अपने पेजों के साथ एक meta.ts फ़ाइल रखकर साइडबार समूह कॉन्फ़िगर करें — समूह का शीर्षक, आइकन, क्रम, और उसमें नेस्टेड पेजों का क्रम सेट करें।

आपके कंटेंट ट्री का हर फ़ोल्डर एक साइडबार समूह बन जाता है। उस समूह की दिखावट और उसके चिल्ड्रन के क्रम को नियंत्रित करने के लिए उसके पेजों के साथ एक meta.ts रखें। यह पूरी तरह वैकल्पिक है: इसके बिना, समूह का लेबल फ़ोल्डर का ह्यूमनाइज़्ड नाम होता है और उसके पेज index, न्यूमेरिक प्रीफ़िक्स, फिर वर्णानुक्रम के अनुसार क्रमबद्ध होते हैं।

मेटा परिभाषित करना

पूरी तरह टाइप किए गए कॉन्फ़िग के लिए एक defineMeta ऑब्जेक्ट एक्सपोर्ट करें। फ़ाइल को उस फ़ोल्डर की जड़ में रखें जिसे वह कॉन्फ़िगर करती है — guides/meta.ts Guides समूह को कॉन्फ़िगर करती है:

import { defineMeta } from "blume";

export default defineMeta({
  title: "Guides",
  icon: "book-open",
  order: 2,
  collapsed: false,
  pages: ["configuration", "theming", "deployment"],
});

हर फ़ील्ड वैकल्पिक है — केवल वही सेट करें जिसे आप ओवरराइड करना चाहते हैं।

Blume केवल उन्हीं फ़ोल्डरों से meta.ts फ़ाइलें पढ़ता है जिन्हें आपका कंटेंट कवर करता है: जो फ़ाइल किसी ऐसे फ़ोल्डर के अंतर्गत हो जिसे आपके कंटेंट के exclude ग्लोब छोड़ देते हैं, या जो हर include ग्लोब से बाहर हो, वह कभी इम्पोर्ट नहीं की जाती। root: "." और exclude: ["src/**"] के साथ, एक असंबंधित src/lib/meta.ts को अनछुआ छोड़ दिया जाता है।

हर include ग्लोब से बाहर की meta.ts तब भी अनदेखी की जाती है जब उसका फ़ोल्डर एक साइडबार समूह हो, जैसे किसी ऐसी साइट पर किसी रेफ़रेंस का टैग फ़ोल्डर जिसकी include केवल guides/** को सूचीबद्ध करती है। Blume ऐसी फ़ाइल के बारे में BLUME_META_OUTSIDE_INCLUDE के रूप में चेतावनी देता है: एक ऐसा include ग्लोब जोड़ें जो उस फ़ोल्डर तक पहुँचता हो, जैसे "api/**/*.{md,mdx}", ताकि Blume उसे पढ़ सके।

फ़ील्ड

pages सरणी चिल्ड्रन को स्लग के अनुसार सूचीबद्ध करती है — फ़ोल्डर या फ़ाइल का नाम, जिसमें से न्यूमेरिक प्रीफ़िक्स और कोई भी कोष्ठक हटा दिए गए हों (इसलिए 01-quickstart.mdx का स्लग "quickstart" है)। हर सूचीबद्ध चाइल्ड सरणी में अपनी स्थिति को अपने क्रम के रूप में लेता है (0, 1, 2, …)। जिन चिल्ड्रन को आप छोड़ देते हैं, वे फिर भी दिखते हैं और अपने स्वयं के क्रम के अनुसार क्रमबद्ध होते हैं: एक index पेज पहले ही रहता है, जिस चाइल्ड का sidebar.order, न्यूमेरिक प्रीफ़िक्स, या उसकी अपनी meta.ts का order हो, वह सूचीबद्ध वालों के बीच उसी संख्या के अनुसार क्रमबद्ध होता है, और जिस चाइल्ड के पास इनमें से कुछ भी न हो, वह उनके बाद आता है। जब सरणी को ही पूरा क्रम होना चाहिए, तो हर चाइल्ड को सूचीबद्ध करें। जो प्रविष्टि समूह के किसी भी पेज या फ़ोल्डर का नाम नहीं देती, वह किसी चीज़ को क्रमबद्ध नहीं करती, इसलिए Blume meta.ts में उसकी पंक्ति पर BLUME_META_UNKNOWN_PAGE के रूप में उसके बारे में चेतावनी देता है, और उस स्लग का सुझाव देता है जो सबसे संभवतः अभिप्रेत है।

यह सरणी पेजों को पेजों के बीच और समूहों को समूहों के बीच क्रमबद्ध करती है, लेकिन जहाँ स्वतंत्र पेज समूहों के ऊपर सूचीबद्ध होते हैं, वहाँ यह दोनों को आपस में नहीं मिलाती: साइडबार के शीर्ष पर (और प्रत्येक टैब सेक्शन के शीर्ष पर), और किसी भी ऐसे समूह में जिसमें एक flat उपसमूह हो, जिसका हेडर अन्यथा अपने बाद आने वाले पेजों का स्वामी प्रतीत होता। वहाँ, pages: ["advanced", "intro"] होने पर भी intro पेज advanced समूह के ऊपर ही सूचीबद्ध होता है।

समूह कैसे रेंडर होते हैं — फ़्लैट हेडर, संकुचित होने वाले डिस्क्लोज़र, या ड्रिल-इन पैनल — यह डिफ़ॉल्ट रूप से पूरे साइडबार के navigation.sidebar.display से तय होता है; केवल इस समूह के लिए इसे ओवरराइड करने हेतु यहाँ display सेट करें। किसी फ़ोल्डर का index पेज इसे फ्रंटमैटर से भी सेट कर सकता है, जो meta.ts पर भारी पड़ता है — देखें प्रति-समूह ओवरराइड्स।

जनरेट किए गए समूह

एक OpenAPI, AsyncAPI, या GraphQL रेफ़रेंस अपने टैग समूहों के नाम और क्रम स्पेक से तय करता है। किसी एक को बदलने के लिए, उस फ़ोल्डर में एक meta.ts जोड़ें जिसके अंतर्गत टैग के पेज प्रकाशित होते हैं: रेफ़रेंस /api पर होने पर, आपके कंटेंट फ़ोल्डर में api/pets/meta.ts Pets समूह को कॉन्फ़िगर करती है। यह जो फ़ील्ड सेट करती है, वे जनरेट किए गए फ़ील्ड्स की जगह ले लेते हैं, और बाकी फ़ील्ड अपने जनरेट किए गए मान बनाए रखते हैं, इसलिए केवल title सेट करने वाली meta.ts स्पेक के क्रम में टैग का स्थान बनाए रखती है।

कंप्यूटेड मेटा

चूँकि meta.ts एक वास्तविक मॉड्यूल है, आप मेटा की गणना कर सकते हैं — स्कैन के समय इसे बनाने के लिए ऑब्जेक्ट के बजाय एक फ़ंक्शन (सिंक या async) पास करें। किसी बाहरी स्रोत से पेजों को क्रमबद्ध करने के लिए उपयोगी:

import { defineMeta } from "blume";

export default defineMeta(async () => ({
  title: "Guides",
  pages: await orderFromCms(),
}));

समूह के भीतर क्रम

pages सरणी किसी समूह के चिल्ड्रन का क्रम तय करती है, और यह किसी सूचीबद्ध पेज के अपने sidebar.order या किसी सूचीबद्ध सबफ़ोल्डर के अपने order पर भारी पड़ती है। जो कुछ भी यह छोड़ देती है, वह प्रत्येक पेज के फ्रंटमैटर sidebar.order पर वापस चला जाता है, फिर फ़ाइल सिस्टम पर (पहले एक index पेज, फिर न्यूमेरिक प्रीफ़िक्स, फिर वर्णानुक्रम)। पूर्ण साइडबार प्राथमिकता क्रम के लिए — जिसमें स्पष्ट कॉन्फ़िग साइडबार भी शामिल है — देखें नेविगेशन › क्रम।

URL सेगमेंट जोड़े बिना पेजों को समूहबद्ध करने के लिए, आपको meta.ts की ज़रूरत ही नहीं है: कोष्ठक वाले फ़ोल्डर नाम का उपयोग करें — देखें पेज › समूह फ़ोल्डर।

अंतर्राष्ट्रीयकरण

i18n के तहत, फ़ोल्डर मेटा प्रति लोकेल रिज़ॉल्व होता है: फ़्रेंच समूह को स्वतंत्र रूप से क्रमबद्ध करने के लिए fr/guides/ के अंतर्गत एक meta.ts रखें। इसके बिना (या नीचे बताई गई साझा meta.$.ts के बिना), फ़्रेंच समूह फ़ॉलबैक लोकेल की meta.ts को प्रतिबिंबित करता है।

ऐसे फ़ोल्डर मेटा के लिए जो हर भाषा में समान है, एक $ मार्कर जोड़ें ताकि एक ही फ़ाइल बिना डुप्लिकेशन के सभी लोकेल्स के लिए काम करे:

docs/guides/meta.$.ts   (folder meta applied to every locale)

किसी विशिष्ट लोकेल का meta.ts उस भाषा के लिए साझा meta.$.ts को फिर भी ओवरराइड करता है।

आगे कहाँ जाएँ