सुविधाजनक mdbook का मेरा उपयोग - doctoc के साथ -

नमस्ते, मैं अक्षम हूँ। काम में भी, Rust द्वारा आधिकारिक तौर पर दस्तावेज़ बनाने के लिए उपयोग किए जाने वाले Markdown प्रारूप में लिखे जा सकने वाले mdbook का उपयोग करना बहुत अच्छा लगता है, इसलिए मैं अपने उपयोग का तरीका प्रस्तुत करूँगा।

इंस्टॉलेशन

cargo install के साथ इंस्टॉल करें

cargo install mdbook

बाद में उपयोग की जाने वाली सामग्री तालिका बनाने के लिए doctoc इंस्टॉल करें।

sudo npm -g install doctoc

ईमानदारी से कहूँ तो, ऐसा लगता है कि Markdown में स्वचालित रूप से सामग्री तालिका उत्पन्न करने के लिए अन्य कमांड भी हैं, लेकिन मेरा शोध अपर्याप्त है।

प्रारंभिक सेटअप

बस mdbook init चलाएँ

~/git/lets-mdbook$ mdbook init

Do you want a .gitignore to be created? (y/n)
y
What title would you like to give the book? 
test
2024-11-23 22:19:57 [INFO] (mdbook::book::init): Creating a new book with stub content

All done, no errors...](alleycat:[haturatu]:~/git/lets-mdbook$ mdbook init

Do you want a .gitignore to be created? (y/n)
y
What title would you like to give the book? 
test
2024-11-23 22:19:57 [INFO] (mdbook::book::init): Creating a new book with stub content

All done, no errors...
alleycat:[haturatu]:~/git/lets-mdbook$ ls
book  book.toml  src

यहाँ, src में लेख के रूप में .md फ़ाइलें डालें, और जब आप इसे बिल्ड करते हैं, तो यह डिफ़ॉल्ट रूप से book निर्देशिका में आउटपुट होता है।

alleycat:[haturatu]:~/git/lets-mdbook/src$ ls
SUMMARY.md  chapter_1.md](alleycat:[haturatu]:~/git/lets-mdbook$ cat src/
SUMMARY.md    chapter_1.md  
alleycat:[haturatu]:~/git/lets-mdbook$ cat src/SUMMARY.md 
# Summary

- [Chapter 1](./chapter_1.md)

इस src/SUMMARY.md में आप एक सामग्री तालिका बना सकते हैं जो साइडबार में प्रदर्शित होती है।

बिल्ड प्रक्रिया को शेल स्क्रिप्ट के साथ स्वचालित करें और एक अपडेट इतिहास भी बनाएँ

हर बार जब src निर्देशिका अपडेट होती है, तो doctoc कमांड चलाकर mdbook build करना... यह मूर्खतापूर्ण लगता है... मैंने खुद ऐसा सोचा और इसे और बर्दाश्त नहीं कर सका, इसलिए मैंने एक शेल स्क्रिप्ट बनाई ताकि मैं vim खोलते हुए भी कार्यों की एक श्रृंखला चला सकूँ।

#!/bin/bash

pwd | grep "src$" || cd src
doctoc .
sed -i "3d" ./*.md
sed -i "/](\#/d" ./SUMMARY.md
sed -i "8a`date`" ./update.md
cd ..

mdbook build
git add .
git commit -m "wip"
git push

यह pwd | grep "src$" || cd src के साथ, यदि pwd परिणाम में src शामिल है, तो कुछ भी नहीं करता है। यदि नहीं, तो यह cd src पर चला जाता है। ऐसा क्यों किया जा रहा है, इसका कारण यह है कि यदि आप src/*.md को संपादित करते समय :!../build.sh के साथ इस स्क्रिप्ट को चलाते हैं, तो यह src निर्देशिका के भीतर cd करेगा, जो थोड़ा अजीब लगता है, इसलिए मैंने ऐसा किया। वैसे, ऐसा न करने पर भी ऑपरेशन में कोई समस्या नहीं है...। इसके अलावा, यह मानते हुए कि git remote-url सेट किया गया है और git push एक बार किया गया है, update.md इस तरह दिखता है।

<!-- START doctoc generated TOC please keep comment here to allow auto update -->
<!-- DON'T EDIT THIS SECTION, INSTEAD RE-RUN doctoc TO UPDATE -->

- [Update Log](#update-log)

<!-- END doctoc generated TOC please keep comment here to allow auto update -->

# Update Log
2024年 11月 23日 土曜日 22:39:24 JST

sed -i "8adate" ./update.md के साथ, यह स्क्रिप्ट चलने पर 8वीं पंक्ति में एक लॉग के रूप में रहता है। ईमानदारी से कहूँ तो, यदि आप इसे ठीक से करना चाहते हैं, तो git commit के रिटर्न वैल्यू से यह निर्धारित करना कि केवल तभी अपडेट इतिहास में रखा जाए जब कोई कमिट हो, तो यह स्पष्ट रूप से अधिक सुविधाजनक होगा, लेकिन यह एक तात्कालिक स्क्रिप्ट थी, इसलिए कृपया इसे समझें...।

क्या Github Actions का उपयोग करना बेहतर नहीं होगा?

यह बिल्ड प्रक्रिया वास्तव में Actions में भी उपयोग की जा सकती है।
हालाँकि, यदि ऐसा वातावरण है जहाँ uses के साथ अन्य yml संपत्तियों का उपयोग नहीं किया जा सकता है, तो क्या होगा?

यदि आप इसे केवल Github Actions के साथ उपयोग करते हैं तो यह अच्छा हो सकता है, लेकिन यदि आप GitLab को Git सर्वर के रूप में उपयोग कर रहे हैं और github.com की संपत्तियों का उपयोग करने का प्रयास करते हैं, तो यह थोड़ा जटिल हो जाता है (जो स्वाभाविक है...), इसलिए मैंने इस बार ऐसा किया।
वास्तव में, Github का एंटरप्राइज़ संस्करण इस संबंध में काफी परेशानी भरा है...।
एंटरप्राइज़ में एक्शन के उपयोग के बारे में

इसलिए, मैंने सोचा कि मैं इस पर बहुत अधिक भरोसा नहीं कर सकता...। इसलिए मैंने, जो और भी अविश्वसनीय है, इसे एक शेल स्क्रिप्ट में लिखा...।