پروژه mdBook یک ابزار تولید وبسایت از فایل های مارکداون هست که در ابتدا توسط خود تیم توسعه دهنده زبان Rust، برای تولید فایل HTML از مستندات خود Rust نوشته شد اما الان توسط پروژه های مختلف استفاده میشود و یکی از بهترین ابزار های موجود برای تبدیل فایل مارکداون به HTML است.
راه های متفاوتی برای نصب mdBook هست، شما میتوانید فایل های باینری mdBook را از این لینک دانلود کنید و در $PATH قرار بدهید تا از هرجای سیستم، mdBook قابل دسترسی باشد.
اگر هم میخواهید از سورس بیلد بگیرید، به نسخه 1.54 به بالای راست نیاز خواهید داشت و با دستور زیر میتوان mdBook را بیلد و نصب کرد :
cargo install mdbook
اگر هم میخواهید mdBook را از آخرین کامیت مخزن گیت هابش نصب کنید با دستور زیر اینکار قابل انجام است :
cargo install --git https://github.com/rust-lang/mdBook.git mdbook
با دستور زیر، mdBook ساختار پروژه همراه با فایل های مورد نیاز را میسازد :
mdbook init my-first-book
قبل از ساخت کتاب چند سوال پرسیده میشود و پس از پاسخ دادن به سوالات، میتوانید دایرکتوری فعلی را به دایرکتوری ساخته شده تغییر بدهیم :
cd my-first-book
و با دستور زیر، کتاب ما به HTML تبدیل شده و روی یک وب سرور محلی میزبانی میشود(پارامتر open، لینک کتاب را در مرورگر باز میکند) :
mdbook serve --open
در ریشه دایرکتوری کتاب، یک فایل book.toml ساخته میشود که به زبان نشانه گذاری TOML نوشته شده و حاوی تنظیمات پیشفرض هست و معمولا برای شروع به اندازه کافی خوبه و لازم نیست تغییرش بدهیم، در این لینک تنظیمات و گزینه های بیشتر توضیح داده شده است.
این فایل که در دایرکتوری src ساخته میشود، در واقع فهرست کتاب شماست که تمام بخش ها را در بر میگیرد، در زیر یک نمونه اولیه از این فایل آمده است :
# Summary - [Introduction](README.md) - [My First Chapter](my-first-chapter.md) - [Nested example](nested/README.md) - [Sub-chapter](nested/sub-chapter.md)
برای اضافه کردن بخش جدید کافی است لینکی به یک فایل مارکداون موجود در دایرکتوری src ایجاد کنید، اگر mdBook را روی حالت serve اجرا کرده باشید، با ذخیره تغییرات فایل مورد نظر در صورت وجود نداشتن ساخته میشود.
برای نوشتن یک بخش، کافی است فایلی را که برای بخش مورد نظر در فایل summary.md تعیین کردید را در یک کد ادیتور باز کنید و محتوای خود را در آن با فرمت مارکداون بنویسید(برای یادگیری مارکداون از این لینک میتوانید استفاده کنید).
برای گرفتن خروجی از کتاب، کافی است دستور زیر را در ریشه پروژه اجرا کنید :
mdbook build
و هم اکنون کتاب شما در دایرکتوری book، انتظارتان را میکشد!
برای اطلاعات بیشتر میتوانید مستندات mdBook را بررسی کنید :