Mkdocs, इस ओपन सोर्स सॉफ़्टवेयर के लिए प्रलेखन धन्यवाद बनाएँ

अगले लेख में हम Mkdocs पर एक नज़र डालने जा रहे हैं। यदि आप सॉफ्टवेयर विकसित करना चाहते हैं प्रलेखन बनाने के लिए एक मंच आपकी एक परियोजना के लिए। या यदि आप किसी ऐसी कंपनी में काम करते हैं जिसे कर्मचारियों के लिए आंतरिक दस्तावेज बनाने की आवश्यकता है। भले ही आप एक उन्नत उपयोगकर्ता हैं जो कुछ नोट्स सहेजना चाहते हैं। MkDocs एक उपकरण है जिसे आपको आज़माना चाहिए।

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

आगे हम देखेंगे कि MkDocs का उपयोग करके एक पूर्ण प्रलेखन वेबसाइट प्राप्त करना कितना आसान है। कई अन्य हैं साइट जनरेटर इसी तरह स्थिर, लेकिन यह कॉन्फ़िगरेशन और कार्यान्वयन सबसे सरल है.

एक सामान्य उपयोगकर्ता भी इस सॉफ़्टवेयर का उपयोग कर सकता है नोट्स लेने के लिए एक स्थानीय प्लेटफ़ॉर्म बनाएं खुद के लिए या इसी तरह के कुछ भी।

MkDocs स्थापित करें

स्थानीय रूप से स्थापित करें

आइए देखें कि MkDocs स्थापित करना काफी आसान है। हम कर सकते हैं पाइप का उपयोग करके इसे स्थापित करें। आपको बस एक टर्मिनल (Ctrl + Alt + T) खोलना होगा और उसमें लिखना होगा:

pip install mkdocs

स्थापना के बाद, अपनी कार्यशील निर्देशिका में, निम्न कमांड को चलाएं एक साइट को इनिशियलाइज़ करें:

mkdocs new mkdocspro

और फिर इसकी सेवा शुरू करें Daud:

cd mkdocspro

mkdocs serve

तब आप कर सकते हो लोकलहोस्ट पर जाएं: 8000 (या पोर्ट 8000 के साथ आपका IP पता / होस्टनाम) यह देखने के लिए कि MkDocs कैसे काम करता है।

अपने nginx सर्वर पर स्थापित करें

चूंकि यह एक स्थिर साइट जनरेटर है, PHP या अजगर की तरह कोई बैकएंड इंजन की जरूरत नहीं है। आप MkDocs प्रोजेक्ट को अपने वेब सर्वर (nginx, apache2) पर एक मिनट में लागू कर सकेंगे। उदाहरण के लिए, यहाँ है nginx वर्चुअल होस्ट कॉन्फ़िगरेशन:

server {
        server_name ejemplo.com;

        root /var/www/mkdocspro/sitio;
        index index.html;

        location / {
                try_files $uri $uri/ =404;
        }
}

के स्थान पर example.com डोमेन के साथ आपके सर्वर पर है। आपको भी बदलना पड़ेगा / var / www / mkdocspro / साइट अपने सर्वर पर साइट के सबफ़ोल्डर के रास्ते से। तब हमारे पास केवल है नग्नेक्स पुनः आरंभ करें निम्नलिखित आदेश के साथ:

sudo service nginx restart

अब आप example.com पर जा सकते हैं और इसे देख सकते हैं।

Mkdocs में एक और थीम स्थापित करें

डिफ़ॉल्ट Mkdocs विषय विशेष रूप से अच्छा नहीं है। लेकिन आप एक मिनट में एक और स्थापित कर सकते हैं। एक अन्य विषय की स्थापना का एक उदाहरण, निम्नलिखित होगा। जिसके साथ हम जा रहे हैं सामग्री विषय स्थापित करें:

pip install mkdocs-material

स्थापना के बाद, विषय को सक्रिय करने के लिए, आपको करना होगा अपनी mkdocs.yml फ़ाइल को संपादित करें और इसे इसके समान बनाएं। कुछ विकल्प जोड़े जा सकते हैं:

site_name: Proyecto MkDocs
site_url: 'http://ejemplo.com'
repo_url: 'https://github.com/nombreusuario/proyectourlongithub'
edit_uri: edit/master
site_description: 'Aquí una descripción corta.'
google_analytics: ['UA-xxxxxxxxx-x', 'ejemplo.com']
extra:
  favicon: 'https://ejemplo/favicon.png'
  social:
    - type: 'github'
      link: 'https://github.com/xxxxxx'
    - type: 'facebook'
      link: 'https://facebook.com/xxxxxxx'
    - type: 'twitter'
      link: 'https://twitter.com/xxxxxxx'
  disqus: 'minombredisqus'
  theme: 'material'

विकल्प काफी स्पष्ट हैं। लेकिन यहां कुछ स्पष्टीकरण दिए गए हैं:

• रेपो_यूआरएल: है Git रिपॉजिटरी URL। यदि आप Git को सीधे अपने MkDocs प्रोजेक्ट में एकीकृत करने की योजना बनाते हैं, तो आप इस विकल्प का उपयोग करके लोगों को पृष्ठ संपादित कर सकते हैं या प्रोजेक्ट को कांटा कर सकते हैं।
• संपादित करें: यह है GitHub पर पृष्ठों के संपादन के लिए उपसर्ग। आप इसे बदल सकते हैं यदि आप GitLab या GitBucket का उपयोग कर रहे हैं।
• गूगल विश्लेषिकी: MkDocs का कोई कंट्रोल पैनल नहीं है। इसलिए जानना है जो आपकी वेबसाइट पर जाता है, आपको Google Analytics का उपयोग करना चाहिए। यह विकल्प आपको अपने खाते को वेबसाइट के साथ जोड़ने के लिए अपना ट्रैकिंग नंबर डालने की अनुमति देगा।
• Disqus: अगर तुम चाहते हो Disqus टिप्पणी प्रणाली सक्षम करें वेबसाइट पर, आप अपना संक्षिप्त नाम यहां डाल सकते हैं।
• विषय: द उस थीम का नाम जिसे आप उपयोग करना चाहते हैं। आपको इसे पहले स्थापित करना होगा, जैसा कि हमने अभी सामग्री विषय के साथ किया था। यह वह नाम होगा जिसका हम उदाहरण में उपयोग करेंगे।

नए विषय के परिवर्तन देखें

फ़ाइल सहेजने के बाद, mkdocsproject फ़ोल्डर के अंदर mkdocs बनाएँ। आपकी वेबसाइट सामग्री विषय के डिफ़ॉल्ट रूप और अनुभव को अपनाएगी:

महत्वपूर्ण: हर संशोधन के बाद हमेशा mkdocs बनाने के लिए सुनिश्चित करें जो आप फ़ाइलों में करते हैं। अन्यथा आपको कोई परिवर्तन नहीं दिखेगा।

देखते हैं अन्य थीम और विकल्प इस सॉफ़्टवेयर को कॉन्फ़िगर करने के लिए। आप उनसे परामर्श ले सकते हैं आधिकारिक दस्तावेज MkDocs द्वारा। यहाँ की एक सूची है संभव विकल्प हम उपयोग कर सकते हैं।