पेज

आपके कंटेंट फ़ोल्डर की फ़ाइलें कैसे पेज बनती हैं, और उन्हें कैसे व्यवस्थित तथा नामित करें ताकि रूटिंग और नेविगेशन अपने आप अनुमानित हो जाएँ।

आपके डॉक्स केवल Markdown और MDX फ़ाइलों का एक फ़ोल्डर हैं। Blume हर फ़ाइल को एक पेज में बदल देता है — रूटिंग, नेविगेशन और मेटाडेटा फ़ाइल सिस्टम से अनुमानित होते हैं, इसलिए सिंक में रखने के लिए कोई मैनिफ़ेस्ट नहीं होता।

कंटेंट आपके कंटेंट रूट के अंतर्गत रहता है (डिफ़ॉल्ट रूप से docs/; इसे blume.config.ts में content.root से बदलें)।

Markdown और MDX

Blume दो तरह की फ़ाइलें रेंडर करता है:

• .md — सादे गद्य के लिए Markdown: GFM, frontmatter, स्मार्ट विराम-चिह्न, और सुपरस्क्रिप्ट/सबस्क्रिप्ट।
• .mdx — वह सब कुछ जो .md में है, साथ ही कंपोनेंट्स और केवल MDX वाले डायरेक्टिव, पैकेज इंस्टॉल, और गणित।

जब कोई पेज केवल गद्य हो तो .md चुनें, और जब उसमें कंपोनेंट्स या डायरेक्टिव चाहिए हों तो .mdx। बदलना बस फ़ाइल का नाम बदलने जितना आसान है।

.mdx में { एक JavaScript एक्सप्रेशन शुरू करता है और < एक JSX टैग, इसलिए जो टेक्स्ट .md में ठीक है वह किसी पेज को तोड़ सकता है: एक शाब्दिक ब्रेस, एक HTML कमेंट ({/* … */} लिखें), या खुला छोड़ा गया कोई एलिमेंट (<br /> लिखें)। Blume प्रोजेक्ट पढ़ते समय हर .mdx पेज को पार्स करता है, इसलिए जो पेज पार्स नहीं होता उसे blume dev, blume validate, blume doctor, और blume check BLUME_MDX_SYNTAX के रूप में रिपोर्ट करते हैं, जो उस पंक्ति और कॉलम पर एक त्रुटि होती है जहाँ MDX रुका था, और blume build कुछ भी कंपाइल करने से पहले वहीं रुक जाता है। --no-strict के साथ, बिल्ड उस पेज को छोड़ देता है और बाकी साइट बना देता है। blume dev पेज को बनाए रखता है, और उसे खोलने पर त्रुटि दिखाई देती है।

कोई एक्सप्रेशन पार्स हो सकता है और फिर भी पेज रेंडर होते समय विफल हो सकता है, जैसे किसी ऐसे पेज पर {user.name} जहाँ user कहीं परिभाषित नहीं है। blume build इसे एक्सप्रेशन की पंक्ति पर BLUME_MDX_UNDEFINED_NAME के रूप में रिपोर्ट करता है, चाहे वह एक्सप्रेशन पेज में हो या उस पार्शियल में जिसमें वह मौजूद है। ब्रेसेज़ को टेक्स्ट के रूप में दिखाने के लिए, हर खुलने वाले ब्रेस को एस्केप करें (\{) या टेक्स्ट को इनलाइन कोड में रखें। ऐसे मान के लिए जिसे हर पेज साझा करता है, एक वेरिएबल परिभाषित करें।

फ़ाइलें और रूट्स

हर फ़ाइल कंटेंट रूट के अंतर्गत अपने पाथ के अनुसार एक रूट से मैप होती है:

नेस्टेड फ़ोल्डर नेस्टेड रूट बन जाते हैं, और किसी फ़ोल्डर के अंदर मौजूद index.mdx उस फ़ोल्डर का अपना पेज बन जाता है।

जो अक्षर किसी पेज के URL को तोड़ सकते हैं — #, ?, %, और : — वे उसके रूट से हटा दिए जाते हैं, इसलिए 100%.mdx /100 पर प्रकाशित होता है। # और ? को फ़ाइल और फ़ोल्डर के नामों में बिल्कुल न रखें: Astro का कंटेंट लोडर ऐसी फ़ाइल को पढ़ नहीं सकता, इसलिए Blume उसे एक त्रुटि के रूप में रिपोर्ट करता है और साइट से बाहर छोड़ देता है। sdks/c#.mdx का नाम बदलकर sdks/c.mdx करें, तो वह /sdks/c पर प्रकाशित होगा — यानी वही रूट जो इन अक्षरों के हटने के बाद वैसे भी बनता।

संख्यात्मक उपसर्गों से क्रम तय करना

साइडबार में क्रम नियंत्रित करने के लिए किसी फ़ाइल या फ़ोल्डर के आगे एक संख्या और एक -, _, या . लगाएँ। यह उपसर्ग URL से हटा दिया जाता है, इसलिए आप लिंक तोड़े बिना पेजों का क्रम बदल सकते हैं:

01-introduction.mdx  ->  /introduction
02-installation.mdx  ->  /installation

किसी नाम की शुरुआत में मौजूद संस्करण या तिथि नाम का हिस्सा होती है, क्रम नहीं: 1.2.0.mdx का रूट /1.2.0 होता है, और 2024-01-05-launch.mdx का /2024-01-05-launch। Blume इन्हें तिथियों के रूप में पढ़ता है:

• एक ISO तिथि, YYYY-MM-DD: 2024-01-05.mdx का रूट /2024-01-05 होता है।
• पहले दिन या महीना, फिर चार अंकों का वर्ष, यानी D-M-YYYY या M-D-YYYY, जिसमें दिन और महीने के लिए एक या दो अंक हों: 12-05-2022.mdx का रूट /12-05-2022 होता है।
• एक वर्ष और एक महीना, YYYY-MM: 2024-01.mdx का रूट /2024-01 होता है।

तिथि या तो नाम के अंत में आती है या उसके बाद एक -, _, या . और फिर नाम का बाकी हिस्सा आता है (2024-01-recap.mdx)। Blume के पुराने संस्करण अंतिम दो रूपों की पहली संख्या को क्रम-उपसर्ग के रूप में पढ़ते थे, इसलिए 12-05-2022.mdx /05-2022 पर और 2024-01.mdx /01 पर प्रकाशित होता था। वे पुराने URL अब नए URL पर रीडायरेक्ट होते हैं, जब तक कि वहाँ कोई दूसरा पेज मौजूद न हो। उपसर्ग केवल फ़ाइल और फ़ोल्डर के नामों से हटाया जाता है (Obsidian vault के नोट्स फ़ाइलें ही माने जाते हैं)। frontmatter में दिया गया slug, और CMS या GitHub Releases जैसे किसी कंटेंट स्रोत से आने वाला पेज, वही नाम बनाए रखते हैं जो उन्हें दिया गया था।

क्रम निर्धारण की कई परतें हैं — पूरी प्राथमिकता नियमावली के लिए नेविगेशन देखें।

समूह फ़ोल्डर

किसी फ़ोल्डर के नाम को कोष्ठकों में लपेटें ताकि उसके पेज साइडबार में समूहित हो जाएँ, बिना कोई URL सेगमेंट जोड़े:

docs/(internal)/security.mdx  ->  /security

ये पेज एक साझा “Internal” साइडबार समूह में रहते हैं, लेकिन उनके URL सपाट और कोष्ठक-रहित बने रहते हैं। किसी भी अन्य फ़ोल्डर की तरह समूह फ़ोल्डर पर भी संख्यात्मक उपसर्ग लगाया जा सकता है, कोष्ठकों के अंदर या बाहर: (01-internal) और 01-(internal) दोनों सबसे पहले क्रमित होते हैं और उनका रूट (internal) की तरह ही बनता है।

ड्राफ़्ट

किसी पेज को ड्राफ़्ट के रूप में चिह्नित करें ताकि वह प्रोडक्शन बिल्ड से बाहर रहे, फिर भी blume dev में उसका पूर्वावलोकन किया जा सके:

---
title: Work in progress
draft: true
---

blume build ड्राफ़्ट को छोड़ देता है; blume dev उन्हें रेंडर करता है ताकि आप खुले में काम कर सकें।

कंटेंट प्रकार

हर पेज का एक प्रकार होता है, जो type frontmatter फ़ील्ड से तय होता है (डिफ़ॉल्ट doc)। प्रकार Blume को पेजों के समूहों के साथ अलग-अलग व्यवहार करने देते हैं — सबसे महत्वपूर्ण यह कि blog और changelog पेज फ़ीड में एकत्र किए जाते हैं।

---
title: v1.2.0
type: changelog
date: 2026-06-20
changelog:
  version: 1.2.0
  category: Features
---

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

फ़ीड

Blume seo.rss.types में सूचीबद्ध हर कंटेंट प्रकार के लिए अपने आप एक RSS फ़ीड जनरेट करता है — डिफ़ॉल्ट रूप से blog और changelog — बशर्ते उसमें कम से कम एक पेज हो। फ़ीड /<type>/rss.xml पर सर्व की जाती हैं:

हर प्रविष्टि को एक date दें ताकि आइटम नए-से-पुराने क्रम में सज सकें और उनमें pubDate हो। बिना उद्धरण चिह्न वाली YAML तिथि ठीक है — Blume उसे सामान्यीकृत कर देता है:

---
title: Introducing Blume
type: blog
date: 2026-06-22
description: Why we built a markdown-first docs framework.
---

फ़ीड को एक निरपेक्ष साइट URL चाहिए, इसलिए deployment.site सेट करें। Blume हर पेज में <link rel="alternate"> टैग जोड़ता है ताकि ब्राउज़र और फ़ीड रीडर उन्हें अपने आप खोज लें। प्रत्येक कंटेंट प्रकार को लिखने के लिए ब्लॉग और चेंजलॉग देखें।

इस पेज पर

हर पेज को उसके शीर्षकों से बनी एक स्वचालित विषय-सूची मिलती है। चौड़ी स्क्रीन पर यह आपके कंटेंट के बगल में एक स्टिकी साइडबार में रहती है; सँकरी स्क्रीन पर यह पेज के ऊपर एक इस पेज पर पैनल में सिमट जाती है। जैसे-जैसे आप स्क्रॉल करते हैं, आप जिस सेक्शन को पढ़ रहे होते हैं उसकी प्रविष्टि हाइलाइट हो जाती है, ताकि लंबे पेज में आपको हमेशा पता रहे कि आप कहाँ हैं।

Blume हर शीर्षक को एक ऐंकर में स्लगिफ़ाई करता है, इसलिए हर प्रविष्टि सीधे अपने सेक्शन से लिंक होती है — और आप URL के अंत में उसका स्लग जोड़कर किसी भी शीर्षक तक डीप-लिंक कर सकते हैं (.../my-page#getting-started)।

डिफ़ॉल्ट रूप से विषय-सूची में आपके ## और ### शीर्षक (H2 और H3) सूचीबद्ध होते हैं; शीर्षकों की सीमा बदलने या विषय-सूची बंद करने के लिए toc सेट करें। जिस पेज में उस सीमा का कोई शीर्षक नहीं होता, उसमें बस कोई विषय-सूची नहीं होती।

आगे कहाँ जाएँ