کامپوننت‌های Fumadocs چه کمکی به مستندات شما می‌کنند؟

اگر مقاله «معرفی کامل Fumadocs» را خوانده باشید، می‌دانید که Fumadocs یک فریم‌ورک مستندسازی مبتنی بر React و Next.js است. اما نقطه‌ای که Fumadocs را واقعاً از یک Markdown ساده متمایز می‌کند، مجموعه کامپوننت‌های آماده و واکنش‌گرای آن است؛ قطعاتی که به شما اجازه می‌دهند به‌جای متن خشک، مستنداتی تعاملی، خوانا و حرفه‌ای بسازید.

در این راهنما، به‌صورت کاملاً عملی و با مثال اجرایی، تمام کامپوننت‌های کلیدی Fumadocs — از بلوک‌های کد پیشرفته گرفته تا Callout، Card، Accordion، Steps و Tabs — را قدم‌به‌قدم بررسی می‌کنیم تا از همین امروز بتوانید در پروژه خودتان استفاده‌شان کنید.

چرا از کامپوننت‌های Fumadocs استفاده کنیم؟

• افزایش تعامل کاربر: کامپوننت‌هایی مثل Tabs، Accordion و Steps تجربه‌ای پویاتر نسبت به متن ساده ایجاد می‌کنند.
• بهبود خوانایی و سازمان‌دهی: با Callout، Cards و InlineTOC می‌توانید مطالب را دسته‌بندی و برجسته کنید.
• صرفه‌جویی در زمان توسعه: به‌جای پیاده‌سازی از صفر، از کامپوننت‌های آماده و بهینه استفاده می‌کنید.
• سازگاری با سئو: ساختار معنایی (Semantic HTML) این کامپوننت‌ها به رتبه‌بندی بهتر در گوگل کمک می‌کند.

بلوک‌های کد (Code Blocks) — نمایش زیبا، تعاملی و حرفه‌ای

بلوک‌های کد قلب هر مستند فنی‌اند. در Fumadocs، این بلوک‌ها بسیار فراتر از یک <pre> ساده عمل می‌کنند و امکانات پیشرفته‌ای در اختیارتان می‌گذارند.

امکانات کلیدی بلوک‌های کد در Fumadocs

• هایلایت سینتکس خودکار برای بیش از ۱۰۰ زبان برنامه‌نویسی (با موتور Shiki)
• شماره‌گذاری خطوط با قابلیت شروع از هر عدد دلخواه
• هایلایت کلمات و خطوط خاص با کامنت‌های ساده
• نمایش تفاوت‌ها (Diff) با علامت‌های -- و ++
• قابلیت Twoslash برای نمایش نوع‌های TypeScript به‌صورت تعاملی
• عنوان‌دار کردن بلوک‌ها برای توضیح محتوای کد
• تب‌های چندگانه برای نمایش کد در چند زبان یا حالت مختلف

نحوه استفاده از بلوک کد ساده

برای نمایش یک قطعه کد ساده، کافی است آن را بین سه بک‌تیک (```) قرار دهید و زبان برنامه‌نویسی را مشخص کنید.

console.log('سلام دنیا از Fumadocs!');

` ` `js
console.log('سلام دنیا از Fumadocs!');
` ` `

افزودن عنوان به بلوک کد

با افزودن ویژگی title، می‌توانید برای هر بلوک کد یک برچسب توضیحی قرار دهید؛ به‌ویژه زمانی مفید است که چند قطعه کد مرتبط را کنار هم نشان می‌دهید.

console.log('این یک کد با عنوان است');

` ` `js title="فایل اصلی – index.js"
console.log('این یک کد با عنوان است');
` ` `

شماره‌گذاری خطوط از ابتدا یا هر عدد دلخواه

شماره‌گذاری خطوط به خواننده کمک می‌کند به بخش‌های خاص کد ارجاع دهد. با lineNumbers می‌توانید این ویژگی را فعال کنید و حتی نقطه شروع شماره‌گذاری را تغییر دهید.

const greeting: string = 'Hello World';
console.log(greeting);

function startFromTen() {
  console.log('خط شماره ۱۰');
  return true;
}

هایلایت، دیف و فوکوس — برجسته‌سازی هوشمند

با کامنت‌های خاص می‌توانید بخش‌های مهم کد را برجسته کنید، تغییرات را نشان دهید یا روی یک خط خاص فوکوس کنید. این ویژگی برای آموزش گام‌به‌گام و نمایش تغییرات کد بسیار کاربردی است.

// خط برجسته شده
const component = <div>سلام دنیا</div>; 

// کلمه برجسته شده
<div>Fumadocs</div>

// نمایش تفاوت (diff)
console.log('hewwo'); 
console.log('hello'); 

// فوکوس روی خط
return new ResizeObserver(() => {}); 

` ` `tsx
const component = <div>سلام دنیا</div>; // [!code highlight]
/ / [!code word:Fumadocs]
<div>Fumadocs</div>
console.log('hewwo'); // [!code --]
console.log('hello'); // [!code ++]
return new ResizeObserver(() => {}); // [!code focus]
` ` `

نمایش کد در قالب تب با آیکون

با قرار دادن چند بلوک کد کنار هم و اختصاص یک تب به هرکدام، کاربران به‌راحتی بین نمونه‌های مختلف جابه‌جا می‌شوند. برای هر تب می‌توانید آیکون هم تعیین کنید.

console.log('A');

` ` `ts tab="<Building /> ساختمان"
console.log('A');
` ` `

` ` `ts tab="<RocketIcon /> موشک"
console.log('B');
` ` `

` ` `ts tab="بدون ایکون"
console.log('C');
` ` `

نصب خودکار پکیج‌ها (Auto Package Management)

با سینتکس npm، دستور نصب شما به‌طور خودکار برای چهار پکیج‌منیجر محبوب (npm, pnpm, yarn, bun) نمایش داده می‌شود؛ ویژگی‌ای که برای مستندات کتابخانه‌ها و فریم‌ورک‌ها بسیار کاربردی است.

npm install next -D

` ` `npm
npm install next -D
` ` `

Include کردن فایل‌های دیگر — ماژولار کردن مستندات

با تگ <include> می‌توانید محتوای یک فایل MDX دیگر را دقیقاً در همان نقطه‌ای که قرار می‌دهید درج کنید. این ویژگی به شما اجازه می‌دهد بخش‌های تکراری (هدر، فوتر، توضیحات مشترک) را در یک فایل مجزا نگه دارید و در چند صفحه از آن استفاده کنید.

<include>./include.mdx</include>

Callout — جلب توجه به نکات مهم با رنگ و آیکون

کامپوننت Callout یک جعبه اطلاع‌رسانی زیبا و قابل‌تنظیم است که با رنگ‌بندی و آیکون‌های مختلف، نکات کلیدی، هشدارها، خطاها، موفقیت‌ها یا ایده‌ها را برجسته نشان می‌دهد. استفاده از Callout در بخش‌های حساس مستندات، راهنمایی خواننده را بهبود می‌بخشد.

انواع Callout

<Callout title="نکته (مقدار پیش‌فرض)">
  این یک نکته عمومی است ...
</Callout>

<Callout title="هشدار" type="warn">
  قبل از اعمال تغییرات ...
</Callout>

<Callout title="ارور" type="error">
  این خطا زمانی رخ می‌دهد ...
</Callout>

<Callout title="موفق" type="success">
  عملیات با موفقیت انجام شد ...
</Callout>

Cards و Card — نمایش محتوا به‌صورت کارت‌های تعاملی

کارت‌ها یکی از مؤثرترین روش‌ها برای ارائه لینک‌ها، معرفی ویژگی‌ها، دسته‌بندی مطالب و ایجاد ناوبری بصری هستند. هر کارت می‌تواند آیکون، عنوان، توضیحات و لینک داشته باشد. در صورت نبود لینک، کارت به‌صورت یک جعبه اطلاعاتی ساده عمل می‌کند.

مزایای استفاده از کارت‌ها

• ایجاد ناوبری سریع و جذاب
• تفکیک بصری موضوعات مختلف
• افزایش نرخ کلیک (CTR) در صفحات مستندات
• نمایش اطلاعات به‌صورت خلاصه و منظم

<Cards>
  <Card icon={<RocketIcon />} title="شروع سریع">
    در کمتر از ۵ دقیقه پروژه‌ی خود را راه‌اندازی کنید.
  </Card>
  {/* سایر کارت‌ها ... */}
</Cards>

Accordion و Accordions — مدیریت محتوای طولانی با قابلیت جمع‌شدن

آکاردئون‌ها امکان می‌دهند محتوای حجیم و طولانی را در بخش‌های قابل‌جمع‌شدن قرار دهید. این ویژگی برای سوالات متداول (FAQ)، توضیحات فنی طولانی و مستندات API ایده‌آل است. (نمونه واقعی آن را در بخش «سوالات متداول» همین مقاله می‌بینید.)

تنظیمات مهم

• type="single": فقط یک بخش در هر لحظه باز می‌ماند (بستن خودکار بقیه بخش‌ها)
• type="multiple": چند بخش می‌توانند هم‌زمان باز باشند (پیش‌فرض)

<Accordions type="single">
  <Accordion id="faq-1" value="1" title="چگونه Fumadocs را نصب کنم؟">
    پاسخ توضیحی ...
  </Accordion>
  <Accordion id="faq-2" value="2" title="آیا Fumadocs از RTL پشتیبانی می‌کند؟">
    پاسخ توضیحی ...
  </Accordion>
</Accordions>

Step و Steps — راهنمای گام‌به‌گام برای آموزش‌های مرحله‌ای

وقتی می‌خواهید یک فرآیند یا آموزش را مرحله‌به‌مرحله توضیح دهید، کامپوننت Steps بهترین انتخاب است. هر Step به‌طور خودکار شماره‌گذاری می‌شود و فاصله مناسبی بین مراحل ایجاد می‌کند.

کاربردهای رایج

• آموزش نصب و راه‌اندازی
• راهنمای گام‌به‌گام پیاده‌سازی یک ویژگی
• فرآیندهای عیب‌یابی (Troubleshooting)
• آموزش کدنویسی مرحله‌به‌مرحله

<Steps>
  <Step>
    **مرحله اول: نصب وابستگی‌ها**
    ابتدا با اجرای دستور `npm install` ...
  </Step>
  <Step>
    **مرحله دوم: راه‌اندازی سرور توسعه**
    با دستور `npm run dev` ...
  </Step>
  <Step>
    **مرحله سوم: ایجاد و ویرایش مستندات**
    فایل‌های MDX خود را ...
  </Step>
</Steps>

File، Folder و Files — نمایش ساختار پوشه‌ها و فایل‌ها

این کامپوننت‌ها برای نمایش درخت‌واره دایرکتوری پروژه بسیار مفیدند. با Folder و File می‌توانید پوشه‌ها و فایل‌ها را با قابلیت باز/بسته شدن (defaultOpen) نشان دهید و به خواننده کمک کنید ساختار پروژه را بهتر درک کند.

<Files>
  <Folder name="app" defaultOpen>
    <File name="layout.tsx" />
    <File name="page.tsx" />
  </Folder>
  <Folder name="components">
    <File name="button.tsx" />
  </Folder>
  <File name="package.json" />
</Files>

تصاویر (Image) — نمایش گرافیک، لوگو و بزرگ‌نمایی

برای نمایش تصاویر، از سینتکس استاندارد Markdown استفاده کنید. Fumadocs تصاویر را به‌طور خودکار بهینه می‌کند و در صورت نیاز، قابلیت بزرگ‌نمایی (Zoom) و متن جایگزین (Alt Text) را فراهم می‌کند.

![لوگوی رسمی Mipiboy – برند مستندسازی حرفه‌ای](/mipiboy-logo-white.png)

InlineTOC — فهرست مطالب درون‌خطی برای دسترسی سریع

کامپوننت InlineTOC یک فهرست مطالب کوچک و جمع‌وجور می‌سازد که می‌توانید در هر نقطه از صفحه (معمولاً بالای مقاله) قرار دهید — دقیقاً همان چیزی که در ابتدای همین مقاله دیدید. این ابزار به کاربران کمک می‌کند بدون اسکرول طولانی، به بخش‌های مختلف مقاله دسترسی داشته باشند.

<InlineTOC items={toc}>فهرست مطالب</InlineTOC>

Tabs و Tab — نمایش محتوای چندگانه در تب‌های مجزا

تب‌ها راهی عالی برای ارائه محتوای مرتبط اما مجزا هستند؛ مثلاً کد یک تابع در چند زبان برنامه‌نویسی، یا توضیحات نصب برای چند سیستم‌عامل مختلف — دقیقاً همان الگویی که در سراسر همین مقاله برای نمایش «نمایش/کد» استفاده شده است. با تنظیم updateAnchor، لینک هر تب به‌طور خودکار در آدرس مرورگر به‌روزرسانی می‌شود که برای اشتراک‌گذاری دقیق محتوا بسیار مفید است.

console.log('سلام از Javascript!');

fn main() {
    println!("سلام از Rust!");
}

#include <iostream>
int main() {
    std::cout << "سلام از C++!" << std::endl;
    return 0;
}

<Tabs items={['Javascript', 'Rust', 'C++']} updateAnchor>
  <Tab id="tab-js" value="Javascript">
    ` ` `js
    console.log('سلام از Javascript!');
    ` ` `
  </Tab>
  <Tab id="tab-rs" value="Rust">
    ` ` `rust
    fn main() { println!("سلام از Rust!"); }
    ` ` `
  </Tab>
</Tabs>

کامپوننت‌های تکمیلی و پیشرفته Fumadocs

علاوه بر کامپوننت‌های پرکاربردی که در بالا دیدید، Fumadocs چند کامپوننت تخصصی‌تر هم دارد که در مستندات فنی و پروژه‌های بزرگ‌تر بسیار به‌کار می‌آیند:

<TypeTable
  type={{
    percentage: {
      description: 'درصد موقعیت اسکرول برای نمایش دکمه بازگشت به بالا',
      type: 'number',
      default: 0.2,
    },
  }}
/>

نکات پیشرفته برای بهینه‌سازی مستندات با Fumadocs

رعایت چند نکته کلیدی، کیفیت مستندات شما را چند پله بالا می‌برد:

1. ساختار معنایی Heading: از H1 فقط برای عنوان اصلی صفحه (که خودِ Fumadocs از فرانت‌متر title می‌سازد)، H2 برای بخش‌های اصلی و H3 برای زیربخش‌ها استفاده کنید.
2. لینک‌سازی داخلی و خارجی: با کامپوننت Card به صفحات مرتبط درون سایت و منابع معتبر خارجی ارجاع دهید.
3. Alt Text کامل برای تصاویر: متن جایگزین توصیفی و حاوی کلمه کلیدی، هم به سئو و هم به دسترسی‌پذیری کمک می‌کند.
4. چگالی طبیعی کلمات کلیدی: عباراتی مثل «Fumadocs»، «مستندسازی»، «Next.js»، «MDX» را طبیعی و بدون فشار در متن بگنجانید.
5. به‌روزرسانی مداوم: تاریخ آخرین ویرایش را در صفحه درج کنید و مستندات را هم‌زمان با نسخه‌های جدید Fumadocs به‌روز نگه دارید.

سوالات متداول درباره کامپوننت‌های Fumadocs

جمع‌بندی نهایی و توصیه‌ها

در این راهنما، به‌طور کامل با تمام کامپوننت‌های کلیدی Fumadocs آشنا شدید: از بلوک‌های کد پیشرفته گرفته تا Callout، Card، Accordion، Steps، Files، InlineTOC، Tabs و کامپوننت‌های تخصصی‌تری مثل TypeTable و ImageZoom. هرکدام از این ابزارها با هدف بهبود تجربه کاربری، افزایش تعامل و ساده‌سازی تولید محتوا طراحی شده‌اند.

پیشنهادات عملی برای شروع

1. با یک پروژه کوچک شروع کنید: یک مستند ساده برای یک کتابخانه یا ابزار شخصی بسازید.
2. کامپوننت‌ها را ترکیب کنید: چند کامپوننت را در یک صفحه کنار هم بگذارید تا غنای محتوا بالا برود.
3. روی چند دستگاه تست کنید: مطمئن شوید کامپوننت‌ها در موبایل و دسکتاپ به‌خوبی نمایش داده می‌شوند.
4. از کاربران بازخورد بگیرید: نظر مخاطبان درباره خوانایی و کاربردپذیری مستندات را جویا شوید.

با به‌کارگیری درست این کامپوننت‌ها، مستندات شما هم از نظر فنی غنی‌تر می‌شود و هم رتبه بهتری در موتورهای جستجو کسب می‌کند.

کلمات کلیدی اصلی: Fumadocs, مستندسازی, Next.js, MDX, کامپوننت, بلوک کد, Callout, Card, Accordion, Steps, Tabs, InlineTOC, آموزش, راهنما, سئو

کلمات کلیدی فرعی: نمایش کد, هایلایت, شماره‌گذاری خطوط, دیف, فوکوس, نصب پکیج, کارت تعاملی, فهرست مطالب, ساختار پوشه, TypeTable, ImageZoom, راست‌چین, RTL