Jekyll . में H2s से स्वचालित रूप से सबनेविगेशन उत्पन्न करें

मैं Jekyll का उपयोग करके अपनी प्रलेखन साइट का पुनर्निर्माण कर रहा हूं। चूंकि हमारे दस्तावेज़ पृष्ठ बहुत बड़े हैं, इसलिए हमें शीर्ष-स्तरीय नेविगेशन के अतिरिक्त किसी प्रकार का सबनेविगेशन भी रखना होगा।

इस पोस्ट में हम कवर करेंगे कि कैसे एक साधारण जेकिल प्लग-इन बनाया जाए जो आपकी पोस्ट या पेज के शीर्षकों से सबनेव लिंक उत्पन्न कर सके।

अवलोकन

मैंने इस परियोजना को निम्नलिखित कार्यों में विभाजित किया है:

एक जेकिल जेनरेटर बनाएं जो साइट के प्रत्येक पृष्ठ पर चलता है।
जनरेटर को सिखाएं कि पृष्ठों को प्री-रेंडर कैसे करें ताकि वह शीर्षक की जानकारी निकाल सके।
उन पृष्ठों को पार्स करने के लिए नोकोगिरी का उपयोग करें जो HTML प्रासंगिक शीर्षकों और सामग्री को निकालते हैं।
सबनेविगेशन रेंडर करें।

नीचे दिए गए उदाहरणों में सभी सबनव लिंक एंकर लिंक हैं। काम करने के इस दृष्टिकोण के लिए, आपको यह सुनिश्चित करना होगा कि आपका मार्कडाउन प्रोसेसर शीर्षकों के लिए आईडी बनाता है। RedCarpet with_toc_data . के साथ विकल्प अच्छी तरह से काम करता है।

एक बुनियादी जेकिल जेनरेटर

कुछ अलग-अलग प्रकार के प्लग-इन हैं जिन्हें आप Jekyll के लिए बना सकते हैं। हम एक जनरेटर बनाने जा रहे हैं।

जेनरेटर केवल वे वर्ग हैं जो Jekyll::Generator . से इनहेरिट करते हैं और जो generate . नामक एक विधि प्रदान करते हैं ।

जेकेल सभी मार्कडाउन फाइलों को लोड करने के बाद जेनरेटर चलाए जाते हैं लेकिन उन फाइलों को एचटीएमएल में बदलने से पहले। एक site ऑब्जेक्ट को जनरेट विधि में पास किया जाता है। और आप साइट ऑब्जेक्ट का उपयोग अपने सभी साइट पृष्ठों, पोस्ट और अन्य संसाधनों तक पहुंचने के लिए कर सकते हैं।

नीचे दिए गए उदाहरण में, हम एक जनरेटर बनाते हैं जो सभी पेजों को लूप करता है और उनके शीर्षक प्रिंट करता है।

class MySubnavGenerator < Jekyll::Generator
  def generate(site)
    site.pages.each do |page|
      puts page.data["title"]
    end
  end
end

हम जेनरेटर के अंदर पेज और साइट डेटा को भी संशोधित कर सकते हैं -- फ्रंट-मैटर से लोड किया गया डेटा और साइट कॉन्फ़िगरेशन फ़ाइल से।

   page.data["title"] += " - modified!"
   site.data["tagline"]

HTML को प्री-रेंडरिंग मार्कडाउन

हम अपने मार्कडाउन दस्तावेज़ों से शीर्षक निकालना चाहते हैं। ऐसा करने का सबसे आसान तरीका है मार्कडाउन को HTML में बदलना और फिर नोकोगिरी जैसे टूल का उपयोग करके HTML को पार्स करना।

क्या यह मुझे थोड़ा गंदा महसूस कराता है? हां। क्या यह थोड़ा धीमा होगा? बिल्कुल। लेकिन चूंकि जैकिल एक स्थिर साइट जनरेटर है, इसलिए मुझे रीयल-टाइम प्रदर्शन के बारे में चिंता करने की ज़रूरत नहीं है। तो मैं बस अपनी नाक पकड़ कर इसे ठीक करने जा रहा हूँ।

यहां, हम प्रत्येक मार्कडाउन पृष्ठ को HTML में बदलने के लिए Jekyll's बिल्ट इन मार्कडाउन रैपर का उपयोग करते हैं।

class MySubnavGenerator < Jekyll::Generator
  def generate(site)
    parser = Jekyll::Converters::Markdown.new(site.config)

    site.pages.each do |page|
      if page.ext == ".md"
        html = parser.convert(page['content'])
        # Do something with the html here
      end
    end
  end
end

Extracting Headings

हमारी नई दस्तावेज़ीकरण साइट के लिए, मैंने तय किया कि प्रत्येक H2 टैग में एक संबंधित सबनेविगेशन लिंक होना चाहिए। इसलिए मैं प्रत्येक पृष्ठ के HTML को पार्स करने के लिए नोकोगिरी का उपयोग करूंगा, फिर मैं पृष्ठ से प्रत्येक H2 टैग निकाल दूंगा।

अभी के लिए, हम केवल H2 की सामग्री और आईडी को स्क्रीन पर प्रिंट करेंगे:

require "nokogiri"

class MySubnavGenerator < Jekyll::Generator
  def generate(site)
    parser = Jekyll::Converters::Markdown.new(site.config)

    site.pages.each do |page|
      if page.ext == ".md"
        doc = Nokogiri::HTML(parser.convert(page['content']))
        doc.css('h2').each do |heading|
          puts "#{ heading.text }: #{ heading['id'] }"
        end
      end
    end
  end
end

अब जब हमारे पास शीर्षक टेक्स्ट और आईडी है तो हम सबनेविगेशन लिंक की एक सूची बना सकते हैं।

हम लिंक की इस सूची को पेज की डेटा विशेषता के रूप में ही स्टोर करेंगे। इस तरह, हम अपने पेज टेम्प्लेट से लिंक्स तक पहुंच सकते हैं।

require "nokogiri"

class MySubnavGenerator < Jekyll::Generator
  def generate(site)
    parser = Jekyll::Converters::Markdown.new(site.config)

    site.pages.each do |page|
      if page.ext == ".md"
        doc = Nokogiri::HTML(parser.convert(page['content']))
        page.data["subnav"] = []
        doc.css('h2').each do |heading|
          page.data["subnav"] << { "title" => heading.text, "url" => [page.url, heading['id']].join("#") }
        end
      end
    end
  end
end

अब, अपने टेम्पलेट में, आप सबनाव के माध्यम से लूप कर सकते हैं और प्रत्येक लिंक प्रदर्शित कर सकते हैं:

{% for item in page.subnav %}
  <a href="{{ item.url }}">{{ item.title }}</a>
{% endfor %}

समस्या निवारण

जैसा कि मैंने पहले उल्लेख किया है, यह सब आपके मार्कडाउन प्रोसेसर पर निर्भर है जो प्रत्येक शीर्षक के लिए अद्वितीय आईडी बनाता है। _config.yml . से मेरी मार्कडाउन सेटिंग यहां दी गई हैं :

# Use the redcarpet Markdown renderer
markdown: redcarpet
redcarpet:
    extensions: [
        'no_intra_emphasis',
        'fenced_code_blocks',
        'autolink',
        'strikethrough',
        'superscript',
        'with_toc_data',
        'tables',
        'hardwrap'
    ]

अगला अप...

उपरोक्त दृष्टिकोण अच्छी तरह से काम करता है यदि आपको केवल एक स्तर के सबनेविगेशन की आवश्यकता है। लेकिन क्या होगा अगर आपको और चाहिए? यानी यदि आप चाहते हैं कि आपके मेनू में सब-सबनेविगेशन लिंक बनाने के लिए H2 के सभी H3 टैग "अंदर" हों?

हम भविष्य के ब्लॉग पोस्ट में इसे और बहुत कुछ कवर करेंगे। तो बने रहें!