संस्करणीकरण

संस्करण स्विचर, नवीनतम-की-ओर कैनोनिकल SEO, संस्करण-आधारित खोज और संस्करण-सजग एजेंट सतह के साथ प्रति रिलीज़ अपने दस्तावेज़ों के स्नैपशॉट फ़्रीज़ करें।

Blume आपके दस्तावेज़ों को उसी तरह संस्करणित करता है जैसे रिलीज़ वास्तव में काम करती हैं: नवीनतम दस्तावेज़ीकरण आपके कंटेंट रूट पर स्वच्छ, उपसर्ग-रहित URL के साथ रहता है, और प्रत्येक पिछला संस्करण अपने स्वयं के फ़ोल्डर में एक फ़्रीज़ किया गया स्नैपशॉट होता है। जब आप शिप करें तब एक स्नैपशॉट काटें, और Blume आपके लिए स्विचर, “पुराना संस्करण” सूचना, खोज की परिधि, SEO और एजेंट सतह को जोड़ देता है। यह ऑप्ट-इन है: versions ब्लॉक के बिना कुछ भी नहीं बदलता।

इसे सक्षम करें

एक versions ब्लॉक जोड़ें जो वर्तमान दस्तावेज़ों और किसी भी संग्रहीत स्नैपशॉट का नाम बताए:

versions: {
  current: { label: "v2.0", badge: "Latest" },
  archived: [
    { id: "v1.0" },
    { id: "v0.9", label: "0.9 (legacy)" },
  ],
}

current स्विचर में उपसर्ग-रहित ट्री को लेबल करता है (एक वैकल्पिक badge के साथ)। प्रत्येक संग्रहीत प्रविष्टि का id स्नैपशॉट की डायरेक्टरी का नाम भी है और उसका URL खंड भी — id का आरंभ किसी अक्षर से होना चाहिए (v1.0, न कि 1.0) ताकि वे कभी भी संख्यात्मक क्रम उपसर्गों से न टकराएँ। संग्रहीत संस्करणों को नवीनतम पहले के क्रम में सूचीबद्ध करें; वही क्रम स्विचर का क्रम होता है।

एक संस्करण काटें

जब आप रिलीज़ करें, तो वर्तमान दस्तावेज़ों को एक ही कमांड से फ़्रीज़ करें:

blume version v1.0

यह आपके कंटेंट ट्री को docs/v1.0/ में कॉपी करता है (मौजूदा स्नैपशॉट छोड़कर), कॉपी के भीतर रूट-निरपेक्ष लिंक को फिर से लिखता है ताकि वे स्नैपशॉट के भीतर ही रहें (/guides/x बन जाता है /v1.0/guides/x, फेंस्ड और इनलाइन कोड अछूता रहता है), और id को blume.config.ts में पंजीकृत करता है — या जब आपका कॉन्फ़िग ऐसी संरचना में हो जिसे यह छुएगा नहीं, तब चिपकाने हेतु प्रविष्टि प्रिंट कर देता है। जो पृष्ठ कॉपी किए गए ट्री का हिस्सा नहीं हैं, उनके लिंक — उत्पन्न API संदर्भ, चेंजलॉग जैसे दूरस्थ स्रोत — लाइव पृष्ठों की ओर ही संकेत करते रहते हैं, क्योंकि स्नैपशॉट के पास उनकी कोई प्रति नहीं होती। कॉन्फ़िगर किए गए संस्करणों की सूची देखने के लिए blume version को बिना id के चलाएँ।

नई डायरेक्टरी की समीक्षा करें और उसे किसी भी अन्य कंटेंट की तरह कमिट करें। इसे उठाने के लिए blume dev को पुनः आरंभ करें।

docs/
  index.mdx               ->  /              (latest)
  guides/quickstart.mdx   ->  /guides/quickstart
  v1.0/
    index.mdx             ->  /v1.0          (frozen)
    guides/quickstart.mdx ->  /v1.0/guides/quickstart

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

स्विचर और सूचना

संस्करण कॉन्फ़िगर होने पर, हेडर में स्वतः एक संस्करण ड्रॉपडाउन जुड़ जाता है। स्विच करने पर आप लक्षित संस्करण में उसी पृष्ठ पर पहुँचते हैं यदि वह मौजूद हो, और न होने पर उस संस्करण के रूट पर (हमेशा रूट पर पहुँचने के लिए switcher.redirect: "root" सेट करें)। यदि आप navigation.selectors में अपना स्वयं का kind: "version" सिलेक्टर घोषित करते हैं, तो वह स्वचालित सिलेक्टर को प्रतिस्थापित कर देता है।

प्रत्येक संग्रहीत पृष्ठ पर एक न हटाई जा सकने वाली सूचना भी दिखती है, जिसमें “नवीनतम पर जाएँ” लिंक उस पृष्ठ के लाइव समकक्ष की ओर संकेत करता है। इसे प्रति संस्करण अनुकूलित या निष्क्रिय करें:

archived: [
  { id: "v1.0", banner: "These docs cover the 1.x SDK." },
  { id: "v0.9", banner: false },
];

SEO

पुराने दस्तावेज़ खोज इंजनों का प्रिय जाल होते हैं: बासी पृष्ठ लाइव पृष्ठ से ऊपर रैंक कर जाता है, या दोनों प्रतिस्पर्धा करते हैं। Blume वही उत्तर डिफ़ॉल्ट रूप से अपनाता है जिसकी SEO मार्गदर्शिकाएँ सिफ़ारिश करती हैं और जिसे कोई अन्य दस्तावेज़ फ़्रेमवर्क स्वचालित नहीं करता — संग्रहीत पृष्ठ इंडेक्स-योग्य बने रहते हैं परंतु नवीनतम समकक्ष को अपना कैनोनिकल घोषित करते हैं, जिससे लाइव पृष्ठ आधिकारिक रहता है जबकि केवल-संस्करण कंटेंट (ऐसा पृष्ठ जो नवीनतम दस्तावेज़ों में अब मौजूद नहीं है) स्व-कैनोनिकल के साथ खोजने योग्य बना रहता है।

प्रति संस्करण आप एक भिन्न व्यवहार चुन सकते हैं:

archived: [
  { id: "v1.0" }, // canonical → latest (default)
  { id: "v0.9", canonical: "self" }, // every page authoritative
  { id: "v0.8", noindex: true }, // deindexed entirely
];

साइटमैप भी यही अनुसरण करता है: वे संग्रहीत पृष्ठ जिनका कैनोनिकल किसी लाइव समकक्ष की ओर संकेत करता है, छोड़ दिए जाते हैं, noindex संस्करण पूरी तरह छोड़ दिए जाते हैं, और केवल-संस्करण पृष्ठ सूचीबद्ध रहते हैं। किसी पृष्ठ का अपना seo.canonical फ़्रंटमैटर हमेशा प्रभावी रहता है।

खोज

खोज डायलॉग परिणामों को देखे जा रहे संस्करण तक सीमित रखता है, और भाषा टॉगल के बगल में एक “सभी संस्करण” टॉगल (प्रति पाठक याद रखा जाने वाला) देता है। क्रॉस-संस्करण परिणाम अपनी पंक्ति पर अपने संस्करण का नाम बताते हैं। Orama (डिफ़ॉल्ट), FlexSearch, Algolia और Typesense सभी इस परिधि का पालन करते हैं — होस्टेड रिकॉर्ड एक version फ़ेसेट रखते हैं, जिसमें वर्तमान दस्तावेज़ "current" के रूप में अपलोड होते हैं — जबकि Pagefind अपरिधित रहता है, जो उसके लोकेल व्यवहार से मेल खाता है।

एजेंट

एजेंट सतह संस्करण-सजग है — ऐसा कुछ जो कोई अन्य दस्तावेज़ फ़्रेमवर्क नहीं करता:

• MCP के search_docs और list_pages टूल डिफ़ॉल्ट रूप से वर्तमान दस्तावेज़ों पर काम करते हैं और version स्वीकार करते हैं: एक संग्रहीत id ("v1.0") या "all"। get_navigation अनुरोध पर किसी संग्रहीत स्नैपशॉट का ट्री लौटाता है।
• llms.txt संग्रहीत संस्करणों को वर्तमान दस्तावेज़ों के बाद अनुभागों में रखता है, 1.0 (archived) के रूप में लेबल करके, ताकि इंडेक्स पढ़ने वाला एजेंट जान सके कि कौन-से दस्तावेज़ फ़्रीज़ किए गए हैं।
• llms-full.txt केवल-वर्तमान रहता है — यह सपाट डंप एक ही पृष्ठ की फ़्रीज़ की गई प्रतियों को कभी आपस में नहीं मिलाता।
• हर संस्करण के पृष्ठों के लिए रॉ Markdown मिरर (.md URL) मौजूद रहते हैं, जैसे किसी भी रूट के लिए होते हैं।

i18n के साथ

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

docs/
  guides/x.mdx            ->  /guides/x
  fr/guides/x.mdx         ->  /fr/guides/x
  v1.0/
    guides/x.mdx          ->  /v1.0/guides/x
    fr/guides/x.mdx       ->  /fr/v1.0/guides/x

लोकेल फ़ॉलबैक प्रत्येक संस्करण के भीतर काम करता है: कोई अअनूदित स्नैपशॉट पृष्ठ स्थानीयकृत URL पर फ़ॉलबैक लोकेल का कंटेंट रेंडर करता है, और hreflang विकल्प प्रति संस्करण समूहित होते हैं। कोई संस्करण id किसी कॉन्फ़िगर किए गए लोकेल कोड से नहीं टकरा सकता — Blume ऐसे कॉन्फ़िग को सीधे अस्वीकार कर देता है।

क्या असंस्करणित रहता है

संस्करणीकरण दस्तावेज़ कंटेंट ट्री को कवर करता है। ब्लॉग, चेंजलॉग, OpenAPI विनिर्देशों से उत्पन्न API संदर्भ, और कस्टम पृष्ठ हमेशा वर्तमान रहते हैं। दो और व्यवहार जानने योग्य हैं: हेडर टैब वर्तमान दस्तावेज़ों के सापेक्ष परिभाषित होते हैं, इसलिए किसी संग्रहीत ट्री के भीतर साइडबार टैब द्वारा अपरिधित रेंडर होता है; और बड़ी साइटों को ध्यान देना चाहिए कि प्रत्येक स्नैपशॉट एक पूर्ण प्रति है — कंटेंट, खोज इंडेक्स प्रविष्टियाँ, और नेविगेशन डेटा सभी प्रति संस्करण बढ़ते हैं।