mdbook ব্যবহারের আমার সুবিধাজনক পদ্ধতি - doctoc সহ -

নমস্কার, আমি অযোগ্য।
কাজের ক্ষেত্রেও, Rust দ্বারা আনুষ্ঠানিকভাবে ব্যবহৃত Markdown ফরম্যাটে ডকুমেন্ট লেখার জন্য mdbook ব্যবহার করা খুবই আরামদায়ক, তাই আমি এটি কীভাবে ব্যবহার করি তা আপনাদের সাথে শেয়ার করব।

ইনস্টলেশন

cargo install দিয়ে ইনস্টল করুন

cargo install mdbook

পরে ব্যবহারের জন্য বিষয়বস্তু তালিকা (table of contents) তৈরির জন্য 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-এর এন্টারপ্রাইজ সংস্করণ এই দিক থেকে বেশ ঝামেলাপূর্ণ...।
এন্টারপ্রাইজে অ্যাকশন ব্যবহার সম্পর্কে

সুতরাং, আমি ভাবলাম যে এটি খুব নির্ভরযোগ্য নয়...। তাই আমি, যে আরও কম নির্ভরযোগ্য, একটি শেল স্ক্রিপ্টে এটি লিখেছিলাম...।