Fumadocs چیست و چرا این روزها این‌قدر سر و صدا کرده؟

اگر تا امروز یک بار هم که شده برای یک پروژه، کتابخانه یا محصول نرم‌افزاری خودتان یک سایت مستندات (Documentation Site) ساخته باشید، احتمالاً این حس آشناست: هر بار از صفر شروع می‌کنید، دوباره روی طراحی، جستجو، سایدبار، حالت تاریک/روشن و ده‌ها جزئیات کوچک دیگر وقت می‌گذارید. Fumadocs دقیقاً برای حل همین مسئله ساخته شده است.

Fumadocs یک فریم‌ورک متن‌باز و مدرن مستندسازی مبتنی بر React.js است که توسط توسعه‌دهنده‌ای به نام Fuma Nama ساخته شده و این روزها توسط پروژه‌های شناخته‌شده‌ای مثل Vercel، Orama و Unkey استفاده می‌شود. در این مقاله قرار است بررسی کنیم و ببینیم اصلاً Fumadocs چیست، چه معماری‌ای دارد و چرا این‌قدر بین توسعه‌دهنده‌ها محبوب شده است؛ سپس در مقاله بعدی سراغ «کامپوننت‌های Fumadocs» و نحوه استفاده عملی از آن‌ها خواهیم رفت.

مسئله‌ای که Fumadocs حل می‌کند

اکثر ابزارهای مستندسازی قدیمی‌تر یکی از این دو مشکل را دارند:

• یا خیلی بسته‌اند: یک تم آماده به شما می‌دهند و اگر بخواهید چیزی خارج از چارچوب آن بسازید، باید کل ساختار را دور بزنید.
• یا خیلی خام‌اند: باید همه‌چیز از جستجو گرفته تا رندر MDX را خودتان از صفر پیاده‌سازی کنید.

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

معماری Fumadocs: چرا طراحی لایه‌ای آن مهم است؟

یکی از تفاوت‌های اصلی Fumadocs با رقبایش، معماری کاملاً جداشده و ترکیب‌پذیر (composable) آن است. Fumadocs به‌جای اینکه یک بسته یکپارچه و بزرگ باشد، به چند لایه مستقل تقسیم شده:

ویژگی‌های کلیدی Fumadocs

پشتیبانی کامل از Markdown و MDX

Fumadocs به‌صورت پیش‌فرض هم از Markdown ساده و هم از MDX (سینتکس Markdown به‌علاوه JSX) پشتیبانی می‌کند. یعنی نویسندگان محتوا می‌توانند مثل همیشه با Markdown بنویسند و توسعه‌دهنده‌ها می‌توانند کامپوننت React واقعی داخل محتوا وارد کنند.

• هایلایت سینتکس با موتور Shiki برای بیش از صد زبان برنامه‌نویسی
• گروه‌بندی بلوک‌های کد (Codeblock Group) و نمایش در قالب تب
• Callout، Card و سایر کامپوننت‌های تعاملی آماده
• تولید خودکار فهرست مطالب (Auto Table of Contents)
• قابلیت TypeScript Twoslash برای نمایش تایپ‌ها به‌صورت زنده داخل کدبلاک‌ها

محتوای همیشه به‌روز با React Server Components

یکی از قابلیت‌های متمایزکننده Fumadocs، ترکیب MDX با React Server Components است. این یعنی می‌توانید داخل یک صفحه مستندات، مستقیماً از دیتابیس یا یک CMS داده بخوانید و آن را رندر کنید؛ بدون این‌که مستندات شما ثابت (Static) و از رده خارج بماند.

• نمایش داده زنده از دیتابیس یا API داخل صفحات مستندات
• کامپوننت auto-type-table برای تولید خودکار جدول مستندسازی از روی تایپ‌های TypeScript
• OpenAPI Playground برای تست تعاملی API‌ها مستقیماً از داخل مستندات

فریم‌ورک-اگنوستیک (Framework Agnostic) بودن

برخلاف بسیاری از ابزارهای مشابه که فقط برای یک فریم‌ورک خاص ساخته شده‌اند، Fumadocs به‌صورت رسمی از چند فریم‌ورک React پشتیبانی می‌کند:

جستجوی حرفه‌ای

Fumadocs به‌صورت آماده با موتورهای جستجوی Orama و Algolia یکپارچه می‌شود، بدون این‌که نیاز به پیاده‌سازی جستجو از صفر داشته باشید. برای پروژه‌های کوچک‌تر هم گزینه جستجوی محلی (Local Search) به‌صورت پیش‌فرض کار می‌کند.

شخصی‌سازی مثل شادکن (shadcn/ui for docs)

Fumadocs یک CLI اختصاصی دارد که دقیقاً مثل رویکرد شادکن‌یو‌آی (shadcn/ui) عمل می‌کند: به‌جای این‌که کامپوننت‌ها را به‌صورت یک پکیج بسته دریافت کنید، کد آن‌ها مستقیماً داخل پروژه شما کپی می‌شود تا هر طور که خواستید تغییرش دهید.

npx @fumadocs/cli customize

سازگاری با منابع محتوا و CMS

مستندات همیشه قرار نیست فقط داخل فایل‌های MDX محلی نوشته شوند. Fumadocs طوری طراحی شده که با هر منبع محتوایی کار کند:

• فایل‌های محلی MDX از طریق fumadocs-mdx
• CMSهای هدلس مثل Sanity، Payload CMS و BaseHub
• Content Collections به‌عنوان یک لایه محتوای جایگزین

import { loader } from 'fumadocs-core/source';
import { defineDocs } from 'fumadocs-mdx/macro';

const docs = defineDocs({
  dir: 'content/docs',
});

export const source = loader({
  source: docs.toFumadocsSource(),
  baseUrl: '/docs',
});

نصب و شروع سریع با Fumadocs

راه‌اندازی یک پروژه جدید Fumadocs تنها چند دقیقه طول می‌کشد. کافی است این مراحل را دنبال کنید:

npm create fumadocs-app

---
title: Hello World
---

## سلام دنیا

این اولین صفحه مستندات من با Fumadocs است.

npm run dev

پس از راه‌اندازی، ساختار پروژه شما تقریباً به این شکل خواهد بود:

Fumapress: نسخه ساده‌شده برای غیرمهندسان

اگر تمام این پیکربندی‌ها برای شما زیاد به نظر می‌رسد، Fumadocs یک برادر کوچک‌تر و ساده‌تر به نام Fumapress هم دارد. ایده Fumapress این است که هر ویژگی فقط با یک پلاگین فعال می‌شود؛ بدون نیاز به دانش قبلی از پیکربندی‌های پیچیده.

import { defineConfig } from "fumapress";
import { fumadocsMdx } from "fumapress/adapters/mdx";
import { flexsearchPlugin } from "fumapress/plugins/flexsearch";
import { llmsPlugin } from "fumapress/plugins/llms.txt";
import { docs } from "./.source/server";

export default defineConfig({
  content: {
    docs: docs.toFumadocsSource(),
  },
})
  .plugins(flexsearchPlugin(), llmsPlugin())
  .adapters(fumadocsMdx());

مقایسه Fumadocs با ابزارهای مشابه

مزایا و محدودیت‌های Fumadocs

مزایا:

• طراحی پیش‌فرض بسیار زیبا و مدرن
• معماری ماژولار و کاملاً قابل‌ترکیب
• عملکرد بالا به لطف React Server Components
• جامعه فعال و پروژه‌ای کاملاً متن‌باز

محدودیت‌ها:

• وابستگی کامل به اکوسیستم React (گزینه‌ای برای Vue یا Svelte وجود ندارد)
• برای تیم‌هایی که تجربه کمی با React/Next.js دارند، منحنی یادگیری اولیه محسوس است

سوالات متداول درباره Fumadocs

جمع‌بندی: آیا Fumadocs انتخاب درستی برای شماست؟

Fumadocs یکی از جدی‌ترین گزینه‌ها برای هر تیمی است که با اکوسیستم React/Next.js کار می‌کند و می‌خواهد به‌جای ساختن مستندات از صفر، از قطعات آماده و باکیفیت استفاده کند؛ بدون این‌که مجبور شود از انعطاف‌پذیری و شخصی‌سازی صرف‌نظر کند. معماری لایه‌ای آن، پشتیبانی از React Server Components، و ابزار CLI مشابه shadcn/ui، آن را به یکی از مدرن‌ترین انتخاب‌ها در سال ۲۰۲۶ تبدیل کرده است.

کلمات کلیدی اصلی: Fumadocs, معرفی Fumadocs, فریم‌ورک مستندسازی, Next.js, React, MDX, ساخت سایت مستندات

کلمات کلیدی فرعی: مقایسه Fumadocs, نصب Fumadocs, Fumapress, معماری Fumadocs, headless docs, RTL, راست‌چین