रिमोट MDX

mdxRemote() सोर्स की सहायता से किसी GitHub रिपॉज़िटरी या रॉ URL से HTTP के माध्यम से Markdown और MDX फ़ेच करें, जिन्हें हर Blume कॉम्पोनेंट के साथ रेंडर किया जाता है।

बिल्ट-इन mdxRemote() एडैप्टर HTTP के माध्यम से रॉ .md/.mdx फ़ाइलें फ़ेच करता है। आप फ़ाइलों को या तो किसी GitHub रिपॉज़िटरी के सबट्री (github) से सूचीबद्ध कर सकते हैं, या किसी रॉ बेस URL के सापेक्ष स्पष्ट रूप से (url + files) निर्दिष्ट कर सकते हैं:

import { defineConfig } from "blume";
import { filesystem, mdxRemote } from "blume/sources";

export default defineConfig({
  content: {
    sources: [
      filesystem({ root: "docs" }),
      // The docs/ subtree of acme/sdk, mounted under /sdk
      mdxRemote({
        prefix: "sdk",
        github: { owner: "acme", repo: "sdk", ref: "main", path: "docs" },
      }),
    ],
  },
});

यदि आप फ़ाइलों की सूची स्वयं देना चाहते हैं, तो url को किसी रॉ बेस URL पर सेट करें:

mdxRemote({
  prefix: "sdk",
  url: "https://raw.githubusercontent.com/acme/sdk/main/docs",
  files: ["intro.mdx", "guide.mdx"],
});

include (डिफ़ॉल्ट ["**/*.{md,mdx}"]) फ़ाइलों को path के अंतर्गत उनके पाथ के आधार पर फ़िल्टर करता है, ठीक उसी तरह जैसे किसी filesystem() सोर्स का include करता है: ! से शुरू होने वाला पैटर्न उन फ़ाइलों को बाहर कर देता है जिनसे वह मेल खाता है (["**/*.mdx", "!drafts/**"])। github के साथ, सोर्स ref पर रिपॉज़िटरी के पूरे ट्री को सूचीबद्ध करता है और केवल path के अंतर्गत आने वाली फ़ाइलों को रखता है। यदि उस ref पर path के अंतर्गत कुछ भी नहीं है, तो सोर्स कोई पेज नहीं पढ़ता और BLUME_SOURCE_PATH_MISSING के साथ चेतावनी देता है। GitHub इस सूची की एक सीमा तय करता है (पूरी रिपॉज़िटरी के लिए 100,000 एंट्री या 7 MB, चाहे path कुछ भी हो), और यह सीमा पार होने पर सोर्स BLUME_SOURCE_TRUNCATED के साथ चेतावनी देता है: ऐसी स्थिति में फ़ाइलों को url और files के साथ सूचीबद्ध करें।

रिमोट फ़ाइलों के बीच कोई सापेक्ष लिंक ([Errors](./02-errors.mdx)) उस पेज पर ले जाता है जिस पर लिंक की गई फ़ाइल प्रकाशित होती है, और रूट से उसका क्रम-निर्धारण प्रीफ़िक्स हटा दिया जाता है। यह रेंडर किए गए पेज पर, पेज की Markdown कॉपी और llms-full.txt में, तथा असिस्टेंट द्वारा पढ़ी जाने वाली सामग्री में भी इसी तरह काम करता है, और blume validate भी इस लिंक की जाँच इसी तरह करता है।

किसी प्राइवेट रिपॉज़िटरी का टोकन GITHUB_TOKEN एनवायरनमेंट वेरिएबल से पढ़ा जाता है। यह टोकन कभी भी आपके कॉन्फ़िग या जनरेट किए गए आउटपुट में इनलाइन नहीं किया जाता। इसे केवल GitHub के अपने होस्ट (api.github.com, raw.githubusercontent.com) पर ही भेजा जाता है, किसी कस्टम url बेस पर कभी नहीं। पब्लिक रिपॉज़िटरी इस टोकन के बिना भी काम करती है। github के साथ, एडैप्टर इस वेरिएबल को घोषित करता है, इसलिए यदि यह सेट न हो तो blume dev और blume build BLUME_MISSING_SECRET के साथ चेतावनी देते हैं: फ़ाइलों की सूची GitHub के API के माध्यम से प्राप्त की जाती है, जो बिना प्रमाणीकरण के प्रति घंटे केवल 60 अनुरोधों की अनुमति देता है। रॉ url केवल फ़ाइलें पढ़ता है, इसलिए पहले से कोई चेतावनी नहीं दी जाती। यदि GITHUB_TOKEN सेट न हो और GitHub किसी फ़ाइल को 401, 403 या 404 के साथ अस्वीकार कर दे, तो छोड़ी गई फ़ाइल की चेतावनी में बताया जाता है कि यह वेरिएबल सेट नहीं है।

GitHub पर पढ़े जाने के लिए लिखी गई फ़ाइल अक्सर किसी # Heading से शुरू होती है, जबकि Blume पेज के title को उसके <h1> के रूप में रेंडर करता है। यदि किसी रिमोट पेज की पहली पंक्ति ऐसा h1 है जो उसके फ़्रंट मैटर के title से मेल खाता है, या फ़्रंट मैटर में कोई title सेट नहीं है, तो वह हेडिंग हटा दी जाती है और उसका टेक्स्ट ही टाइटल बन जाता है। इस तरह पेज पर केवल एक <h1> दिखाई देता है। यदि पहली हेडिंग title से भिन्न है, तो वह बनी रहती है।

रिमोट पेज पूरी MDX और कॉम्पोनेंट सटीकता के साथ रेंडर किए जाते हैं। उनकी सामग्री एक छिपी हुई स्टेजिंग डायरेक्टरी में लिखी जाती है और आपके लोकल डॉक्स के साथ Astro के माध्यम से रेंडर की जाती है। इसलिए कॉलआउट, टैब और Blume के अन्य सभी कॉम्पोनेंट सामान्य रूप से काम करते रहते हैं।

अन्य सभी रिमोट सोर्स की तरह, फ़ेच किए गए पेज ऑफ़लाइन बिल्ड के लिए कैश किए जाते हैं और blume sync से रीफ़्रेश होते हैं। अधिक जानकारी के लिए कैशिंग और ऑफ़लाइन बिल्ड देखें।

कई GitHub रिपॉज़िटरी से एक डॉक्स पोर्टल बनाएँ गाइड में इसका उपयोग हर रिपॉज़िटरी के डॉक्स फ़ोल्डर को एक ही साइट में लाने के लिए किया गया है। यह सामग्री किसी एक रिलीज़ पर पिन रहती है, जो केवल तभी बदलती है जब आप उसे बदलते हैं।