راهنما

نگاه اجمالی

MKDOCS یک راه حل سریع و آسان برای تولید وبسایتهای ایستا جهت فراهم آوردن مستندات پروژه است. فایل های مستندات با زبان Markdown نوشته شده و به همراه یک فایل YAML تهیه می شوند.

میزبانی در هر کجا که بخواهید

شما میتوانید این صفحات استاتیک HTML را در صفحات گیت هاب، آمازونS3 و یا هر جای دیگر قرار دهید.

به آسانی سفارشی کنید

با سفارشی کردن قالب ها، نمایش مستندات پروژه تان را به سلیقه خود عوض کنید.

راهنمای نصب

برای نصب MKDOCS در ابتدا لازم است پایتون را به همراه پکیج منجر پایتون - pip ( پکیج منجر در فایل ستاپ پایتون موجود است ) روی سیستم خود نصب کنید.

از طریق دستورات زیر مطمئن شوید که پایتون به درستی روی سیستم نصب شده است.

$ python --version
Python 2.7.2
$ pip --version
pip 1.5.2

MKDOCS از پایتون 2.6، 2.7، 3.3 و 3.4 پشتیبانی می کند.

به کاربران ویندوز پیشنهاد می کنیم برای راه اندازی پایتون و pip از Chocolatey استفاده کنند.

پکیج MKDOCS را با کمک دستور زیر نصب کنید.

pip install mkdocs

پکیج MKDOCS الان باید روی سیستم شما نصب شده باشد.

با کمک دستور mkdocs --version میتوانید مطمئن شوید همه چیز سر جای خودش است.

$ mkdocs --version
mkdocs, version 0.15.2

وقت شروعه

ساختن یک پروژه ساده است.

mkdocs new my-project
cd my-project

بگذارید ببینیم پروژه ای که ساخته ایم، کجاست.

یک فایل تنظیمات با اسم mkdocs.yml و یک فولدر با نام docs که شامل فایل های مستنداتمان است.

در حال حاضر فولدر docs تنها شامل یک فایل index.md است.

MKDOCS به همراه یک وب سرور داخلی در اختیارتان است و به شما این امکان را می دهد همزمان که روی مستندات کار می کنید پیش نمایشی از آن را هم ببینید.

برای استفاده ابتدا به مسیر قرار گرفتن فایل mkdocs.yml بروید و بعد دستور mkdocs serve را اجرا کنید.

$ mkdocs serve
Running at: http://127.0.0.1:8000/

آدرس http://127.0.0.1:8000 را در مروگر باز کنید، صفحه ایندکس برایتان به نمایش در می آید.

این وب سرور از auto-reloading پشتیبانی می کند و در صورت هر گونه تغییر در فایل تنظیمات، دایرکتوری مستندات و یا دایرکتوری قالب، مجددا بازخوانی میشود.

به docs/index.md بروید و ویرایشش کنید. مرورگر رو ریلود کنید و تغییرات صورت گرفته را تماشا کنید.

حال زمان مناسبی ست تا فایل تنظیمات را ویرایش کنید. در mkdocs.yml مقدار site_name را عوض کنید. به محض ریلود صفحه تغییرات اعمال شده را خواهید دید.

اضافه کردن صفحات

به آدرس docs/index.md بروید و تیتر پیش فرض را به MKLorum تغییر دهید. حالا صفحه را مجددا بارگذاری کنید. تغییرات باید اعمال شده باشند.

بیاید یک صفحه به داکیومنت اضافه کنیم.

curl 'jaspervdj.be/lorem-markdownum/markdown.txt' > docs/about.md

برای اضافه کردن نویگیشن باز هم به سراغ فایل تنظیمات می رویم و اطلاعات لازم برای اضافه شدن به هدر را وارد می کنیم.

site_name: My Docs
pages:
- Home: index.md
- About: about.md
theme: basic_theme

کافی ست بار دیگر صفحه را بارگذاری کنید تا ببینید دو مورد Home و About به نویگیشن بار اضافه شده اند.

سایر دستورات

دستورات مختلفی در دسترس هستند که می توانید با وارد کردن دستور زیر از آنها آگاه بشوید.

mkdocs --help

راهنمای نصب قالب Jinks

شما میتوانید به راحتی این قالب را با استفاده از Pip دانلود کنید.

pip install mkdocs-jinks

و برای تغییر تم داکیومت در فایل mkdocs.yml. خط زیر را بیفزایید:

theme: jinks_fa

و سپس همانطور که پیش تر گفته شد با دستور mkdocs serve نتیجه را ببینید.