شروع کار

تست آنلاین

می‌توانید ویت‌پرس را مستقیماً در مرورگر خود در StackBlitz امتحان کنید.

نصب

پیش‌نیازها

• Node.js نسخه 18 یا بالاتر.
• ترمینال برای دسترسی به ویت‌پرس از طریق رابط خط فرمان (CLI).
• ویرایشگر متنی با پشتیبانی از Markdown.
  • VSCode به همراه افزونه رسمی Vue.

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

npm

$ npm add -D vitepress

pnpm

$ pnpm add -D vitepress

yarn

$ yarn add -D vitepress

yarn (pnp)

$ yarn add -D vitepress vue

bun

$ bun add -D vitepress

درباره peer dependency های ناموجود هشدار دریافت می‌کنید؟

اگر از PNPM استفاده می‌کنید، متوجه هشدار peer dependency برای @docsearch/js خواهید شد. این مسئله جلوی عملکرد ویت‌پرس را نمی‌گیرد. اگر می‌خواهید این هشدار را نادیده بگیرید، موارد زیر را به package.json خود اضافه کنید:

"pnpm": {
  "peerDependencyRules": {
    "ignoreMissing": [
      "@algolia/client-search",
      "search-insights"
    ]
  }
}

نکته

ویت‌پرس یک بسته فقط ESM است. از require() برای وارد کردن آن استفاده نکنید و اطمینان حاصل کنید که نزدیک‌ترین package.json شما شامل "type": "module" است، یا پسوند فایل‌های مربوطه خود مانند .vitepress/config.js را به .mjs/.mts تغییر دهید. برای جزئیات بیشتر به راهنمای عیب‌یابی Vite مراجعه کنید. همچنین، در زمینه‌های async CJS می‌توانید از await import('vitepress') استفاده کنید.

Wizard راه‌اندازی

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

npm

$ npx vitepress init

pnpm

$ pnpm vitepress init

yarn

$ yarn vitepress init

bun

$ bun vitepress init

چند سوال ساده از شما پرسیده خواهد شد:

┌  Welcome to VitePress!
│
◇  Where should VitePress initialize the config?
│  ./docs
│
◇  Site title:
│  My Awesome Project
│
◇  Site description:
│  A VitePress Site
│
◆  Theme:
│  ● Default Theme (Out of the box, good-looking docs)
│  ○ Default Theme + Customization
│  ○ Custom Theme
└

Vue به عنوان peer dependency

اگر قصد دارید سفارشی‌سازی‌هایی که از کامپوننت‌ها یا APIهای Vue استفاده می‌کنند را انجام دهید، باید vue را به عنوان dependency نیز نصب کنید.

ساختار فایل‌ها

اگر در حال ساخت یک سایت مستقل ویت‌پرس هستید، می‌توانید سایت را در دایرکتوری فعلی خود (./) بسازید. اما، اگر ویت‌پرس را در یک پروژه موجود به همراه سایر کدهای منبع نصب می‌کنید، توصیه می‌شود سایت را در یک دایرکتوری تودرتو (مثلاً ./docs) بسازید تا از بقیه پروژه جدا باشد.

فرض کنیم که پروژه ویت‌پرس را در ./docs ساخته‌اید، ساختار فایل‌های تولید شده باید به این شکل باشد:

.
├─ docs
│  ├─ .vitepress
│  │  └─ config.js
│  ├─ api-examples.md
│  ├─ markdown-examples.md
│  └─ index.md
└─ package.json

دایرکتوری docs به عنوان ریشه پروژه سایت ویت‌پرس در نظر گرفته می‌شود. دایرکتوری .vitepress محل ذخیره فایل‌های پیکربندی ویت‌پرس، حافظه نهان سرور توسعه، خروجی ساخت و کد سفارشی‌سازی تم اختیاری است.

نکته

به طور پیش‌فرض، ویت‌پرس حافظه نهان سرور توسعه خود را در .vitepress/cache و خروجی ساخت تولیدی را در .vitepress/dist ذخیره می‌کند. اگر از Git استفاده می‌کنید، باید آنها را به فایل .gitignore خود اضافه کنید. این مکان‌ها همچنین قابل پیکربندی هستند.

فایل پیکربندی

فایل پیکربندی (.vitepress/config.js) به شما اجازه می‌دهد جنبه‌های مختلف سایت ویت‌پرس خود را سفارشی کنید، با گزینه‌های پایه‌ای مانند عنوان و توضیحات سایت:

// .vitepress/config.js
export default {
  // گزینه‌های سطح سایت
  title: 'ویت‌پرس',
  description: 'فقط در حال بازی کردن.',

  themeConfig: {
    // گزینه‌های سطح تم
  }
}

همچنین می‌توانید رفتار تم را از طریق گزینه themeConfig پیکربندی کنید. برای جزئیات کامل درباره همه گزینه‌های پیکربندی، به راهنمای پیکربندی مراجعه کنید.

فایل‌های منبع

فایل‌های Markdown خارج از دایرکتوری .vitepress به عنوان فایل‌های منبع در نظر گرفته می‌شوند.

ویت‌پرس از مسیر یابی مبتنی بر فایل استفاده می‌کند: هر فایل .md به یک فایل .html متناظر با همان مسیر کامپایل می‌شود. برای مثال، index.md به index.html کامپایل می‌شود و می‌تواند در مسیر ریشه / سایت ویت‌پرس نتیجه‌گیری شده بازدید شود.

ویت‌پرس همچنین قابلیت تولید URL‌های تمیز، بازنویسی مسیرها و تولید پویا صفحات را فراهم می‌کند. این موارد در راهنمای مسیر یابی پوشش داده خواهند شد.

راه‌اندازی و اجرا

این ابزار باید اسکریپت‌های npm زیر را به package.json شما اضافه کرده باشد اگر اجازه این کار را در طول فرآیند راه‌اندازی داده باشید:

{
  ...
  "scripts": {
    "docs:dev": "vitepress dev docs",
    "docs:build": "vitepress build docs",
    "docs:preview": "vitepress preview docs"
  },
  ...
}

اسکریپت docs:dev یک سرور توسعه محلی با به‌روزرسانی‌های فوری راه‌اندازی می‌کند. آن را با دستور زیر اجرا کنید:

npm

$ npm run docs:dev

pnpm

$ pnpm run docs:dev

yarn

$ yarn docs:dev

bun

$ bun run docs:dev

به جای اسکریپت‌های npm، می‌توانید ویت‌پرس را مستقیماً با دستور زیر اجرا کنید:

npm

$ npx vitepress dev docs

pnpm

$ pnpm vitepress dev docs

yarn

$ yarn vitepress dev docs

bun

$ bun vitepress dev docs

استفاده بیشتر از خط فرمان در مرجع CLI مستند شده است.

سرور توسعه باید در http://localhost:5173 اجرا شود. URL را در مرورگر خود بازدید کنید تا سایت جدید خود را در عمل ببینید!

مراحل بعدی

• برای درک بهتر چگونگی نگاشت فایل‌های markdown به HTML تولید شده، به راهنمای مسیر یابی مراجعه کنید.

• برای کشف بیشتر درباره اینکه چه کارهایی می‌توانید در صفحه انجام دهید، مانند نوشتن محتوای markdown یا استفاده از کامپوننت‌های Vue، به بخش "نوشتن" راهنما مراجعه کنید. یک مکان عالی برای شروع یادگیری درباره افزونه‌های Markdown است.

• برای کشف ویژگی‌های ارائه شده توسط تم پیش‌فرض مستندات، به مرجع پیکربندی تم پیش‌فرض مراجعه کنید.

• اگر می‌خواهید ظاهر سایت خود را بیشتر سفارشی کنید، بررسی کنید که چگونه تم پیش‌فرض را گسترش دهید یا یک تم سفارشی بسازید.

• هنگامی که سایت مستندات شما شکل گرفت، حتماً راهنمای استقرار را بخوانید.