07
مهبستن
پروژه خود را از امروز شروع کنید91307930-021
ساخت مستندات با docs page
- نویسنده : آیسان بهرمند
- ارسال شده در: 9 جولای 2025
- ارسال دیدگاه: 0
فهرست مطالب
docs.page یه ابزار باحاله که بهت کمک میکنه از فایلهای Markdown (همون فایلهای متنی ساده با فرمت .md) یه مستندات شیک و حرفهای بسازی. این ابزار مستقیم به مخزن GitHub وصل میشه و هر تغییری تو فایلهات بدی، خودش آپدیتشون میکنه. تازه، رایگانه و برای پروژههای عمومی حسابی بهدرد میخوره! این راهنما بهت کمک میکنه ساخت مستندات با docs page رو یاد بگیری.
ویژگیهای کلیدی ساخت مستندات با docs page
- بدون نیاز به تنظیمات پیچیده: یه فایل docs.json و یه پوشه docs میسازی. توی پوشه docs، فایلهایی با فرمت .mdx میذاری و docs.page خودش سایت مستنداتت رو میسازه.
- قابل شخصیسازی: میتونی لوگو، لینکهای شبکههای اجتماعی، تم، آنالیتیکس، منوهای ناوبری و چیزای دیگه رو با یه فایل تنظیمات ساده اضافه کنی.
- پیشنمایش زنده: میتونی مستندات رو برای هر شاخه، درخواست کشیدن (pull request) یا کامیت خاص ببینی، که باعث میشه همکاری و بررسی همزمان راحتتر بشه.
- هات ریلود: این قابلیت بهت اجازه میده تغییراتت رو توی فایلهای Markdown (.mdx) همون لحظه ببینی، بدون نیاز به رفرش یا بازسازی دستی.
- ربات گیتهاب: یه ربات گیتهاب داره که بهطور خودکار لینک پیشنمایش مستندات رو برای درخواستهای کشیدن میسازه.
- پشتیبانی از MDX: میتونی مستنداتت رو با Markdown بنویسی و از MDX استفاده کنی تا کامپوننتهای React مثل تبها، کارتها، توییتها و مراحل رو مستقیم توی فایل Markdownت بذاری.
- جستوجو: با DocSearch ادغام شده و قابلیت جستوجوی کامل توی مستندات رو داره.
- طراحی responsive: مستنداتت روی هر دستگاه و اندازه صفحهای خوب به نظر میرسه.
- حالت تیره/روشن: میتونی تم رو بین حالت تیره و روشن عوض کنی.
- هایلایت کد: برای بلوکهای کد، قابلیت هایلایت سینتکس و کپی کردن محتوا داره.
docs.page چطور کار میکنه؟
برای شروع، میتونی با CLI خود docs.page پروژه مستنداتت رو راه بندازی. با این دستور توی ترمینال:
pnpm dlx @docs.page/cli init docs.page
خروجی دستور چیزی شبیه اینه:
pnpm dlx @docs.page/cli init docs.page
? Are you sure you want to setup and install docs.page in /home/officialrajdeepsingh/medium/docs.page? yes
Files created:
– docs.json: Configuration file for your documentation site
– docs/index.mdx: The home page of your documentation site
– docs/next-steps.mdx: A page to help you get started with docs.page
Initialization complete. To preview your documentation site, visit https://docs.page/preview in your browser.
بعد از اجرای این دستور، ساختار پروژهت اینجوری میشه:
.
├── docs
│ ├── index.mdx
│ └── next-steps.mdx
└── docs.json
2 directories, 3 files
پوشه docs شامل فایلهای Markdown برای مستنداتته و فایل docs.json تنظیمات سایتت مثل هدر، سایدبار، لوگو، تم و چیزای دیگه رو داره.
چطور پیشنمایش زنده رو توی docs.page فعال کنیم؟
برای دیدن پیشنمایش زنده ساخت مستندات با docs.page توی مرورگر، نیازی به اجرای دستورات توسعهای روی لپتاپت نداری. کافیه این مراحل رو بری:
برو به سایت docs.page و روی دکمه Local Preview کلیک کن.
پروژه مستنداتت رو از روی لپتاپت انتخاب کن و دکمه Select Directory رو بزن.
یه پنجره جدید باز میشه (بسته به سیستمعاملت ممکنه ظاهرش فرق کنه). پروژهت رو انتخاب کن.
بعدش یه پیام هشدار توی مرورگر میبینی که میگه «آیا اجازه میدی سایت فایلها رو ببینه؟». دکمه View files رو بزن.
حالا میتونی پیشنمایش زنده سایت مستنداتت رو توی مرورگر ببینی و هر تغییری که توی فایلها بدی، همون لحظه توی مرورگر نشون داده میشه. بهطور پیشفرض، سایت مستنداتت باید چیزی شبیه این باشه.
چطور docs.page رو تنظیم کنیم؟
فایل docs.json فایل اصلی برای تنظیمات مستنداتته. این فایل کلی گزینه داره که میتونی باهاش لوگو، تم، آنالیتیکس و چیزای دیگه رو تغییر بدی.
گزینههای اصلی تنظیمات
- ویژگیهای پایه
- لوگو
- تم
- هدر
- لینکهای شبکههای اجتماعی
- سئو
- جستوجو
- تبها
- سایدبار
توی این آموزش، روی مهمترین گزینهها تمرکز میکنیم:
- ویژگیهای پایه
- لوگو
- تم
- هدر
- لینکهای شبکههای اجتماعی
- سئو
- جستوجو
- تبها
- سایدبار
بعداً توی آموزشهای بعدی درباره استفاده از کامپوننتهای آماده، Frontmatter، اضافه کردن فایلهای اضافی و انتشار سایت مستندات بیشتر حرف میزنیم.
ویژگیهای پایه
docs.page یه سری ویژگیهای پایه داره مثل نام، توضیحات و فاوآیکون که برای سئو خیلی مهمان:
- نام (name): اسم پروژهت که توی هدر نشون داده میشه و برای متادیتای سئو استفاده میشه.
- توضیحات (description): یه خلاصه از پروژهت که توی متا تگها و پیشنمایش شبکههای اجتماعی میاد.
- فاوآیکون (favicon): آیکونی که توی تب مرورگر نشون داده میشه. میتونی یه URL ساده بدی یا برای حالت روشن و تیره آیکون جداگونه تعریف کنی:
- light: URL آیکون برای حالت روشن.
- dark: URL آیکون برای حالت تیره.
مثال توی فایل docs.json:
{
“name”: “Docs.page”,
“description”: “مستنداتت رو مثل کد منتشر کن”,
“favicon”: “https://static.invertase.io/assets/docs.page/docs-page-logo.png”
// یا
“favicon”: {
“light”: “https://cdn-icons-png.flaticon.com/24/9664/9664027.png”,
“dark”: “https://cdn-icons-png.flaticon.com/24/9643/9643115.png”
}
}
لوگو
حالا وقتشه لوگوی مستنداتت رو تنظیم کنی که توی هدر و پیشنمایش شبکههای اجتماعی نشون داده میشه. حداقل ارتفاع لوگو باید 24 پیکسل باشه. میتونی برای حالت روشن و تیره لوگوی جداگونه بذاری. اگه فقط یه لوگو بذاری و کار نکنه، ممکنه موقع تغییر تم سایت به مشکل بخوری.
دو روش برای اضافه کردن لوگو:
- روش اول:
{
“name”: “مستندات من”,
“logo”: “https://cdn-icons-png.flaticon.com/24/2702/2702154.png”
}
- روش دوم:
{
“name”: “مستندات من”,
“logo”: {
“light”: “https://cdn-icons-png.flaticon.com/24/2702/2702154.png”,
“dark”: “https://cdn-icons-png.flaticon.com/24/2702/2702172.png”
}
}
تم
تنظیم تم مستندات خیلی سادهست. اگه تم نذاری، تم پیشفرض استفاده میشه. توی فایل docs.json یه شیء theme داری که شامل اینهاست:
- defaultTheme: انتخاب تم (روشن یا تیره).
- primary: رنگ اصلی برای لینکها، دکمهها و چیزای تعاملی.
- primaryLight: رنگ اصلی برای حالت روشن (اگه نذاری، از primary استفاده میشه).
- primaryDark: رنگ اصلی برای حالت تیره (اگه نذاری، از primary استفاده میشه).
- backgroundLight: رنگ پسزمینه برای حالت روشن.
- backgroundDark: رنگ پسزمینه برای حالت تیره.
مثال:
{
“theme”: {
“defaultTheme”: “dark”,
“primary”: “#de40eb”,
“primaryLight”: “#BFA213”,
“backgroundLight”: “#e0cfff”,
“backgroundDark”: “#00101f”
}
}
هدر
برای تنظیم هدر مستنداتت، این گزینهها رو داری:
- showName: نشون دادن اسم مستندات کنار لوگو (پیشفرض: true).
- showThemeToggle: نشون دادن دکمه تغییر تم (پیشفرض: true).
- showGitHubCard: نشون دادن کارت گیتهاب توی هدر (پیشفرض: true).
- links: یه آرایه از لینکها برای منوی ناوبری توی هدر.
مثال:
{
“header”: {
“showName”: false,
“showGitHubCard”: false,
“links”: [
{ “title”: “گیتهاب”, “href”: “https://github.com/officialrajdeepsingh/docs-page-demo” },
{ “title”: “ایکس”, “href”: “https://x.com/Official_R_deep” },
{ “title”: “لینکدین”, “href”: “https://www.linkedin.com/in/officalrajdeepsingh” }
]
}
}
لینکهای شبکههای اجتماعی
گزینه social یه شیء از جفتهای کلید-مقداره که کلیدش اسم پلتفرم اجتماعیه و مقدارش نام کاربری یا آیدی. مثال:
{
“social”: {
“github”: “officialrajdeepsingh/docs-page-demo”,
“x”: “@Official_R_deep”,
“linkedin”: “officalrajdeepsingh”
}
}
سئو
گزینه noindex به موتورهای جستوجو میگه که مستنداتت رو ایندکس نکنن (پیشفرض: false).
{
“noindex”: true
}
جستوجو
برای فعال کردن جستوجو، میتونی Algolia DocSearch رو با تنظیم شیء docsearch توی docs.json ادغام کنی:
{
“search”: {
“docsearch”: {
“appId”: “YOUR_APP_ID”,
“apiKey”: “YOUR_API_KEY”,
“indexName”: “YOUR_INDEX_NAME”
}
}
}
تبها
تبها یه آرایه از اشیاء هستن که بالای سایت مستندات نشون داده میشن. هر تب این ویژگیها رو داره:
- id: شناسه منحصربهفرد.
- title: متن روی تب.
- href: لینک موقع کلیک.
- locale (اختیاری): اگه تنظیم بشه، تب فقط برای زبان خاص نشون داده میشه.
مثال:
{
“tabs”: [
{ “id”: “root”, “title”: “مستندات”, “href”: “/” },
{ “id”: “components”, “title”: “کامپوننتها”, “href”: “/components” }
]
}
سایدبار
برای نمایش سایدبار توی سایت، میتونی توی docs.json تنظیمش کنی. سایدبار یه لیست از لینکهاست که کنار مستندات نشون داده میشه. میتونی لینکها رو با گروهها و صفحهها سازماندهی کنی.
گزینهها
- pages: لیست لینکهای صفحهها.
- title: عنوان آیتم سایدبار.
- href: لینک موقع کلیک.
- icon (اختیاری): آیکون کنار آیتم.
- group (اختیاری): گروهی که آیتم زیرش نشون داده میشه.
- tab (اختیاری): آیتم فقط وقتی تب خاصی فعاله نشون داده میشه.
مثال:
{
“sidebar”: [
{
“pages”: [
{ “title”: “بررسی اجمالی”, “href”: “/”, “icon”: “book” },
{ “title”: “تنظیمات”, “href”: “/configuration”, “icon”: “gear” }
]
},
{
“group”: “کامپوننتها”,
“icon”: “grip”,
“pages”: [
{ “title”: “شروع”, “href”: “/components”, “icon”: “rocket” },
{ “title”: “آکاردئون”, “href”: “/components/accordion”, “icon”: “square-caret-down” },
{ “title”: “کالاوتها”, “href”: “/components/callouts”, “icon”: “bullhorn” },
{ “title”: “کارتها”, “href”: “/components/cards”, “icon”: “square-full” }
]
}
]
}
استفاده از کامپوننتهای آماده
docs.page 15 تا کامپوننت آماده داره که نیازی به ایمپورتشون توی فایل MDX نیست. مستقیم میتونی ازشون استفاده کنی. مثلاً کامپوننت Info Callout:
—
title: به docs.page خوش اومدی!
description: با docs.page شروع کن
—
به docs.page خوش اومدی! دستوری که اجرا کردی یه ساختار فایل اولیه برای پروژهت ساخته.
## راهنما
### تنظیمات
توی ریشه پروژهت یه فایل `docs.json` ساخته شده که برای تنظیم سایت مستنداتته. میتونی اسم، توضیحات، سایدبار، تم، لوگو و چیزای دیگه رو باهاش تنظیم کنی.
<Info>یه مثال ساده از فایل: </Info>
پیدا کردن خطاها
اگه توی سایت مستنداتت خطایی دیدی، با کلیک روی دکمه diagnostics میتونی همه خطاها رو ببینی.
استفاده از Frontmatter
Frontmatter یه بلوک YAMLه که اول فایل Markdown میاد و بین سه تا خط تیره (—) قرار میگیره. برای تنظیم متادیتای صفحه و سئو استفاده میشه.
مثال:
—
title: به پروژه عالی خوش اومدی
description: یه مستندات باحال!
—
# خوش اومدی!
ویژگیهای مهم Frontmatter
- title: عنوان صفحه برای متادیتا، کارتهای اجتماعی و سرصفحه.
- description: خلاصه صفحه برای سئو و پیشنمایش لینک.
- image: URL تصویر برای کارتهای اجتماعی و بالای صفحه.
- redirect: URL برای ریدایرکت (محتوای صفحه نادیده گرفته میشه).
- showPageTitle: نشون دادن عنوان صفحه بهعنوان هدر (بولین).
- showPageImage: نشون دادن تصویر Frontmatter بالای صفحه.
- noindex: اگه true باشه، موتورهای جستوجو صفحه رو ایندکس نمیکنن.
اضافه کردن فایلهای اضافی (Assets)
میتونی توی مستنداتت از تصاویر و ویدیوها استفاده کنی، چه بهصورت ریموت و چه لوکال.
فایلهای ریموت
برای فایلهای ریموت، مستقیم URL رو توی فایل Markdown میذاری:
—
title: خوش اومدی
description: یه مستندات باحال!
—
# خوش اومدی!
فایلهای لوکال
برای فایلهای لوکال، یه پوشه assets توی پوشه docs بساز و تصاویر یا ویدیوها رو اونجا بذار. بعد توی فایل Markdown با مسیر نسبی بهشون ارجاع بده:
docs/
assets/
natural.png
index.mdx
توی فایل Markdown:
تفاوت لوکال و ریموت
- لوکال: فایلها (PNG، JPG، PDF و غیره) توی پوشه عمومی پروژهت ذخیره میشن و با URL دامنهت در دسترسن.
- ریموت: فایلها روی سرور خارجی (مثل Unsplash، Pixabay) ذخیره شدن و با URL کامل استفاده میشن.
مثال فایل ریموت:
هر کدوم مزایا و معایب خودشون رو دارن. فایلهای ریموت رو میتونی مستقیم توی MDX بذاری، ولی برای لوکال باید فایل رو توی پوشه عمومی بذاری و بعد ارجاع بدی.
انتشار سایت مستندات
با docs.page، انتشار سایت مستندات خیلی سادهست و نیازی به تنظیمات خاصی نداره. کافیه کدهای لوکالت رو به یه مخزن گیتهاب push کنی. بعدش سایتت فوراً از طریق دامنه docs.page در دسترسه.
مثلاً اگه مخزنت officialrajdeepsingh/docs-page-demo باشه، مستنداتت توی این آدرس در دسترسه: https://docs.page/officialrajdeepsingh/docs-page-demo
پیشنمایش تغییرات آینده
برای دیدن پیشنمایش تغییرات قبل از انتشار، میتونی از اپلیکیشن گیتهاب docs.page استفاده کنی. هر pull request که توی مخزنت بسازی، یه URL پیشنمایش زنده منحصربهفرد میسازه.
برای تنظیم اپلیکیشن گیتهاب:
- برو به https://github.com/apps/docs-page.
- روی دکمه Install کلیک کن.
- اکانت گیتهابت رو انتخاب کن.
- همه مخازن یا یه مخزن خاص رو انتخاب کن.
- روی Install کلیک کن.
- رمز عبور و OTP رو وارد کن.
اگه نصب موفق باشه، هر وقت pull request بسازی، اپلیکیشن docs.page یه پیشنمایش زنده برات درست میکنه.
نتیجهگیری
docs.page یه پروژه متنباز رایگانه که بهت اجازه میده ساخت مستندات با docs.page سریع، زیبا و بدون نیاز به تنظیمات پیچیده بسازی. به نظرم بهترین راهحل برای مستنداته. با سرویس ابری docs.page میتونی بهراحتی سایت مستنداتت رو راهاندازی و منتشر کنی.
فعلاً کاملاً رایگانه و امیدوارم همینطور بمونه. اگه یه روز پولی بشه، امیدوارم راهنمای واضحی برای انتشار روی پلتفرمهای دیگه بدن.
بیشتر بخوانید: “TIBCO Spotfireچیست؟“
دیدگاه بگذارید