Notion

notion() सोर्स के साथ Notion डेटाबेस इम्पोर्ट करें — पंक्तियाँ पेज बनती हैं, प्रॉपर्टीज़ फ्रंटमैटर बनती हैं, और ब्लॉक Blume कंपोनेंट्स बनते हैं।

बिल्ट-इन notion() एडेप्टर किसी Notion डेटाबेस को एक कलेक्शन में बदल देता है: प्रत्येक पंक्ति एक पेज बनती है, उसकी प्रॉपर्टीज़ फ्रंटमैटर बनती हैं, और उसका ब्लॉक ट्री MDX बनता है। कॉलआउट, टॉगल, कॉलम और कोड ब्लॉक संबंधित Blume कंपोनेंट्स से मैप होते हैं, और Notion में आप जो टेक्स्ट टाइप करते हैं वह ठीक वैसे ही रेंडर होता है जैसा लिखा गया है: किसी पेज में मौजूद {, < या Markdown वर्ण को MDX, JSX या फ़ॉर्मैटिंग के रूप में पढ़ने के बजाय एस्केप किया जाता है, जब तक कि आप MDX के लिए ऑप्ट इन न करें। वीडियो ब्लॉक में YouTube लिंक होने पर वे <YouTube> एम्बेड बन जाते हैं और अन्यथा <video> प्लेयर। दोनों ही स्थितियों में ब्लॉक का कैप्शन <Frame> कैप्शन बनता है। अगर लिंक किसी मीडिया फ़ाइल के बजाय किसी वीडियो पेज का है (जैसे Vimeo या Loom URL), तो उसे बिल्ड चेतावनी के रूप में रिपोर्ट किया जाता है। उसका <video> प्लेयर उसी पेज की ओर इंगित करता रहता है, जिसे वह चला नहीं सकता, इसलिए ऐसे वीडियो का लिंक टेक्स्ट में दें। एडेप्टर @notionhq/client (v5 या उसके बाद का संस्करण) को अपनी रनटाइम निर्भरता के रूप में घोषित करता है, जो एक वैकल्पिक पीयर है। Blume डेटाबेस को उसके पहले डेटा सोर्स के माध्यम से पढ़ता है।

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

export default defineConfig({
  content: {
    sources: [
      filesystem({ root: "docs" }),
      notion({
        prefix: "handbook",
        database: "8f2c1e0a4b7d4f3c9e6a5d2b1c0f9e8d", // the id in the database URL
        // Property names default to the title-typed prop / Description / Slug / Order / Status
        // Pages whose Status isn't publishedValue (default "Published") import as drafts
        publishedValue: "Done",
      }),
    ],
  },
});

इंटीग्रेशन टोकन NOTION_TOKEN एनवायरनमेंट वेरिएबल से लिया जाता है (डेटाबेस को अपने इंटीग्रेशन के साथ साझा करें)। इसके बिना, सोर्स Notion को कॉल करने से पहले ही BLUME_MISSING_SECRET त्रुटि के साथ रुक जाता है, जिसमें उस वेरिएबल का नाम बताया जाता है, जब तक कि उसके पास इसके बजाय सर्व करने के लिए कोई कैश किया गया स्नैपशॉट न हो।

Status प्रॉपर्टी डिफ़ॉल्ट रूप से यह तय करती है कि कौन-सा पेज प्रकाशित होगा। इसका मान publishedValue से तुलना किया जाता है, जिसका डिफ़ॉल्ट Published है। अगर किसी पेज के Status (एक status या select प्रॉपर्टी) में publishedValue के अलावा कोई और मान है, तो वह पेज draft: true के साथ इम्पोर्ट होता है, और प्रोडक्शन बिल्ड ड्राफ़्ट को हटा देते हैं। जिस पेज में कोई Status मान नहीं है, वह प्रकाशित होता है। जिस डेटाबेस में यह प्रॉपर्टी ही नहीं है, उसका हर पेज प्रकाशित होता है। Notion के डिफ़ॉल्ट status विकल्प Not started, In progress और Done हैं। इसलिए इन विकल्पों का उपयोग करने वाले डेटाबेस में कोई Published मान नहीं होता, और जब तक आप publishedValue: "Done" (या प्रकाशित को दर्शाने वाला कोई और विकल्प) सेट नहीं करते, वह कुछ भी प्रकाशित नहीं करता। अगर आपकी status प्रॉपर्टी का नाम अलग है, तो उसे properties.status में दें। अगर आप हर पेज को उसका status देखे बिना इम्पोर्ट करना चाहते हैं, तो इसे ऐसी प्रॉपर्टी पर सेट करें जो डेटाबेस में मौजूद नहीं है।

Notion की इमेज और वीडियो URLs साइन की हुई होती हैं और कुछ समय बाद समाप्त हो जाती हैं। इसलिए एडेप्टर बिल्ड के समय उन्हें साइट के एसेट्स में डाउनलोड करता है और उनके संदर्भ बदल देता है। इससे CMS का कोई एसेट समय के साथ स्टैटिक बिल्ड में टूटता नहीं है। केवल वही फ़ाइल सहेजी जाती है जिसे सर्वर इमेज या वीडियो बताता है। अगर रिस्पॉन्स में यह जानकारी नहीं है, तो वह फ़ाइल सहेजी जाती है जिसके URL में इमेज या वीडियो एक्सटेंशन हो। बाकी फ़ाइलों का मूल URL ही रहता है और बिल्ड चेतावनी दिखती है, ताकि आपकी साइट के ओरिजिन से मीडिया के अलावा कुछ भी सर्व न हो। API कॉल्स एक छोटे रिक्वेस्ट पूल से भेजी जाती हैं, एक समय में 3, जो Notion की प्रति-इंटीग्रेशन रेट लिमिट के बराबर है। इससे सैकड़ों पेजों वाले डेटाबेस भी 429 रिस्पॉन्स के बिना इम्पोर्ट हो जाते हैं। इसे बदलने के लिए सोर्स पर concurrency सेट करें।

किसी Notion डेटाबेस को डॉक्स साइट में बदलें इस पूरी प्रक्रिया को शुरू से अंत तक समझाता है, जिसमें एक Status प्रॉपर्टी यह तय करती है कि क्या लाइव होगा। एक ही डॉक्यूमेंटेशन साइट में Markdown और Notion को मिलाएँ Notion एडिटर्स को Git में मौजूद Markdown के साथ उनका अपना एक अलग सेक्शन देता है।

Notion में MDX लिखना

अधिकांश Blume कंपोनेंट्स के लिए Notion में कोई ब्लॉक नहीं है। Notion पेज में इनमें से किसी का उपयोग करने के लिए (जैसे <Card> कंपोनेंट्स का एक <CardGroup>), उसका MDX टेक्स्ट के रूप में टाइप करें और mdx: true सेट करें। इसके बाद सोर्स पैराग्राफ़, हेडिंग, लिस्ट आइटम, कोट और कॉलआउट के टेक्स्ट को MDX के रूप में पढ़ता है। इसलिए Notion में टाइप किए गए कंपोनेंट्स, {expressions} और Markdown, Notion के अपने बोल्ड, इटैलिक, लिंक और इनलाइन कोड के साथ रेंडर होते हैं। कोड ब्लॉक, टॉगल शीर्षक, इमेज और वीडियो कैप्शन, और प्रॉपर्टीज़ सादा टेक्स्ट ही रहते हैं।

notion({
  database: "8f2c1e0a4b7d4f3c9e6a5d2b1c0f9e8d",
  mdx: true,
});

इसके बाद टेक्स्ट पर किसी .mdx फ़ाइल की तरह MDX के नियम लागू होते हैं: कोई अनपेक्षित { या < पेज को विफल कर देता है, और import से शुरू होने वाला पैराग्राफ़ import स्टेटमेंट के रूप में पढ़ा जाता है। साइट बिल्ड होते समय MDX कोड चलाता है। इसलिए जो भी डेटाबेस को एडिट कर सकता है, वह आपकी बिल्ड मशीन पर कोड चला सकता है और उसके एनवायरनमेंट वेरिएबल्स पढ़ सकता है, जिनमें NOTION_TOKEN भी शामिल है। mdx केवल ऐसे डेटाबेस के लिए चालू करें जिसके एडिटर्स को आप साइट का कोड सौंपने लायक भरोसेमंद मानते हों।