नेविगेशन

Blume आपकी फ़ाइलों से साइडबार बनाता है, फिर आपको फ्रंटमैटर, फ़ोल्डर मेटा, या कॉन्फ़िग से उसे परिष्कृत करने देता है — ब्रेडक्रंब और आउटलाइन साथ-साथ चलते हैं।

Blume फ़ाइल सिस्टम से आपका साइडबार बनाता है, फिर आपको उसे जितना चाहें — या जितना कम चाहें — परिष्कृत करने देता है: पेज दर पेज, फ़ोल्डर दर फ़ोल्डर, या एक स्पष्ट कॉन्फ़िग के साथ। ब्रेडक्रंब, पिछला/अगला लिंक, और पेज पर मौजूद आउटलाइन सभी उसी मॉडल से निकलते हैं, कुछ भी जोड़ने की ज़रूरत नहीं।

डिफ़ॉल्ट रूप से साइडबार आपके कंटेंट ट्री का प्रतिबिंब होता है:

फ़ोल्डर समूह बन जाते हैं, फ़ाइलें पेज बन जाती हैं
एक पेज का लेबल उसका फ्रंटमैटर title होता है; एक समूह का लेबल मानव-पठनीय बनाया गया फ़ोल्डर नाम होता है
आइटम संख्यात्मक उपसर्ग के अनुसार क्रमबद्ध होते हैं, फिर वर्णानुक्रम में, और एक फ़ोल्डर का index पेज सबसे पहले आता है
जिस फ़ोल्डर में index पेज होता है, उसकी समूह पंक्ति उसी पेज से लिंक हो जाती है, इसलिए अनुभाग के नाम पर क्लिक करने से अनुभाग का लैंडिंग पेज खुलता है

कई साइटों के लिए इतना ही काफ़ी है — नीचे दी गई हर चीज़ वैकल्पिक है।

पेज लेबल, आइकन, और बैज

एक ही पेज साइडबार में कैसे दिखे, इसे उसके फ्रंटमैटर में sidebar के अंतर्गत समायोजित करें:

sidebar:
  label: Quickstart # override the title in the sidebar
  icon: rocket # an icon from Blume's built-in set
  badge: New # a small label beside the entry
  order: 1 # sort position within its group

पूरे पेज स्कीमा के लिए फ्रंटमैटर देखें।

फ़ोल्डर समूह

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

import { defineMeta } from "blume";

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

हर फ़ील्ड और स्कैन के समय मेटा की गणना करने के लिए फ़ोल्डर मेटा देखें।

एक फ़ोल्डर का meta.title और उसके अपने index पेज का फ्रंटमैटर title स्वतंत्र रूप से हल किए जाते हैं — i18n के अंतर्गत एक का अनुवाद करना और दूसरे को भूल जाना एक सही साइडबार दिखाता है, लेकिन लैंडिंग पेज पर ही पुराना <title>/शीर्षक रह जाता है। जब ये अलग हो जाते हैं तो Blume एक BLUME_NAV_INDEX_TITLE_MISMATCH चेतावनी देता है। फ़ॉलबैक लोकेल से भरे गए अअनुवादित पेज इससे मुक्त हैं — उनका शीर्षक फ़ॉलबैक लोकेल का है, और समाधान पेज का अनुवाद करना है, उसका फ्रंटमैटर संपादित करना नहीं।

URL सेगमेंट जोड़े बिना पेजों को समूहबद्ध करने के लिए, कोष्ठक वाले फ़ोल्डर नाम का उपयोग करें — देखें पेज।

डिस्प्ले मोड

navigation.sidebar.display तय करता है कि हर साइडबार समूह कैसे रेंडर हो:

navigation: {
  sidebar: {
    display: "flat", // "flat" | "group" | "page"
  },
}

flat (डिफ़ॉल्ट) — एक ऐसा हेडर जो संकुचित नहीं होता, जिसके नीचे उसके पेज सूचीबद्ध होते हैं। जो पेज किसी समूह में नहीं हैं वे हमेशा पहले, समूह अनुभागों के ऊपर सूचीबद्ध होते हैं, ताकि उन्हें किसी समूह के चाइल्ड आइटम न समझा जाए।
group — प्रति समूह एक संकुचित होने वाला <details> प्रकटीकरण। समूह डिफ़ॉल्ट रूप से संकुचित अवस्था में शुरू होते हैं; वर्तमान पेज वाला समूह हमेशा खुला शुरू होता है, ताकि केवल वही अनुभाग विस्तृत हो जिसमें आप हैं। किसी समूह को हर हाल में खुला रखने के लिए फ़ोल्डर मेटा में collapsed: false सेट करें।
page — हर समूह एक ही पंक्ति होती है, जिस पर क्लिक करने से साइडबार एक उप-पैनल में सरक जाता है जिसमें केवल उस समूह के आइटम दिखते हैं, और ऊपर एक पीछे जाने वाला तीर होता है। यह पैनल रूट-अवेयर है, इसलिए समूह के अंदर किसी पेज पर सीधे पहुँचने पर वह सीधे उसी पर खुलता है।

group और page दोनों मोड में, जो अनुभाग वर्तमान पेज पर खुला नहीं है, उसे उस पेज के HTML से बाहर रखा जाता है और पहली बार खोले जाने पर फ़ेच किया जाता है (जैसे ही पॉइंटर या फ़ोकस उसकी पंक्ति तक पहुँचता है, उसे पहले से फ़ेच कर लिया जाता है, इसलिए वह आमतौर पर तुरंत खुलता है, और एक बार फ़ेच किया गया अनुभाग विज़िट के शेष समय तक रखा जाता है)। एक बड़ी साइट पर यही किसी पेज के भार का अधिकांश हिस्सा होता है: केवल खुले अनुभाग की पंक्तियाँ ही पेज के साथ भेजी जाती हैं। ये पंक्तियाँ /blume-nav/ के अंतर्गत प्रीरेंडर किए गए फ़्रैगमेंट हैं, इसलिए इन्हें किसी सर्वर की ज़रूरत नहीं होती। JavaScript के बिना पाठक खुला अनुभाग और समूह पंक्तियाँ देखते हैं; साइटमैप, पिछला/अगला लिंक, और खुला अनुभाग क्रॉलर के लिए हर पेज को पहुँच योग्य बनाए रखते हैं।

प्रति-समूह ओवरराइड

जेनरेट किया गया कोई भी समूह ग्लोबल मोड से बाहर निकल सकता है — इसके लिए किसी स्पष्ट साइडबार की ज़रूरत नहीं। फ़ोल्डर के meta.ts में display सेट करें, या — जब फ़ोल्डर में कोई index पेज हो — उस पेज के फ्रंटमैटर में sidebar के अंतर्गत, और केवल वही समूह बदलता है:

import { defineMeta } from "blume";

export default defineMeta({
  title: "Client SDKs",
  display: "page",
});

---
title: Client SDKs
sidebar:
  display: page
---

जेनरेट किए गए किसी समूह का प्रभावी मोड सबसे उच्च प्राथमिकता से हल किया जाता है:

समूह के अपने index पेज के फ्रंटमैटर में sidebar.display
फ़ोल्डर के meta.ts में display
ग्लोबल navigation.sidebar.display
Blume का डिफ़ॉल्ट (flat)

किसी समूह का display केवल उसी समूह पर लागू होता है — नेस्टेड उपसमूह अपना स्वयं का मान इसी शृंखला के माध्यम से हल करते हैं। इंडेक्स पेज वाला page-मोड समूह फिर भी अपने उप-पैनल में गहराई तक जाता है: इंडेक्स पेज पैनल के पहले आइटम के रूप में सूचीबद्ध होता है, और उसके URL पर पहुँचने पर पैनल सीधे खुल जाता है।

sidebar.display का कहीं और कोई अर्थ नहीं है — किसी गैर-इंडेक्स पेज पर, कंटेंट रूट के अपने index पेज पर (रूट कोई समूह नहीं है; navigation.sidebar.display का उपयोग करें), या किसी भी पेज पर जब एक स्पष्ट साइडबार कॉन्फ़िगर किया गया हो (उसके आइटम हर समूह के मोड के स्वामी होते हैं) — इसलिए Blume उसे चुपचाप छोड़ देने के बजाय एक BLUME_SIDEBAR_DISPLAY_IGNORED चेतावनी देता है। collapsed group मोड के लिए विशिष्ट बना रहता है; जब कोई समूह flat या page पर हल होता है तो वह निष्क्रिय रहता है।

एक स्पष्ट साइडबार में मौजूद समूह अपने स्वयं के display से ग्लोबल मोड को ओवरराइड करता है, ठीक पहले की तरह।

क्रम निर्धारण

जब साइडबार जेनरेट होता है, तो क्रम सबसे उच्च प्राथमिकता से हल किया जाता है:

कॉन्फ़िग साइडबार

एक स्पष्ट navigation.sidebar जेनरेट किए गए ट्री को पूरी तरह से बदल देता है।

फ़ोल्डर मेटा

meta.ts में मौजूद pages ऐरे एक समूह को क्रमबद्ध करता है।

फ्रंटमैटर

किसी पेज पर sidebar.order।

फ़ाइल सिस्टम

पहले एक index पेज, फिर संख्यात्मक उपसर्ग, फिर लेबल के अनुसार वर्णानुक्रम।

एक ही स्पष्ट या संख्यात्मक क्रम पर पहुँचने वाले दो सहोदर आपस में वर्णानुक्रम पर लौट आते हैं — Blume एक BLUME_DUPLICATE_SIDEBAR_ORDER चेतावनी देता है ताकि यह टकराव अनदेखा न रह जाए।

छिपे हुए पेज

किसी पेज को साइडबार से — और पिछला/अगला पेजिनेशन से — छिपाएँ, जबकि वह बना रहे और अपने URL से पहुँच योग्य रहे:

sidebar:
  hidden: true

किसी फ़ोल्डर का index पेज दोनों जगह दिखता है — समूह पंक्ति के लिंक के रूप में और समूह के भीतर पहली पंक्ति के रूप में। केवल लिंक किया हुआ हेडर रखने के लिए इंडेक्स पेज को छिपाएँ: समूह पंक्ति फिर भी लैंडिंग पेज खोलती है, और पिछला/अगला लिंक फिर भी उससे होकर गुज़रते हैं।

टैब

शीर्ष-स्तरीय अनुभागों को हेडर में टैब के रूप में रेंडर करें, जो एक बड़ी साइट को अलग-अलग क्षेत्रों में बाँटने के लिए उपयोगी है — जैसे अडैप्टर, एक API, और AI गाइड। जब वर्तमान रूट किसी टैब के path के अंतर्गत आता है तो वह टैब हाइलाइट हो जाता है:

navigation: {
  tabs: [
    { label: "Adapters", path: "/adapters", icon: "plug" },
    { label: "API", path: "/api", icon: "rocket" },
    { label: "AI", path: "/ai", icon: "sparkles" },
  ],
}

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

navigation: {
  tabs: [
    { label: "API", path: "/reference" },
  ],
}

एक टैब का path उसका अनुभाग उपसर्ग होता है, और वही लिंक टारगेट का भी काम करता है। जिस अनुभाग का path अपने आप में कोई पेज नहीं है — बिना index.mdx वाला फ़ोल्डर — वह एक 404 पर ले जाता, इसलिए टैब इसके बजाय अनुभाग के पहले पेज पर लौट आता है। जब आप चाहते हैं कि वह कहीं और पहुँचे तो href सेट करें:

navigation: {
  tabs: [
    { label: "Changelog", path: "/changelog", href: "/changelog" },
  ],
}

यह उन रूट्स के लिए मायने रखता है जो कंटेंट ट्री का हिस्सा नहीं हैं, क्योंकि फ़ॉलबैक उन्हें देख नहीं सकता: जेनरेट किया गया चेंजलॉग इंडेक्स, या pages/ के अंतर्गत आपके द्वारा जोड़ा गया कोई कस्टम पेज। href के बिना, एक /changelog टैब इंडेक्स के बजाय सबसे नई प्रविष्टि पर पहुँचता है। जो टैब href सेट नहीं करते, वे अप्रभावित रहते हैं।

एक i18n साइट पर, एक टैब का label (और एक ड्रॉपडाउन आइटम का) स्ट्रिंग के बजाय प्रति-लोकेल मैप हो सकता है — सक्रिय लोकेल की प्रविष्टि जीतती है, फिर डिफ़ॉल्ट लोकेल की:

navigation: {
  tabs: [
    { label: { en: "Docs", fr: "Documentation" }, path: "/docs" },
    { label: "CLI", path: "/cli" }, // a plain string renders as-is everywhere
  ],
}

टैब साइडबार को भी सीमित करते हैं: जब वर्तमान रूट किसी टैब के path के अंतर्गत आता है, तो साइडबार केवल उसी अनुभाग के पेज दिखाता है — इसलिए /adapters/* अडैप्टर सूचीबद्ध करता है और कुछ नहीं। टैब के path पर मौजूद फ़ोल्डर अनुभाग बन जाता है, इसलिए इसके लिए टैब्स के अलावा किसी अतिरिक्त कॉन्फ़िग की ज़रूरत नहीं; अपने कंटेंट को प्रति टैब एक फ़ोल्डर में व्यवस्थित करें और हर टैब को उस पर इंगित करें।

ऐसे रूट पर जो किसी टैब के अंतर्गत नहीं है (या जिस टैब का path / है), साइडबार वे पेज दिखाता है जो किसी टैब से संबंधित नहीं हैं — हर टैब का फ़ोल्डर उससे छिपा रहता है, क्योंकि उस अनुभाग के पास पहले से ही हेडर में अपना टैब है। इसलिए एक रूट लैंडिंग पेज आपके ढीले शीर्ष-स्तरीय पेज सूचीबद्ध करता है जबकि अनुभागों में बँटा कंटेंट अपने टैब के पीछे रहता है, जो Fumadocs के रूट फ़ोल्डरों जैसा है। यदि किसी रूट के पास इस तरह दिखाने के लिए अपने कोई पेज नहीं हैं, तो इसके बजाय पूरा ट्री दिखाया जाता है, ताकि साइडबार कभी खाली न रहे।

सिलेक्टर

किसी साइट के पूरे विभाजनों के बीच स्विच करने के लिए — एक प्रोडक्ट, एक वर्शन, या गंतव्यों का कोई भी समूहबद्ध सेट — एक selector जोड़ें। हर एक हेडर में ड्रॉपडाउन के रूप में रेंडर होता है, और वह विकल्प दिखाता है जिसका path वर्तमान रूट से मेल खाता है:

navigation: {
  selectors: [
    {
      kind: "version",
      label: "Version",
      items: [
        { label: "v2 (latest)", path: "/v2", icon: "rocket" },
        { label: "v1", path: "/v1" },
      ],
    },
  ],
}

हर आइटम एक label, एक path, और वैकल्पिक icon, description, और tag लेता है। kind (dropdown, product, version, या language) इस बारे में एक संकेत है कि सिलेक्टर का उपयोग कैसे किया जा रहा है; सभी एक ही ड्रॉपडाउन रेंडर करते हैं।

वर्शनिंग कॉन्फ़िगर होने पर, Blume स्वतः एक वर्शन सिलेक्टर रेंडर करता है — यहाँ अपना स्वयं का kind: "version" सिलेक्टर घोषित करना स्वचालित वाले की जगह ले लेता है, इसलिए हाथ से बनाए गए सेटअप काम करते रहते हैं।

फ़ीचर्ड लिंक

लिंक को साइडबार के सबसे ऊपर, हर अनुभाग के ऊपर पिन करें — एक ब्लॉग, एक चेंजलॉग, एक संपर्क या सहायता पेज जो हमेशा एक क्लिक की दूरी पर होना चाहिए। जेनरेट किए गए ट्री के विपरीत, फ़ीचर्ड लिंक टैब द्वारा सीमित नहीं होते: वे हर रूट पर, हर ब्रेकपॉइंट पर दिखते हैं।

navigation: {
  featured: [
    { label: "Blog", href: "https://example.com/blog", icon: "newspaper" },
    { label: "Contact", href: "/contact", icon: "headphones" },
  ],
}

हर लिंक एक label, एक href, और एक वैकल्पिक icon लेता है (एक बिल्ट-इन आइकन नाम, इमेज पाथ/URL, या इनलाइन SVG — बाकी हर जगह की तरह)। एक href कहीं भी इंगित कर सकता है: एक बाहरी URL नए टैब में खुलता है, जबकि एक आंतरिक रूट (/contact) बिल्ड समय पर आपके पेजों के विरुद्ध सत्यापित किया जाता है, और कुछ भी मेल न खाने पर आपको चेतावनी देता है।

पूर्ण नियंत्रण के लिए, navigation.sidebar में स्पष्ट आइटम सूचीबद्ध करें — एक सादा ऐरे sidebar.items का संक्षिप्त रूप है, और ऑब्जेक्ट रूप उन्हें एक ग्लोबल display के साथ जोड़ता है। जब आइटम सेट होते हैं, तो Blume उन्हें ज्यों का त्यों उपयोग करता है और फ़ाइल-सिस्टम जेनरेशन छोड़ देता है:

navigation: {
  sidebar: [
    "/", // a page, referenced by route
    {
      label: "Guides", // a group
      collapsed: false,
      items: ["/configuration", "/configuration/theming"],
    },
    { label: "GitHub", href: "https://github.com/owner/repo" }, // an external link
  ],
}

हर आइटम एक पेज रूट (एक स्ट्रिंग), एक समूह (label + items), या एक लिंक (label + href) होता है। समूह नेस्ट हो सकते हैं, ग्लोबल display मोड को ओवरराइड कर सकते हैं, और collapsed अवस्था में शुरू हो सकते हैं।

हेडर क्रियाएँ

navigation.actions हेडर में, आइकन बटनों के बाईं ओर सादे लिंक रखता है, और navigation.cta वह एकमात्र भरा हुआ बटन है:

navigation: {
  actions: [{ href: "/changelog", label: "Changelog" }],
  cta: { href: "https://example.com/signup", label: "Start free" },
}

cta जानबूझकर एकवचन है — एक डॉक्स हेडर में ठीक एक ऐसी चीज़ के लिए जगह होती है जो पाठक से करने को कही जा रही हो, और बटनों की एक कतार कुछ भी नहीं कहती। द्वितीयक लिंक actions में होने चाहिए, या featured में यदि उन्हें साइडबार के साथ रहना चाहिए।

कोई http(s) या प्रोटोकॉल-सापेक्ष href नए टैब में खुलता है; एक रूट उसी टैब में रहता है, और एक featured लिंक की तरह बिल्ड समय पर आपके पेजों के विरुद्ध सत्यापित किया जाता है — इसलिए उसी होस्ट पर किसी अन्य ऐप द्वारा परोसा जाने वाला पेज (जैसे प्रोडक्ट पर /signup) एक पूर्ण URL के रूप में लिखा जाना चाहिए। actions sm ब्रेकपॉइंट से नीचे छिपे रहते हैं, जहाँ हेडर में लोगो और नेविगेशन टॉगल के अलावा और किसी चीज़ के लिए जगह नहीं होती। cta भी वहाँ छिपता है, सिवाय ऐसे पेज पर जिसमें कोई नेविगेशन टॉगल न हो — बिना टैब वाला PageLayout पर एक लैंडिंग पेज — जहाँ वह बना रहता है, क्योंकि फ़ोन पर उसे सामने लाने वाली और कोई चीज़ नहीं है।

रिपॉज़िटरी लिंक

जब आप अपने कॉन्फ़िग में github सेट करते हैं, तो Blume हेडर में — थीम टॉगल के बगल में — एक GitHub आइकन दिखाता है जो आपकी रिपॉज़िटरी से लिंक होता है। यह डिफ़ॉल्ट रूप से चालू है; इसे navigation.repo से छिपाएँ:

navigation: {
  repo: false, // hide the header GitHub link (default: true)
}

यह लिंक तभी दिखता है जब github कॉन्फ़िगर किया गया हो, इसलिए बिना रिपॉज़िटरी वाले प्रोजेक्ट किसी भी तरह अप्रभावित रहते हैं।

repo एक पूर्ण URL भी लेता है, जो हेडर के चिह्न को GitHub पर कहीं भी इंगित करता है:

navigation: {
  repo: "https://github.com/acme",
}

यह ऐसे प्रोजेक्ट के लिए है जिसकी डॉक्स रिपॉज़िटरी निजी है। github प्रति-पेज संपादन लिंक, हेडर के चिह्न और एजेंट मैनिफ़ेस्ट की रिपॉज़िटरी — तीनों को एक साथ चलाता है, इसलिए ऐसे प्रोजेक्ट को github अनसेट छोड़ना पड़ता है — और एक URL ही वह चीज़ है जो उसे फिर भी कहीं सार्वजनिक की ओर इंगित करता चिह्न दिखाने देती है। आइकन GitHub का चिह्न ही रहता है, इसलिए किसी अन्य होस्ट का लिंक actions में होना चाहिए।

ब्रेडक्रंब और पेजिनेशन

ये साइडबार ट्री से मुफ़्त में मिलते हैं — कोई कॉन्फ़िगरेशन नहीं:

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

इस पेज पर

हर पेज के ## और ### शीर्षकों से एक दायाँ-रेल आउटलाइन स्वतः जेनरेट होता है, ताकि लंबे पेज भी आसानी से स्कैन किए जा सकें। सँकरी स्क्रीन पर, जहाँ दायाँ रेल छिपा होता है, यह कंटेंट के ऊपर एक “इस पेज पर” ड्रॉपडाउन में सिमट जाता है।

पेज क्रियाएँ

विषय-सूची के नीचे, हर पेज त्वरित क्रियाओं का एक सेट दिखाता है:

GitHub पर संपादित करें — सीधे स्रोत फ़ाइल से लिंक करता है। आपके कॉन्फ़िग में github सेट करने पर दिखता है।
ऊपर स्क्रॉल करें — लंबे पेजों के शीर्ष पर सहजता से लौटाता है।
फ़ीडबैक दें — एक वैकल्पिक प्रतिक्रिया और नोट के साथ पहले से भरा हुआ GitHub इशू खोलता है (इसके लिए भी github ज़रूरी है)।

अन्य क्रियाएँ पेज को AI टूल्स को सौंपती हैं — Markdown के रूप में कॉपी करें और चैट में खोलें — जिन्हें AI में कवर किया गया है।

export चालू होने पर, एक एक्सपोर्ट क्रिया पाठकों को पेज को PDF या EPUB के रूप में डाउनलोड करने की सुविधा भी देती है।