docs: add Persian language (#4089)

Co-authored-by: Divyansh Singh <40380293+brc-dd@users.noreply.github.com>
pull/4423/head
Amirhossein Alibakhshi 2 weeks ago committed by GitHub
parent 08ce34d9a2
commit a3f994b71e
No known key found for this signature in database
GPG Key ID: B5690EEEBB952194

@ -0,0 +1,8 @@
{
"plugins": {
"postcss-rtlcss": {
"ltrPrefix": ":where([dir=\"ltr\"])",
"rtlPrefix": ":where([dir=\"rtl\"])"
}
}
}

@ -0,0 +1,223 @@
import { createRequire } from 'module'
import { defineConfig, type DefaultTheme } from 'vitepress'
const require = createRequire(import.meta.url)
const pkg = require('vitepress/package.json')
export const fa = defineConfig({
title: 'ویت‌پرس',
lang: 'fa-IR',
description: 'Vite & Vue powered static site generator.',
dir: 'rtl',
markdown: {
container: {
tipLabel: 'نکته',
warningLabel: 'هشدار',
dangerLabel: 'خطر',
infoLabel: 'اطلاعات',
detailsLabel: 'جزئیات'
}
},
themeConfig: {
nav: nav(),
sidebar: {
'/fa/guide/': { base: '/fa/guide/', items: sidebarGuide() },
'/fa/reference/': { base: '/fa/reference/', items: sidebarReference() }
},
editLink: {
pattern: 'https://github.com/vuejs/vitepress/edit/main/docs/:path',
text: 'ویرایش این صفحه در گیت‌هاب'
},
footer: {
message: 'انتشار یافته تحت لایسنس MIT',
copyright: 'حق نسخه‌برداری © 2019-کنون Evan You'
},
docFooter: {
prev: 'قبلی',
next: 'بعدی'
},
outline: {
label: 'در این صفحه'
},
lastUpdated: {
text: 'آخرین به‌روزرسانی‌',
formatOptions: {
dateStyle: 'short',
timeStyle: 'medium'
}
},
langMenuLabel: 'تغییر زبان',
returnToTopLabel: 'بازگشت به بالا',
sidebarMenuLabel: 'منوی جانبی',
darkModeSwitchLabel: 'تم تاریک',
lightModeSwitchTitle: 'رفتن به حالت روشن',
darkModeSwitchTitle: 'رفتن به حالت تاریک',
notFound: {
linkLabel: 'بازگشت به خانه',
linkText: 'بازگشت به خانه',
title: 'صفحه مورد نظر یافت نشد',
code: '۴۰۴',
quote:
'اما اگر جهت خود را تغییر ندهید و اگر ادامه دهید به دنبال چیزی که دنبال می‌کنید، ممکن است در نهایت به جایی که در حال رفتن به سمتش هستید، برسید.'
},
siteTitle: 'ویت‌پرس'
}
})
function nav(): DefaultTheme.NavItem[] {
return [
{
text: 'راهنما',
link: 'fa/guide/what-is-vitepress',
activeMatch: '/guide/'
},
{
text: 'مرجع',
link: 'fa/reference/site-config',
activeMatch: '/reference/'
},
{
text: pkg.version,
items: [
{
text: 'Changelog',
link: 'https://github.com/vuejs/vitepress/blob/main/CHANGELOG.md'
},
{
text: 'مشارکت',
link: 'https://github.com/vuejs/vitepress/blob/main/.github/contributing.md'
}
]
}
]
}
function sidebarGuide(): DefaultTheme.SidebarItem[] {
return [
{
text: 'معرفی',
collapsed: false,
items: [
{ text: 'ویت‌پرس چیست؟', link: 'what-is-vitepress' },
{ text: 'شروع کار', link: 'getting-started' },
{ text: 'مسیریابی', link: 'routing' },
{ text: 'استقرار', link: 'deploy' }
]
},
{
text: 'نوشتن',
collapsed: false,
items: [
{ text: 'افزونه‌های Markdown', link: 'markdown' },
{ text: 'مدیریت منابع', link: 'asset-handling' },
{ text: 'Frontmatter', link: 'frontmatter' },
{ text: 'استفاده از Vue در Markdown', link: 'using-vue' },
{ text: 'بین‌المللی سازی', link: 'i18n' }
]
},
{
text: 'شخصی‌سازی',
collapsed: false,
items: [
{ text: 'استفاده از تم شخصی', link: 'custom-theme' },
{
text: 'گسترش تم پیش‌فرض',
link: 'extending-default-theme'
},
{ text: 'بارگیری داده در زمان Build', link: 'data-loading' },
{ text: 'سازگاری SSR', link: 'ssr-compat' },
{ text: 'اتصال به CMS', link: 'cms' }
]
},
{
text: 'آزمایشی',
collapsed: false,
items: [
{ text: 'حالت MPA', link: 'mpa-mode' },
{ text: 'جنریت کردن Sitemap', link: 'sitemap-generation' }
]
},
{ text: 'پیکربندی و مرجع API', base: 'fa/reference/', link: 'site-config' }
]
}
function sidebarReference(): DefaultTheme.SidebarItem[] {
return [
{
text: 'مرجع',
base: 'fa/reference/',
items: [
{ text: 'پیکربندی Site', link: 'site-config' },
{ text: 'پیکربندی Frontmatter', link: 'frontmatter-config' },
{ text: 'Runtime API', link: 'runtime-api' },
{ text: 'CLI', link: 'cli' },
{
text: 'تم پیش‌فرض',
base: 'fa/reference/default-theme-',
items: [
{ text: 'بررسی اجمالی', link: 'config' },
{ text: 'ناوبری', link: 'nav' },
{ text: 'نوار کنار صفحه', link: 'sidebar' },
{ text: 'صفحه اصلی', link: 'home-page' },
{ text: 'پاورقی', link: 'footer' },
{ text: 'طرح', link: 'layout' },
{ text: 'نشان', link: 'badge' },
{ text: 'صفحه تیم', link: 'team-page' },
{ text: 'لینک‌های قبلی / بعدی', link: 'prev-next-links' },
{ text: 'ویرایش لینک', link: 'edit-link' },
{ text: 'Timestamp آخرین به‌روزرسانی', link: 'last-updated' },
{ text: 'جستجو', link: 'search' },
{ text: 'تبلیغات Carbon', link: 'carbon-ads' }
]
}
]
}
]
}
export const search: DefaultTheme.AlgoliaSearchOptions['locales'] = {
fa: {
placeholder: 'جستجوی مستندات',
translations: {
button: {
buttonText: 'جستجو',
buttonAriaLabel: 'جستجو'
},
modal: {
searchBox: {
resetButtonTitle: 'آغاز مجدد جستجو',
resetButtonAriaLabel: 'آغاز مجدد جستجو',
cancelButtonText: 'لغو',
cancelButtonAriaLabel: 'لغو'
},
startScreen: {
recentSearchesTitle: 'جستجو‌های اخیر',
noRecentSearchesText: 'تاریخچه جستجویی یافت نشد.',
saveRecentSearchButtonTitle: 'ذخیره تاریخچه جستجو',
removeRecentSearchButtonTitle: 'حذف تاریخچه جستجو',
favoriteSearchesTitle: 'موارد دلخواه',
removeFavoriteSearchButtonTitle: 'حذف مورد دلخواه'
},
errorScreen: {
titleText: 'نتیجه‌ای یافت نشد برای',
helpText: 'اتصال شبکه خود را بررسی کنید'
},
footer: {
selectText: 'انتخاب',
navigateText: 'رفتن',
closeText: 'بستن',
searchByText: ' جستجو با '
},
noResultsScreen: {
noResultsText: 'نتیجه‌ای یافت نشد برای'
}
}
}
}
}

@ -6,6 +6,7 @@ import { pt } from './pt'
import { ru } from './ru'
import { es } from './es'
import { ko } from './ko'
import { fa } from './fa'
export default defineConfig({
...shared,
@ -15,6 +16,7 @@ export default defineConfig({
pt: { label: 'Português', ...pt },
ru: { label: 'Русский', ...ru },
es: { label: 'Español', ...es },
ko: { label: '한국어', ...ko }
ko: { label: '한국어', ...ko },
fa: { label: 'فارسی', ...fa }
}
})

@ -4,6 +4,7 @@ import { search as ptSearch } from './pt'
import { search as ruSearch } from './ru'
import { search as esSearch } from './es'
import { search as koSearch } from './ko'
import { search as faSearch } from './fa'
export const shared = defineConfig({
title: 'VitePress',
@ -67,7 +68,8 @@ export const shared = defineConfig({
...ptSearch,
...ruSearch,
...esSearch,
...koSearch
...koSearch,
...faSearch
}
}
},

@ -0,0 +1,63 @@
# مدیریت منابع {#asset-handling}
## ارجاع به منابع ایستا {#referencing-static-assets}
تمام فایل‌های Markdown به کامپوننت‌های Vue تبدیل و توسط [Vite](https://vitejs.dev/guide/assets.html) پردازش می‌شوند. شما می‌توانید، **و باید**، هر نوع دارایی را با استفاده از URLهای نسبی مرجع قرار دهید:
```md
![تصویر](./image.png)
```
شما می‌توانید منابع ایستا را در فایل‌های Markdown خود، کامپوننت‌های `*.vue` در قالب، استایل‌ها و فایل‌های `.css` ساده، با استفاده از مسیرهای عمومی مطلق (براساس ریشه پروژه) یا مسیرهای نسبی (براساس سیستم فایل شما) ارجاع دهید. روش دوم مشابه رفتاری است که در صورت استفاده از Vite، Vue CLI یا `file-loader` webpack با آن آشنا هستید.
انواع شایع تصویر، رسانه و فایل فونت به طور خودکار شناسایی و به عنوان منابع درج می‌شوند.
::: tip فایل‌های لینک شده به عنوان دارایی محسوب نمی‌شوند
PDFها یا سند‌های دیگر که از طریق پیوندها در فایل‌های Markdown ارجاع داده شده‌اند به طور خودکار به عنوان دارایی در نظر گرفته نمی‌شوند. برای دسترسی به فایل‌های لینک شده، باید آن‌ها را به صورت دستی در دایرکتوری [`public`](#the-public-directory) پروژه قرار دهید.
:::
تمام منابع ارجاع داده شده، شامل آن‌هایی که از مسیرهای مطلق استفاده می‌کنند، در مرحله تولید به دایرکتوری خروجی با نام فایلی بر اساس یک هش کپی خواهند شد. دارایی‌هایی که هرگز ارجاع نداده شوند، کپی نخواهند شد. منابع تصویر کوچک‌تر از 4 کیلوبایت به صورت base64 درون خطی می‌شوند - این می‌تواند از طریق گزینه پیکربندی [`vite`](../reference/site-config#vite) تنظیم شود.
تمام ارجاع‌های مسیر **ایستا**، شامل مسیرهای مطلق، باید بر اساس ساختار دایرکتوری کاری شما تعیین شوند.
## دایرکتوری عمومی {#the-public-directory}
گاهی اوقات ممکن است نیاز داشته باشید منابع ایستا را فراهم کنید که به صورت مستقیم در هیچ‌یک از Markdown یا کامپوننت‌های قالب شما ارجاع نشده‌اند، یا ممکن است بخواهید برخی فایل‌ها را با نام اصلی خود سرویس دهید. به عنوان مثال، فایل‌هایی مانند `robots.txt`، آیکون‌های fav، و آیکون‌های PWA.
شما می‌توانید این فایل‌ها را در دایرکتوری `public` تحت [دایرکتوری منبع](./routing#source-directory) قرار دهید. به عنوان مثال، اگر ریشه پروژه شما `./docs` است و از محل پیش‌فرض دایرکتوری منبع استفاده می‌کنید، آنگاه دایرکتوری عمومی شما `./docs/public` خواهد بود.
منابع قرار داده شده در `public` به صورت اصلی در ریشه دایرکتوری خروجی کپی خواهند شد.
توجه داشته باشید که باید به فایل‌های قرار داده شده در `public` با استفاده از مسیر مطلق ریشه ارجاع دهید - به عنوان مثال، `public/icon.png` همیشه باید به عنوان `/icon.png` در کد منبع ارجاع داده شود.
## URL پایه {#base-url}
اگر وب‌سایت شما به URL غیر ریشه استقرار می‌یابد، باید گزینه `base` را در `.vitepress/config.js` تنظیم کنید. به عنوان مثال، اگر قصد دارید وب‌سایت خود را به `https://foo.github.io/bar/` استقرار دهید، آنگاه `base` باید به `'/bar/'` تنظیم شود (همیشه باید با یک خط شروع و پایان یابد).
تمام مسیرهای دارایی ایستا شما به صورت خودکار پردازش می‌شوند تا با ارزش‌های `base` مختلف تطبیق یابند. به عنوان مثال، اگر به یک ارجاع مطلق به یک دارایی زیر `public` در Markdown خود اشاره کرده‌اید:
```md
![تصویر](/image-inside-public.png)
```
در این حالت، شما **نیازی ندارید** که آن را به روز کنید وقتی که مقدار پیکربندی `base` را تغییر می‌دهید.
اما، اگر شما در حال نویسندگی یک کامپوننت قالب هستید که به صورت پویا به منابع لینک می‌دهد، به عنوان مثال یک تصویر که `src` آن براساس مقدار پیکربندی قالب است:
```vue
<img :src="theme.logoPath" />
```
در این حالت، توصیه می‌شود که مسیر را با استفاده از کمکی [`withBase`](../reference/runtime-api#withbase) ارائه شده توسط ویت‌پرس بپوشانید:
```vue
<script setup>
import { withBase, useData } from 'vitepress'
const { theme } = useData()
</script>
<template>
<img :src="withBase(theme.logoPath)" />
</template>
```

@ -0,0 +1,56 @@
---
outline: deep
---
# اتصال به یک سیستم مدیریت محتوا (CMS) {#connecting-to-a-cms}
## گام‌های کلی {#general-workflow}
اتصال ویت‌پرس به یک سیستم مدیریت محتوا به طور عمده بر اساس [مسیریابی پویا](./routing#dynamic-routes) خواهد بود. حتماً قبل از شروع، با روش کار آن آشنا شوید.
از آنجایی که هر سیستم مدیریت محتوا به طریقی متفاوت کار می‌کند، در اینجا تنها می‌توانیم یک جریان کاری عمومی را ارائه دهیم که شما باید آن را برای حالت خاص خودتان سفارشی کنید.
1. اگر سیستم مدیریت محتوا نیاز به احراز هویت دارد، یک فایل `.env` برای ذخیره توکن‌های API خود ایجاد کنید و آن را بارگذاری کنید:
```js
// posts/[id].paths.js
import { loadEnv } from 'vitepress'
const env = loadEnv('', process.cwd())
```
2. داده‌های مورد نیاز را از سیستم مدیریت محتوا بازیابی کرده و به شکل داده‌های مسیر مناسب فرمت کنید:
```js
export default {
async paths() {
// از کتابخانه مشتری مربوط به سیستم مدیریت محتوا استفاده کنید اگر نیاز دارید
const data = await (await fetch('https://my-cms-api', {
headers: {
// توکن در صورت لزوم
}
})).json()
return data.map(entry => {
return {
params: { id: entry.id, /* عنوان، نویسندگان، تاریخ و غیره */ },
content: entry.content
}
})
}
}
```
3. نمایش محتوا در صفحه:
```md
# {{ $params.title }}
- نوشته شده توسط {{ $params.author }} در تاریخ {{ $params.date }}
<!-- @content -->
```
## راهنماهای ادغام {#integration-guides}
اگر راهنمایی درباره ادغام ویت‌پرس با یک سیستم مدیریت محتوا خاص نوشته‌اید، لطفاً از لینک "ویرایش این صفحه" زیر استفاده کنید تا آن را ارسال کنید!

@ -0,0 +1,226 @@
---
outline: deep
---
# استفاده از یک تم سفارشی {#using-a-custom-theme}
## Resolve کردن تم {#theme-resolving}
می‌توانید با ایجاد یک فایل `.vitepress/theme/index.js` یا `.vitepress/theme/index.ts` (فایل ورودی تم) تم سفارشی را فعال کنید:
```
.
├─ docs # ریشه پروژه
│ ├─ .vitepress
│ │ ├─ theme
│ │ │ └─ index.js # ورودی تم
│ │ └─ config.js # فایل پیکربندی
│ └─ index.md
└─ package.json
```
وقتی ویت‌پرس حضور یک فایل ورودی تم را شناسایی کند، همواره از تم سفارشی به جای تم پیش‌فرض استفاده می‌کند. با این حال، شما می‌توانید [تم پیش‌فرض را گسترش دهید](./extending-default-theme) تا سفارشی‌سازی‌های پیشرفته‌تری را روی آن اعمال کنید.
## رابط تم {#theme-interface}
یک تم سفارشی ویت‌پرس به عنوان یک شی تعریف می‌شود که شامل رابط زیر است:
```ts
interface Theme {
/**
* کامپوننت لایه‌ی ریشه برای هر صفحه
* @required
*/
Layout: Component
/**
* تقویت نمونه Vue اپلیکیشن
* @optional
*/
enhanceApp?: (ctx: EnhanceAppContext) => Awaitable<void>
/**
* گسترش یک تم دیگر، با فراخوانی `enhanceApp` آن پیش از ما
* @optional
*/
extends?: Theme
}
interface EnhanceAppContext {
app: App // نمونه Vue اپلیکیشن
router: Router // نمونه روتر ویت‌پرس
siteData: Ref<SiteData> // متادیتاهای سطح سایت
}
```
فایل ورودی تم باید تم را به عنوان export پیش‌فرض خود export کند:
```js
// .vitepress/theme/index.js
// شما می‌توانید فایل‌های Vue را مستقیماً در ورودی تم وارد کنید
// ویت‌پرس با @vitejs/plugin-vue پیش‌تنظیم شده است.
import Layout from './Layout.vue'
export default {
Layout,
enhanceApp({ app, router, siteData }) {
// ...
}
}
```
export پیش‌فرض تنها قراردادی برای یک تم سفارشی است و تنها ویژگی `Layout` لازم است. بنابراین، به شیء تم ویت‌پرس می‌توان به عنوان یک کامپوننت Vue ساده ترتیب داد.
درون کامپوننت لایه‌ی خود، دقیقاً مانند یک برنامه Vite + Vue 3 عادی عمل می‌کند. با این وجود، توجه داشته باشید که تم همچنین باید [سازگار با SSR](./ssr-compat) باشد.
## ساخت یک لایه {#building-a-layout}
بیشترین لایه‌ی پایه‌ای نیازمند دارای یک کامپوننت `<Content />` است:
```vue
<!-- .vitepress/theme/Layout.vue -->
<template>
<h1>طرح سفارشی!</h1>
<!-- اینجا محتوای markdown نمایش داده می‌شود -->
<Content />
</template>
```
لایه‌ی بالا به سادگی تمام محتوای markdown هر صفحه را به عنوان HTML نمایش می‌دهد. اولین بهبودی که می‌توانیم اعمال کنیم، مدیریت خطاهای 404 است:
```vue{1-4,9-12}
<script setup>
import { useData } from 'vitepress'
const { page } = useData()
</script>
<template>
<h1>طرح سفارشی!</h1>
<div v-if="page.isNotFound">
صفحه 404 سفارشی!
</div>
<Content v-else />
</template>
```
کمک‌کننده [`useData()`](../reference/runtime-api#usedata) اطلاعات اجرایی مورد نیاز ما را برای رندر شرایطی صفحات مختلف فراهم می‌کند. یکی از دیگر اطلاعاتی که ما می‌توانیم به آن دسترسی داشته باشیم، اطلاعات اولیه صفحه فعلی است. ما می‌توانیم از این اطلاعات برای اجازه دادن به کاربر برای کنترل لایه در هر صفحه استفاده کنیم. به عنوان مثال، کاربر می‌تواند مشخص کند که صفحه باید از یک طرح صفحه خانه خاص استفاده کند با:
```md
---
layout: home
---
```
و ما می‌توانیم تم خود را تنظیم کنیم تا با این موضوع برخورد کند:
```vue{3,12-14}
<script setup>
import { useData } from 'vitepress'
const { page, frontmatter } = useData()
</script>
<template>
<h1>طرح سفارشی!</h1>
<div v-if="page.isNotFound">
صفحه 404 سفارشی!
</div>
<div v-if="frontmatter.layout === 'home'">
صفحه خانه سفارشی!
</div>
<Content v-else />
</template>
```
طبیعتا، شما می‌توانید لایه‌ی خود را به کامپوننت‌های بیشتری تقسیم کنید:
```vue{3-5,12-15}
<script setup>
import { useData } from 'vitepress'
import NotFound from './NotFound.vue'
import Home from './Home.vue'
import Page from './Page.vue'
const { page, frontmatter } = useData()
</script>
<template>
<h1>طرح سفارشی!</h1>
<NotFound v-if="page.isNotFound" />
<Home v-if="frontmatter.layout === 'home'" />
<Page v-else /> <!-- <Page /> با `<Content />` را نمایش می‌دهد -->
</template>
```
برای همه چیزی که در کامپوننت‌های تم موجود است، به [مستندات API اجرایی](../reference/runtime-api) مراجعه کنید. به علاوه، شما می‌توانید از [بارگذاری داده در زمان ساخت](./data-loading) استفاده کنید تا لایه‌های مبتنی بر داده را تولید کنید - به عنوان مثال، یک صفحه که تمام پست‌های وبلاگ در پروژه فعلی را لیست می‌کند.
## توزیع یک تم سفارشی {#distributing-a-custom-theme}
آسان‌ترین روش برای توزیع یک تم سفارشی ارائه آن به عنوان [قالب مخزن در GitHub](https://docs.github.com/en/repositories/creating-and-managing-repositories/creating-a-template-repository) است.
اگر می‌خواهید تم را به عنوان یک بسته npm توزیع کنید، مراحل زیر را دنبال کنید:
1. شیء تم را به عنوان export پیش‌فرض در ورودی بسته‌تان export کنید.
2. اگر امکان دارد، تعریف نوع پیکربندی تم خود را به عنوان `ThemeConfig` export کنید.
3. اگر تم شما نیاز به تنظیم پیکربندی ویت‌پرس دارد، پیکربندی را تحت یک زیر‌مسیر بسته (مانند `my-theme/config`) export کنید تا کاربر بتواند آن را گسترش دهد.
4. گزینه‌های پیکربندی تم را مستند کنید (هم از طریق فایل پیکربندی و هم از طریق frontmatter).
5. دستورالعمل‌های روشنی برای مصرف تم خود ارائه دهید (مانند زیر).
## مصرف یک تم سفارشی {#consuming-a-custom-theme}
برای مصرف یک تم خارجی، آن را از ورودی تم سفارشی وارد و دوباره export کنید:
```js
// .vitepress/theme/index.js
import Theme from 'awesome-vitepress-theme'
export default Theme
```
اگر تم نیاز به گسترش دارد:
```js
// .vitepress/theme/index.js
import Theme from 'awesome-vitepress-theme'
export default {
extends: Theme,
enhanceApp(ctx) {
// ...
}
}
```
اگر تم نیاز به پیکربندی خاص ویت‌پرس دارد، شما همچنین باید آن را در پیکربندی خود گسترش دهید:
```ts
// .vitepress/config.ts
import baseConfig from 'awesome-vitepress-theme/config'
export default {
// گسترش پیکربندی پایه‌ی تم (اگر لازم باشد)
extends: baseConfig
}
```
سرانجام، اگر تم انواع خود را برای پیکربندی تم‌اش ارائه می‌دهد:
```ts
// .vitepress/config.ts
import baseConfig from 'awesome-vitepress-theme/config'
import { defineConfigWithTheme } from 'vitepress'
import type { ThemeConfig } from 'awesome-vitepress-theme'
export default defineConfigWithTheme<ThemeConfig>({
extends: baseConfig,
themeConfig: {
// نوع `ThemeConfig` است
}
})
```

@ -0,0 +1,250 @@
# بارگذاری داده در زمان ساخت {#build-time-data-loading}
ویت‌پرس یک ویژگی به نام **بارگذارهای داده** ارائه می‌دهد که به شما این امکان را می‌دهد که داده‌های دلخواه را بارگیری کنید و آن‌ها را از صفحات یا اجزا وارد کنید. بارگذاری داده فقط **در زمان ساخت** اجرا می‌شود: داده‌های حاصل به صورت JSON در بسته JavaScript نهایی سریالیزه می‌شوند.
بارگذارهای داده می‌توانند برای بارگیری داده‌های از راه دور یا تولید فراداده‌ها بر اساس فایل‌های محلی استفاده شوند. به عنوان مثال، می‌توانید از بارگذارهای داده استفاده کنید تا تمام صفحات API محلی خود را تجزیه کنید و به طور خودکار یک فهرست از تمام ورودی‌های API تولید کنید.
## استفاده ابتدایی {#basic-usage}
یک فایل بارگذار داده باید با `.data.js` یا `.data.ts` پایان یابد. فایل باید یک صادرات پیش‌فرض از یک شی با متد `load()` داشته باشد:
```js
// example.data.js
export default {
load() {
return {
hello: 'world'
}
}
}
```
ماژول بارگذار فقط در Node.js ارزیابی می‌شود، بنابراین شما می‌توانید API ‌های Node و وابستگی‌های npm را به عنوان نیازهای خود وارد کنید.
سپس می‌توانید داده را از این فایل در صفحات `.md` و اجزا `.vue` با استفاده از صادرات نام‌گذاری شده `data` وارد کنید:
```vue
<script setup>
import { data } from './example.data.js'
</script>
<pre>{{ data }}</pre>
```
خروجی:
```json
{
"hello": "world"
}
```
شما متوجه خواهید شد که بارگذار داده خودش داده را صادر نمی‌کند. ویت‌پرس پشت صحنه متد `load()` را فراخوانی می‌کند و به طور ضمنی نتیجه را از طریق صادرات نام‌گذاری شده `data` ارائه می‌دهد.
این کار حتی اگر بارگذار async باشد انجام می‌شود:
```js
export default {
async load() {
// دریافت داده از راه دور
return (await fetch('...')).json()
}
}
```
## داده از فایل‌های محلی {#data-from-local-files}
وقتی نیاز به تولید داده بر اساس فایل‌های محلی دارید، باید از گزینه `watch` در بارگذار داده استفاده کنید تا تغییرات اعمال شده به این فایل‌ها بتواند به روزرسانی‌های سریع منجر شود.
گزینه `watch` همچنین در آنجا مفید است که می‌توانید از [الگوهای glob](https://github.com/mrmlnc/fast-glob#pattern-syntax) برای تطابق با چندین فایل استفاده کنید. الگوها می‌توانند نسبت به فایل بارگذار خود نسبی باشند و تابع `load()` فایل‌های تطابق یافته را به عنوان مسیرهای مطلق دریافت می‌کند.
مثال زیر نشان می‌دهد که چگونه فایل‌های CSV را بارگذاری کرده و آن‌ها را با استفاده از [csv-parse](https://github.com/adaltas/node-csv/tree/master/packages/csv-parse/) به JSON تبدیل می‌کند. این فایل تنها در زمان ساخت اجرا می‌شود، بنابراین شما نیازی به ارسال پارسر CSV به مشتری ندارید!
```js
import fs from 'node:fs'
import { parse } from 'csv-parse/sync'
export default {
watch: ['./data/*.csv'],
load(watchedFiles) {
// watchedFiles یک آرایه از مسیرهای مطلق فایل‌های تطابق یافته خواهد بود.
// تولید یک آرایه از فراداده‌های پست وبلاگ که می‌تواند برای نمایش
// یک لیست در طرح استفاده شود
return watchedFiles.map((file) => {
return parse(fs.readFileSync(file, 'utf-8'), {
columns: true,
skip_empty_lines: true
})
})
}
}
```
## `createContentLoader` {#createcontentloader}
وقتی که در حال ساختن یک سایت متمرکز بر محتوا هستیم، اغلب نیاز به ایجاد یک "بایگانی" یا "فهرست" صفحه داریم: یک صفحه که ما همه ورودی‌های موجود در مجموعه محتوای خود را لیست می‌کنیم، به عنوان مثال پست‌های وبلاگ یا صفحات API. ما می‌توانیم این کار را مستقیماً با API بارگذار داده انجام دهیم، اما از آنجا که این یک حالت استفاده رایج است، ویت‌پرس همچنین یک کمک‌کننده به نام `createContentLoader` را فراهم می‌کند تا این فرآیند را ساده‌تر کند:
```js
// posts.data.js
import { createContentLoader } from 'vitepress'
export default createContentLoader('posts/*.md', /* گزینه‌ها */)
```
کمک‌کننده یک الگوی glob را نسبت به [دایرکتوری منبع](./routing#source-directory) مشخص می‌کند و یک شی `{ watch، load }` را که می‌تواند به عنوان صادرات پیش‌فرض در یک فایل بارگذار داده استفاده شود، برمی‌گرداند. همچنین پیاده‌سازی حافظه پنهانی بر اساس برچسب‌های تغییر مدیریت
می‌کند تا عملکرد توسعه را بهبود بخشد.
لطفاً توجه داشته باشید که بارگذار فقط با فایل‌های Markdown کار می‌کند - فایل‌های غیر-Markdown تطابق یافته حذف می‌شوند.
داده بارگذاری شده یک آرایه با نوع `ContentData[]` خواهد بود:
```ts
interface ContentData {
// آدرس URL برای صفحه. به عنوان مثال /posts/hello.html (شامل پایه نمی‌شود)
// تکرار دستی یا استفاده از `transform` سفارشی برای نرمال کردن مسیرها
url: string
// اطلاعات frontmatter صفحه
frontmatter: Record<string, any>
// موارد زیر فقط وقتی که گزینه‌های مربوط فعال باشند
// ما در زیر آنها را بررسی می‌کنیم
src: string | undefined
html: string | undefined
excerpt: string | undefined
}
```
به طور پیش‌فرض، تنها `url` و `frontmatter` ارائه می‌شوند. این به خاطر این است که داده بارگذاری شده به عنوان JSON در بسته مشتری نهایی درج می‌شود، بنابراین ما باید در مورد اندازه آن محتاط باشیم. در زیر مثالی از استفاده از داده برای ساخت یک صفحه فهرست کمینه وبلاگ آورده شده است:
```vue
<script setup>
import { data as posts } from './posts.data.js'
</script>
<template>
<h1>همه پست‌های وبلاگ</h1>
<ul>
<li v-for="post of posts">
<a :href="post.url">{{ post.frontmatter.title }}</a>
<span>توسط {{ post.frontmatter.author }}</span>
</li>
</ul>
</template>
```
### گزینه‌ها {#options}
احتمالاً داده پیش‌فرض به تمام نیازها پاسخ نمی‌دهد - شما می‌توانید با استفاده از گزینه‌ها به تبدیل داده‌ها مشترک شوید:
```js
// posts.data.js
import { createContentLoader } from 'vitepress'
export default createContentLoader('posts/*.md', {
includeSrc: true, // آیا منبع اصلی مارک‌داون را اضافه کنیم؟
render: true, // آیا صفحه HTML را نیز شامل کنیم؟
excerpt: true, // آیا خلاصه را نیز شامل کنیم؟
transform(rawData) {
// نقشه‌برداری، مرتب‌سازی یا فیلتر کردن داده‌های اصلی به دلخواه.
// نتیجه نهایی آنچه است که به مشتری ارسال خواهد شد.
return rawData.sort((a, b) => {
return +new Date(b.frontmatter.date) - +new Date(a.frontmatter.date)
}).map((page) => {
page.src // منبع اصلی مارک‌داون
page.html // صفحه HTML کامل
page.excerpt // خلاصه HTML (محتوای بالای اولین `---`)
return {/* ... */}
})
}
})
```
بررسی کنید که چگونه در [وبلاگ Vue.js](https://github.com/vuejs/blog/blob/main/.vitepress/theme/posts.data.ts) استفاده شده است.
API `createContentLoader` همچنین می‌تواند در داخل [هوک‌های ساخت](../reference/site-config#build-hooks) استفاده شود:
```js
// .vitepress/config.js
export default {
async buildEnd() {
const posts = await createContentLoader('posts/*.md').load()
// تولید فایل‌های بر اساس فراداده‌های پست‌ها، مثلاً فید RSS
}
}
```
**انواع**
```ts
interface ContentOptions<T = ContentData[]> {
/**
* آیا منبع اصلی را اضافه کنیم؟
* @default false
*/
includeSrc?: boolean
/**
* آیا منبع را به HTML تبدیل کرده و در داده شامل کنیم؟
* @default false
*/
render?: boolean
/**
* اگر `boolean` باشد، آیا باید خلاصه را تجزیه و شامل کنیم؟ (به صورت HTML)
*
* اگر `function` باشد، کنترل نحوه استخراج خلاصه از محتوا.
*
* اگر `string` باشد، تعیین کنید که چگونه جداکننده سفارشی باید برای استخراج خلاصه استفاده شود.
* جداکننده پیش‌فرض `---` است اگر `excerpt` `true` باشد.
*
* @see https://github.com/jonschlinkert/gray-matter#optionsexcerpt
* @see https://github.com/jonschlinkert/gray-matter#optionsexcerpt_separator
*
* @default false
*/
excerpt?:
| boolean
| ((file: { data: { [key: string]: any }; content: string; excerpt?: string }, options?: any) => void)
| string
/**
* تبدیل داده. توجه داشته باشید که داده به عنوان JSON در بسته مشتری درج خواهد شد
* اگر از اجزا یا فایل‌های مارک‌داون وارد شود.
*/
transform?: (data: ContentData[]) => T | Promise<T>
}
```
## بارگذارهای داده تایپ شده {#typed-data-loaders}
زمان استفاده از TypeScript، می‌توانید بارگذار و صادرات `data` خود را به این شکل تایپ کنید:
```ts
import { defineLoader } from 'vitepress'
export interface Data {
// نوع داده
}
declare const data: Data
export { data }
export default defineLoader({
// گزینه‌های بارگذاری با تایپ چک شده
watch: ['...'],
async load(): Promise<Data> {
// ...
}
})
```
## پیکربندی {#configuration}
برای دریافت اطلاعات پیکربندی در داخل یک بارگذار، می‌توانید از کدی مانند زیر استفاده کنید:
```ts
import type { SiteConfig } from 'vitepress'
const config: SiteConfig = (globalThis as any).VITEPRESS_CONFIG
```

@ -0,0 +1,337 @@
---
outline: deep
---
# استقرار وب‌سایت ویت‌پرس شما {#deploy-your-vitepress-site}
راهنماهای زیر بر اساس برخی فرضیات مشترک است:
- وب‌سایت ویت‌پرس در دایرکتوری `docs` پروژه شما قرار دارد.
- شما از دایرکتوری خروجی پیش‌فرض ساخته‌شده (`.vitepress/dist`) استفاده می‌کنید.
- ویت‌پرس به‌عنوان یک وابستگی محلی در پروژه شما نصب شده است و شما اسکریپت‌های زیر را در `package.json` پیکربندی کرده‌اید:
```json
{
"scripts": {
"docs:build": "vitepress build docs",
"docs:preview": "vitepress preview docs"
}
}
```
## ساخت و تست محلی {#build-and-test-locally}
1. برای ساخت اسناد، این دستور را اجرا کنید:
```sh
$ npm run docs:build
```
2. پس از ساخت، آن را به‌صورت محلی پیش‌نمایش دهید با اجرای این دستور:
```sh
$ npm run docs:preview
```
دستور `preview` یک سرور وب ایستا محلی راه‌اندازی می‌کند که دایرکتوری خروجی `.vitepress/dist` را در آدرس `http://localhost:4173` ارائه می‌دهد. شما می‌توانید از این امکان استفاده کنید تا اطمینان حاصل کنید که همه چیز قبل از رفع به محیط تولیدی به‌درستی نمایش داده می‌شود.
3. می‌توانید پورت سرور را با انتقال `--port` به‌عنوان یک آرگمان پیکربندی کنید.
```json
{
"scripts": {
"docs:preview": "vitepress preview docs --port 8080"
}
}
```
حالا اسکریپت `docs:preview` سرور را در `http://localhost:8080` راه‌اندازی خواهد کرد.
## تنظیم مسیر پایه عمومی {#setting-a-public-base-path}
به‌طور پیش‌فرض، ما فرض می‌کنیم که وب‌سایت در مسیر ریشه دامنه (`/`) انتشار می‌یابد. اگر وب‌سایت شما باید در یک زیرمسیر ارائه شود، مانند `https://mywebsite.com/blog/`، در این صورت باید گزینه [`base`](../reference/site-config#base) را به `'/blog/'` در پیکربندی ویت‌پرس تنظیم کنید.
**مثال:** اگر از صفحات GitHub (یا GitLab) استفاده می‌کنید و به `user.github.io/repo/` انتشار می‌دهید، آنگاه `base` را به `/repo/` تنظیم کنید.
## سربرگ‌های حافظه نهان HTTP {#http-cache-headers}
اگر شما کنترلی بر روی سربرگ‌های HTTP در سرور تولیدی خود دارید، می‌توانید سربرگ‌های `cache-control` را پیکربندی کنید تا بهبود عملکرد در بازدیدهای تکراری داشته باشید.
بسیاری از فایل‌های ایستا (مانند JavaScript، CSS و سایر فایل‌های وارد شده که در `public` نیستند) از نام‌های فایل با هش استفاده می‌کنند. اگر پیش‌نمایش تولیدی را با استفاده از تب شبکه ابزارهای توسعه مرورگر خود بررسی کنید، فایل‌هایی مانند `app.4f283b18.js` را خواهید دید.
این هش `4f283b18` از محتوای این فایل تولید شده است. اگر محتوا تغییر کند، URLها نیز تغییر می‌کنند. این به این معنی است که می‌توانید برای این فایل‌ها سربرگ‌های حافظه نهان قدرتمند را استفاده کنید. همه این فایل‌ها در زیردایرکتوری `assets/` در دایرکتوری خروجی قرار می‌گیرند، بنابراین می‌توانید برای آن‌ها سربرگ زیر را پیکربندی کنید:
```
Cache-Control: max-age=31536000,immutable
```
::: details مثال فایل `_headers` برای Netlify
```
/assets/*
cache-control: max-age=31536000
cache-control: immutable
```
توجه: فایل `_headers` باید در [دایرکتوری عمومی](./asset-handling#the-public-directory) قرار گیرد - در این مورد، `docs/public/_headers` - تا کپی شود بطور صحیح به دایرکتوری خروجی.
[مستندات سربرگ‌های سفارشی Netlify](https://docs.netlify.com/routing/headers/)
:::
::: details پیکربندی مثال Vercel در `vercel.json`
```json
{
"headers": [
{
"source": "/assets/(.*)",
"headers": [
{
"key": "Cache-Control",
"value": "max-age=31536000, immutable"
}
]
}
]
}
```
توجه: فایل `vercel.json` باید در ریشه مخزن شما قرار گیرد.
[مستندات Vercel در مورد پیکربندی سربرگ‌ها](https://vercel.com/docs/concepts/projects/project-configuration#headers)
:::
## راهنمای‌های پلتفرم {#platform-guides}
### Netlify / Vercel / Cloudflare Pages / AWS Amplify / Render {#netlify-vercel-cloudflare-pages-aws-amplify-render}
یک پروژه جدید راه‌اندازی کرده و این تنظیمات را با استفاده از داشبورد خود تغییر دهید:
- **دستور ساخت:** `npm run docs:build`
- **دایرکتوری خروجی:** `docs/.vitepress/dist`
- **نسخه Node:** `18` (یا بالاتر)
::: warning هشدار
گزینه‌هایی مانند _Auto Minify_ را برای کد HTML فعال نکنید. این گزینه‌ها ممکن است توضیحاتی را که به Vue معنا دارد، از خروجی حذف کنند. ممکن است خطاهای ناسازگاری را در اجرا ببینید اگر حذف شوند.
:::
### صفحات GitHub {#github-pages}
1. یک فایل به نام `deploy.yml` در دایرکتوری `.github/workflows` پروژه خود ایجاد کنید با محتوایی مانند زیر:
```yaml
# Sample workflow for building and deploying a ویت‌پرس site to GitHub Pages
#
name: Deploy ویت‌پرس site to Pages
on:
# Runs on pushes targeting the `main` branch. Change this to `master` if you're
# using the `master` branch as the default branch.
push:
branches: [main]
# Allows you to run this workflow manually from the Actions tab
workflow_dispatch:
# Sets permissions of the GITHUB_TOKEN to allow deployment to GitHub Pages
permissions:
contents: read
pages: write
id-token: write
# Allow only one concurrent deployment, skipping runs queued between the run in-progress and latest queued.
# However, do NOT cancel in-progress runs as we want to allow these production deployments to complete.
concurrency:
group: pages
cancel-in-progress: false
jobs:
# Build job
build:
runs-on: ubuntu-latest
steps:
- name: Checkout
uses: actions/checkout@v4
with:
fetch-depth: 0 # Not needed if lastUpdated is not enabled
# - uses: pnpm/action-setup@v3 # Uncomment this if you're using pnpm
# - uses: oven-sh/setup-bun@v1 # Uncomment this if you're using Bun
- name: Setup Node
uses: actions/setup-node@v4
with:
node-version: 20
cache: npm # or pnpm / yarn
- name: Setup Pages
uses: actions/configure-pages@v4
- name: Install dependencies
run: npm ci # or pnpm install / yarn install / bun install
- name: Build with ویت‌پرس
run: npm run docs:build # or pnpm docs:build / yarn docs:build / bun run docs:build
- name: Upload artifact
uses: actions/upload-pages-artifact@v3
with:
path: docs/.vitepress/dist
# Deployment job
deploy:
environment:
name: github-pages
url: ${{ steps.deployment.outputs.page_url }}
needs: build
runs-on: ubuntu-latest
name: Deploy
steps:
- name: Deploy to GitHub Pages
id: deployment
uses: actions/deploy-pages@v4
```
::: warning هشدار
مطمئن شوید که گزینه `base` در ویت‌پرس به‌درستی پیکربندی شده است. برای اطلاعات بیشتر به [تنظیم مسیر پایه عمومی](#setting-a-public-base-path) مراجعه کنید.
:::
2. در تنظیمات مخزن خود در زیرمنوی "Build and deployment > Source" در "Github Actions" را انتخاب کنید.
3. تغییرات خود را به شاخه `main` ارسال کنید و منتظر GitHub Actions workflow بمانید. شما باید وب‌سایت خود را در `https://<username>.github.io/[repository]/` یا `https://<custom-domain>/` بسته به تنظیمات خود دیده شده است. وب‌سایت شما به‌طور خودکار در هر بار فشرده‌سازی به شاخه `main` ارسال می‌شود.
### صفحات GitLab {#gitlab-pages}
1. `outDir` را در پیکربندی ویت‌پرس به `../public` تنظیم کنید. گزینه `base` را به `'/<repository>/'` تنظیم کنید اگر می‌خواهید در `https://<username>.gitlab.io/<repository>/` انتشار دهید.
2. یک فایل به نام `.gitlab-ci.yml` در ریشه پروژه خود با محتوای زیر ایجاد کنید. این کار به ساخت و انتشار وب‌سایت شما هر زمانی که تغییری در محتوا ایجاد می‌کنید، می‌پردازد:
```yaml
image: node:18
pages:
cache:
paths:
- node_modules/
script:
# - apk add git # Uncomment this if you're using small docker images like alpine and have lastUpdated enabled
- npm install
- npm run docs:build
artifacts:
paths:
- public
only:
- main
```
### Azure Static Web Apps {#azure-static-web-apps}
1. دستورالعمل [رسمی](https://docs.microsoft.com/en-us/azure/static-web-apps/build-configuration) را دنبال کنید.
2. این مقادیر را در فایل پیکربندی خود تنظیم کنید (و مواردی که نیازی به آن‌ها ندارید، مانند `api_location` را حذف کنید):
- **`app_location`**: `/`
- **`output_location`**: `docs/.vitepress/dist`
- **`app_build_command`**: `npm run docs:build`
### Firebase {#firebase}
1. فایل‌های `firebase.json` و `.firebaserc` را در ریشه پروژه خود ایجاد کنید:
`firebase.json`:
```json
{
"hosting": {
"public": "docs/.vitepress/dist",
"ignore": []
}
}
```
`.firebaserc`:
```json
{
"projects": {
"default": "<YOUR_FIREBASE_ID>"
}
}
```
2. بعد از اجرای `npm run docs:build`، دستور زیر را برای انتشار اجرا کنید:
```sh
firebase deploy
```
### Surge {#surge}
1. بعد از اجرای `npm run docs:build`، دستور زیر را برای انتشار اجرا کنید:
```sh
npx surge docs/.vitepress/dist
```
### Heroku {#heroku}
1. دستورالعمل و راهنماها را در [`heroku-buildpack-static`](https://elements.heroku.com/buildpacks/heroku/heroku-buildpack-static) دنبال کنید.
2. یک فایل به نام `static.json` در ریشه پروژه خود با محتوای زیر ایجاد کنید:
```json
{
"root": "docs/.vitepress/dist"
}
```
### Edgio {#edgio}
به [ایجاد و انتشار یک برنامه ویت‌پرس در Edgio](https://docs.edg.io/guides/vitepress) مراجعه کنید.
### Kinsta Static Site Hosting {#kinsta-static-site-hosting}
شما می‌توانید وب‌سایت ویت‌پرس خود را بر روی [Kinsta](https://kinsta.com/static-site-hosting/) با دنبال کردن این [دستورالعمل‌ها](https://kinsta.com/docs/vitepress-static-site-example/) انتشار دهید.
### Stormkit
شما می‌توانید پروژه ویت‌پرس خود را به [Stormkit](https://www.stormkit.io) با دنبال کردن این [دستورالعمل‌ها](https://stormkit.io/blog/how-to-deploy-vitepress) انتشار دهید.
### Nginx
اینجا یک مثال از پیکربندی بلوک سرور Nginx است. این تنظیم شامل فشرده‌سازی gzip برای فایل‌های متن معمولی، قوانین برای سرویس فایل‌های ایستا سایت ویت‌پرس شما با هدرهای مناسب برای حافظه‌نگهداری مناسب است و همچنین مدیریت `cleanUrls: true` می‌کند.
```nginx
server {
gzip on;
gzip_types text/plain text/css application/json application/javascript text/xml application/xml application/xml+rss text/javascript;
listen 80;
server_name _;
index index.html;
location / {
# content location
root /app;
# exact matches -> reverse clean urls -> folders -> not found
try_files $uri $uri.html $uri/ =404;
# non existent pages
error_page 404 /404.html;
# a folder without index.html raises 403 in this setup
error_page 403 /404.html;
# adjust caching headers
# files in the assets folder have hashes filenames
location ~* ^/assets/ {
expires 1y;
add_header Cache-Control "public, immutable";
}
}
}
```
این پیکربندی فرض می‌کند که سایت ویت‌پرس ساخته شده شما در دایرکتوری `/app` در سرور شما قرار دارد. دستورالعمل `root` را از ابزارهای مربوطه استفاده کنید اگر فایل‌های سایت شما در جای دیگری قرار دارد.
::: warning هشدار
مسیر تنظیمات try_files نباید به طور پیش‌فرض به index.html مانند برنامه‌های دیگر Vue مشخص شود. این کار باعث وضعیت نامعتبر صفحه می‌شود.
:::
اطلاعات بیشتر را در [مستندات رسمی nginx](https://nginx.org/en/docs/)، در این مسائل [#2837](https://github.com/vuejs/vitepress/discussions/2837)، [#3235](https://github.com/vuejs/vitepress/issues/3235) و همچنین در این [پست وبلاگ](https://blog.mehdi.cc/articles/vitepress-cleanurls-on-nginx-environment#readings) از Mehdi Merah پیدا کنید.

@ -0,0 +1,343 @@
---
outline: deep
---
# گسترش تم پیش‌فرض {#extending-the-default-theme}
تم پیش‌فرض ویت‌پرس برای مستندات بهینه‌سازی شده است و قابلیت سفارشی‌سازی دارد. برای دریافت لیست جامع گزینه‌ها، به [نمای کلی از تنظیمات تم پیش‌فرض](../reference/default-theme-config) مراجعه کنید.
با این حال، مواردی وجود دارد که فقط با تنظیمات کافی نخواهد بود. به عنوان مثال:
1. نیاز به تنظیم استایل CSS دارید؛
2. نیاز به اصلاح نمونه برنامه Vue، به عنوان مثال برای ثبت مولفه‌های عمومی؛
3. نیاز به درج محتوای سفارشی در تم از طریق slotهای طرح.
این سفارش‌های پیشرفته نیازمند استفاده از یک تم سفارشی هستند که از تم پیش‌فرض "گسترش" می‌کند.
::: tip نکته
قبل از ادامه، ابتدا [استفاده از یک تم سفارشی](./custom-theme) را بخوانید تا نحوه کار تم‌های سفارشی را درک کنید.
:::
## سفارشی‌سازی CSS {#customizing-css}
CSS تم پیش‌فرض با نادیده گرفتن متغیرهای CSS سطح ریشه قابل سفارشی‌سازی است:
```js
// .vitepress/theme/index.js
import DefaultTheme from 'vitepress/theme'
import './custom.css'
export default DefaultTheme
```
```css
/* .vitepress/theme/custom.css */
:root {
--vp-c-brand-1: #646cff;
--vp-c-brand-2: #747bff;
}
```
لیست متغیرهای CSS [تم پیش‌فرض](https://github.com/vuejs/vitepress/blob/main/src/client/theme-default/styles/vars.css) که می‌توانند سفارشی‌سازی شوند را ببینید.
## استفاده از فونت‌های مختلف {#using-different-fonts}
ویت‌پرس از [Inter](https://rsms.me/inter/) به عنوان فونت پیش‌فرض استفاده می‌کند و فونت‌ها را در خروجی ساخته‌شده شامل می‌شود. این فونت همچنین در محصولات خودکار پیش‌بارگذاری می‌شود. با این حال، این ممکن است مطلوب نباشد اگر می‌خواهید از یک فونت اصلی مختلف استفاده کنید.
برای جلوگیری از شامل شدن Inter در خروجی ساخته‌شده، تم را به جای `vitepress/theme-without-fonts` وارد کنید:
```js
// .vitepress/theme/index.js
import DefaultTheme from 'vitepress/theme-without-fonts'
import './my-fonts.css'
export default DefaultTheme
```
```css
/* .vitepress/theme/custom.css */
:root {
--vp-font-family-base: /* فونت متن عادی */
--vp-font-family-mono: /* فونت کد */
}
```
::: warning هشدار
اگر از مولفه‌های اختیاری مانند مولفه‌های [صفحه تیم](../reference/default-theme-team-page) استفاده می‌کنید، اطمینان حاصل کنید که آن‌ها را هم از `vitepress/theme-without-fonts` وارد می‌کنید!
:::
اگر فونت شما یک فایل محلی است که از طریق `@font-face` ارجاع شده است، به عنوان یک دارایی پردازش می‌شود و با نام فایل هشداردار در `.vitepress/dist/assets` شامل می‌شود. برای پیش‌بارگذاری این فایل، از هوک ساخت [transformHead](../reference/site-config#transformhead) استفاده کنید:
```js
// .vitepress/config.js
export default {
transformHead({ assets }) {
// منظور شده برای همسان سازی font خود، regex مورد نیاز را تنظیم کنید
const myFontFile = assets.find(file => /font-name\.\w+\.woff2/)
if (myFontFile) {
return [
[
'link',
{
rel: 'preload',
href: myFontFile,
as: 'font',
type: 'font/woff2',
crossorigin: ''
}
]
]
}
}
}
```
## ثبت مولفه‌های عمومی {#registering-global-components}
```js
// .vitepress/theme/index.js
import DefaultTheme from 'vitepress/theme'
/** @type {import('vitepress').Theme} */
export default {
extends: DefaultTheme,
enhanceApp({ app }) {
// ثبت مولفه‌های عمومی سفارشی‌شده خود را
app.component('MyGlobalComponent' /* ... */)
}
}
```
اگر از TypeScript استفاده می‌کنید:
```ts
// .vitepress/theme/index.ts
import type { Theme } from 'vitepress'
import DefaultTheme from 'vitepress/theme'
export default {
extends: DefaultTheme,
enhanceApp({ app }) {
// ثبت مولفه‌های عمومی سفارشی‌شده خود را
app.component('MyGlobalComponent' /* ... */)
}
} satisfies Theme
```
از آنجا که از Vite استفاده می‌کنیم، می‌توانید از ویژگی [import glob](https://vitejs.dev/guide/features.html#glob-import) در Vite برای خودکار ثبت یک پوشه از مولفه‌ها استفاده کنید.
## slot ‌های طرح {#layout-slots}
کامپوننت `<Layout/>` تم پیش‌فرض چندین slot دارد که می‌توانید محتوا را در موقعیت‌های مختلف صفحه در آن‌ها درج کنید. در زیر مثالی از درج یک کامپوننت در قبل از طرح داده شده است:
```js
// .vitepress/theme/index.js
import DefaultTheme from 'vitepress/theme'
import MyLayout from './MyLayout.vue'
export default {
extends: DefaultTheme,
// جایگزینی Layout با یک کامپوننت پوشه‌بندی که slotها را درج می‌کند
Layout: MyLayout
}
```
```vue
<!--.vitepress/theme/MyLayout.vue-->
<script setup>
import DefaultTheme from 'vitepress/theme'
const { Layout } = DefaultTheme
</script>
<template>
<Layout>
<template #aside-outline-before>
محتوای سفارشی بالای نوار کناری من
</template>
</Layout>
</template>
```
یا می‌توانید از تابع رندر نیز استفاده کنید.
```js
// .vitepress/theme/index.js
import { h } from 'vue'
import DefaultTheme from 'vitepress/theme'
import MyComponent from './MyComponent.vue'
export default {
extends: DefaultTheme,
Layout() {
return h(DefaultTheme.Layout, null, {
'aside-outline-before': () => h(MyComponent)
})
}
}
```
لیست کاملی از slotهای موجود در طرح پیش‌فرض:
- وقتی `layout: 'doc'` (پیش‌فرض) از طریق frontmatter فعال است:
- `doc-top`
- `doc-bottom`
- `doc-footer-before`
- `doc-before`
- `doc-after`
- `sidebar-nav-before`
- `sidebar-nav-after`
- `aside-top`
- `aside-bottom`
- `aside-outline-before`
- `aside-outline-after`
- `aside-ads-before`
- `aside-ads-after`
- وقتی `layout: 'home'` از طریق frontmatter فعال است:
- `home-hero-before`
- `home-hero-info-before`
- `home-hero-info`
- `home-hero-info-after`
- `home-hero-actions-after`
- `home-hero-image`
- `home-hero-after`
- `home-features-before`
- `home-features-after`
- وقتی `layout: 'page'` از طریق frontmatter فعال است:
- `page-top`
- `page-bottom`
- در صفحه یافت نشد (404):
- `not-found`
- همیشه:
- `layout-top`
- `layout-bottom`
- `nav-bar-title-before`
- `nav-bar-title-after`
- `nav-bar-content-before`
- `nav-bar-content-after`
- `nav-screen-content-before`
- `nav-screen-content-after`
## استفاده از API انتقال نمایش {#using-view-transitions-api}
### در تغییر ظاهر {#on-appearance-toggle}
شما می‌توانید تم پیش‌فرض را گسترش دهید تا هنگام تغییر حالت رنگ، یک انتقال سفارشی را فراهم کند. به عنوان مثال:
```vue
<!-- .vitepress/theme/Layout.vue -->
<script setup lang="ts">
import { useData } from 'vitepress'
import DefaultTheme from 'vitepress/theme'
import { nextTick, provide } from 'vue'
const { isDark } = useData()
const enableTransitions = () =>
'startViewTransition' in document &&
window.matchMedia('(prefers-reduced-motion: no-preference)').matches
provide('toggle-appearance', async ({ clientX: x, clientY: y }: MouseEvent) => {
if (!enableTransitions()) {
isDark.value = !isDark.value
return
}
const clipPath = [
`circle(0px at ${x}px ${y}px)`,
`circle(${Math.hypot(
Math.max(x, innerWidth - x),
Math.max(y, innerHeight - y)
)}px at ${x}px ${y}px)`
]
await document.startViewTransition(async () => {
isDark.value = !isDark.value
await nextTick()
}).ready
document.documentElement.animate(
{ clipPath: isDark.value ? clipPath.reverse() : clipPath },
{
duration: 300,
easing: 'ease-in',
pseudoElement: `::view-transition-${isDark.value ? 'old' : 'new'}(root)`
}
)
})
</script>
<template>
<DefaultTheme.Layout />
</template>
<style>
::view-transition-old(root),
::view-transition-new(root) {
animation: none;
mix-blend-mode: normal;
}
::view-transition-old(root),
.dark::view-transition-new(root) {
z-index: 1;
}
::view-transition-new(root),
.dark::view-transition-old(root) {
z-index: 9999;
}
.VPSwitchAppearance {
width: 22px !important;
}
.VPSwitchAppearance .check {
transform: none !important;
}
</style>
```
نتیجه (**هشدار!**: رنگ‌های فلاشینگ، حرکات ناگهانی، نورهای شدید):
<details>
<summary>نمایش</summary>
![نمایش انتقال ظاهر تغییر](/appearance-toggle-transition.webp)
</details>
برای جزئیات بیشتر در مورد انتقال‌های نمایش به [اسناد کروم](https://developer.chrome.com/docs/web-platform/view-transitions/) مراجعه کنید.
### در تغییر مسیر {#on-route-change}
به زودی.
## جایگزینی کامپوننت‌های داخلی {#overriding-internal-components}
شما می‌توانید با استفاده از [alias های Vite](https://vitejs.dev/config/shared-options.html#resolve-alias)، کامپوننت‌های تم پیش‌فرض را با کامپوننت‌های سفارشی خود جایگزین کنید:
```ts
import { fileURLToPath, URL } from 'node:url'
import { defineConfig } from 'vitepress'
export default defineConfig({
vite: {
resolve: {
alias: [
{
find: /^.*\/VPNavBar\.vue$/,
replacement: fileURLToPath(
new URL('./components/CustomNavBar.vue', import.meta.url)
)
}
]
}
}
})
```
برای دریافت نام دقیق کامپوننت به [کد منبع ما](https://github.com/vuejs/vitepress/tree/main/src/client/theme-default/components) مراجعه کنید. از آنجا که کامپوننت‌ها داخلی هستند، احتمال آنکه نام آن‌ها بین انتشارات کوچک تغییر کند، وجود دارد.

@ -0,0 +1,48 @@
# Frontmatter
## استفاده {#usage}
ویت‌پرس پشتیبانی از frontmatter YAML در تمام فایل‌های Markdown را دارد و آن‌ها را با استفاده از [gray-matter](https://github.com/jonschlinkert/gray-matter) تجزیه می‌کند. Frontmatter باید در بالای فایل Markdown قرار داشته باشد (قبل از هر عنصر از جمله برچسب‌های `<script>`) و باید به صورت YAML معتبر واقع در بین خطوط خط کشیده شود. به عنوان مثال:
```md
---
title: مستندات با ویت‌پرس
editLink: true
---
```
بسیاری از گزینه‌های پیکربندی سایت یا پیش‌فرض در تمام frontmatter گزینه‌های متناظر دارند. شما می‌توانید از frontmatter برای لغو عملکرد خاص برای صفحه فعلی استفاده کنید. برای جزئیات بیشتر، به [مرجع پیکربندی Frontmatter](../reference/frontmatter-config) مراجعه کنید.
همچنین می‌توانید داده‌های اختصاصی frontmatter خود را تعریف کنید تا در بیانیه‌های پویا Vue در صفحه استفاده شود.
## دسترسی به داده‌های Frontmatter {#accessing-frontmatter-data}
داده‌های frontmatter می‌توانند از طریق متغیر global ویژه `$frontmatter` دسترسی داشته باشند:
اینجا یک مثال از نحوه استفاده از آن در فایل Markdown شما است:
```md
---
title: مستندات با ویت‌پرس
editLink: true
---
# {{ $frontmatter.title }}
محتوای راهنما
```
شما همچنین می‌توانید داده‌های frontmatter صفحه فعلی را در `<script setup>` با استفاده از راهنمای [`useData()`](../reference/runtime-api#usedata) به دست آورید.
## فرمت‌های جایگزین Frontmatter {#alternative-frontmatter-formats}
ویت‌پرس همچنین از نحوه نوشتاری frontmatter JSON با استفاده از تکیه‌گاه‌های آغازین و پایانی در آکولاد پشتیبانی می‌کند:
```json
---
{
"title": "عنوان",
"editLink": true
}
---
```

@ -0,0 +1,225 @@
# شروع کار {#getting-started}
## تست آنلاین {#try-it-online}
می‌توانید ویت‌پرس را مستقیماً در مرورگر خود در [StackBlitz](https://vitepress.new) امتحان کنید.
## نصب {#installation}
### پیش‌نیازها {#prerequisites}
- [Node.js](https://nodejs.org/) نسخه 18 یا بالاتر.
- ترمینال برای دسترسی به ویت‌پرس از طریق رابط خط فرمان (CLI).
- ویرایشگر متنی با پشتیبانی از [Markdown](https://en.wikipedia.org/wiki/Markdown).
- [VSCode](https://code.visualstudio.com/) به همراه [افزونه رسمی Vue](https://marketplace.visualstudio.com/items?itemName=Vue.volar).
ویت‌پرس می‌تواند به صورت مستقل استفاده شود یا در یک پروژه موجود نصب شود. در هر دو حالت، می‌توانید آن را با دستور زیر نصب کنید:
::: code-group
```sh [npm]
$ npm add -D vitepress
```
```sh [pnpm]
$ pnpm add -D vitepress
```
```sh [yarn]
$ yarn add -D vitepress
```
```sh [yarn (pnp)]
$ yarn add -D vitepress vue
```
```sh [bun]
$ bun add -D vitepress
```
:::
::: details درباره peer dependency های ناموجود هشدار دریافت می‌کنید؟
اگر از PNPM استفاده می‌کنید، متوجه هشدار peer dependency برای `@docsearch/js` خواهید شد. این مسئله جلوی عملکرد ویت‌پرس را نمی‌گیرد. اگر می‌خواهید این هشدار را نادیده بگیرید، موارد زیر را به `package.json` خود اضافه کنید:
```json
"pnpm": {
"peerDependencyRules": {
"ignoreMissing": [
"@algolia/client-search",
"search-insights"
]
}
}
```
:::
::: tip نکته
ویت‌پرس یک بسته فقط ESM است. از `require()` برای وارد کردن آن استفاده نکنید و اطمینان حاصل کنید که نزدیک‌ترین `package.json` شما شامل `"type": "module"` است، یا پسوند فایل‌های مربوطه خود مانند `.vitepress/config.js` را به `.mjs`/`.mts` تغییر دهید. برای جزئیات بیشتر به [راهنمای عیب‌یابی Vite](http://vitejs.dev/guide/troubleshooting.html#this-package-is-esm-only) مراجعه کنید. همچنین، در زمینه‌های async CJS می‌توانید از `await import('vitepress')` استفاده کنید.
:::
### Wizard راه‌اندازی
ویت‌پرس با یک جادوگر راه‌اندازی خط فرمان ارائه می‌شود که به شما کمک می‌کند یک پروژه پایه را بسازید. پس از نصب، با اجرای دستور زیر جادوگر را راه‌اندازی کنید:
::: code-group
```sh [npm]
$ npx vitepress init
```
```sh [pnpm]
$ pnpm vitepress init
```
```sh [yarn]
$ yarn vitepress init
```
```sh [bun]
$ bun vitepress init
```
:::
چند سوال ساده از شما پرسیده خواهد شد:
<<< @/snippets/init.ansi
::: tip Vue به عنوان peer dependency
اگر قصد دارید سفارشی‌سازی‌هایی که از کامپوننت‌ها یا APIهای Vue استفاده می‌کنند را انجام دهید، باید `vue` را به عنوان dependency نیز نصب کنید.
:::
## ساختار فایل‌ها {#file-structure}
اگر در حال ساخت یک سایت مستقل ویت‌پرس هستید، می‌توانید سایت را در دایرکتوری فعلی خود (`./`) بسازید. اما، اگر ویت‌پرس را در یک پروژه موجود به همراه سایر کدهای منبع نصب می‌کنید، توصیه می‌شود سایت را در یک دایرکتوری تودرتو (مثلاً `./docs`) بسازید تا از بقیه پروژه جدا باشد.
فرض کنیم که پروژه ویت‌پرس را در `./docs` ساخته‌اید، ساختار فایل‌های تولید شده باید به این شکل باشد:
```
.
├─ docs
│ ├─ .vitepress
│ │ └─ config.js
│ ├─ api-examples.md
│ ├─ markdown-examples.md
│ └─ index.md
└─ package.json
```
دایرکتوری `docs` به عنوان **ریشه پروژه** سایت ویت‌پرس در نظر گرفته می‌شود. دایرکتوری `.vitepress` محل ذخیره فایل‌های پیکربندی ویت‌پرس، حافظه نهان سرور توسعه، خروجی ساخت و کد سفارشی‌سازی تم اختیاری است.
::: tip نکته
به طور پیش‌فرض، ویت‌پرس حافظه نهان سرور توسعه خود را در `.vitepress/cache` و خروجی ساخت تولیدی را در `.vitepress/dist` ذخیره می‌کند. اگر از Git استفاده می‌کنید، باید آنها را به فایل `.gitignore` خود اضافه کنید. این مکان‌ها همچنین قابل [پیکربندی](../reference/site-config#outdir) هستند.
:::
### فایل پیکربندی {#the-config-file}
فایل پیکربندی (`.vitepress/config.js`) به شما اجازه می‌دهد جنبه‌های مختلف سایت ویت‌پرس خود را سفارشی کنید، با گزینه‌های پایه‌ای مانند عنوان و توضیحات سایت:
```js
// .vitepress/config.js
export default {
// گزینه‌های سطح سایت
title: 'ویت‌پرس',
description: 'فقط در حال بازی کردن.',
themeConfig: {
// گزینه‌های سطح تم
}
}
```
همچنین می‌توانید رفتار تم را از طریق گزینه `themeConfig` پیکربندی کنید. برای جزئیات کامل درباره همه گزینه‌های پیکربندی، به [راهنمای پیکربندی](../reference/site-config) مراجعه کنید.
### فایل‌های منبع {#source-files}
فایل‌های Markdown خارج از دایرکتوری `.vitepress` به عنوان **فایل‌های منبع** در نظر گرفته می‌شوند.
ویت‌پرس از **مسیر یابی مبتنی بر فایل** استفاده می‌کند: هر فایل `.md` به یک فایل `.html` متناظر با همان مسیر کامپایل می‌شود. برای مثال، `index.md` به `index.html` کامپایل می‌شود و می‌تواند در مسیر ریشه `/` سایت ویت‌پرس نتیجه‌گیری شده بازدید شود.
ویت‌پرس همچنین قابلیت تولید URLهای تمیز، بازنویسی مسیرها و تولید پویا صفحات را فراهم می‌کند. این موارد در [راهنمای مسیر یابی](./routing) پوشش داده خواهند شد.
## راه‌اندازی و اجرا {#up-and-running}
این ابزار باید اسکریپت‌های npm زیر را به `package.json` شما اضافه کرده باشد اگر اجازه این کار را در طول فرآیند راه‌اندازی داده باشید:
```json
{
...
"scripts": {
"docs:dev": "vitepress dev docs",
"docs:build": "vitepress build docs",
"docs:preview": "vitepress preview docs"
},
...
}
```
اسکریپت `docs:dev` یک سرور توسعه محلی با به‌روزرسانی‌های فوری راه‌اندازی می‌کند. آن را با دستور زیر اجرا کنید:
::: code-group
```sh [npm]
$ npm run docs:dev
```
```sh [pnpm]
$ pnpm run docs:dev
```
```sh [yarn]
$ yarn docs:dev
```
```sh [bun]
$ bun run docs:dev
```
:::
به جای اسکریپت‌های npm، می‌توانید ویت‌پرس را مستقیماً با دستور زیر اجرا کنید:
::: code-group
```sh [npm]
$ npx vitepress dev docs
```
```sh [pnpm]
$ pnpm vitepress dev docs
```
```sh [yarn]
$ yarn vitepress dev docs
```
```sh [bun]
$ bun vitepress dev docs
```
:::
استفاده بیشتر از خط فرمان در [مرجع CLI](../reference/cli) مستند شده است.
سرور توسعه باید در `http://localhost:5173` اجرا شود. URL را در مرورگر خود بازدید کنید تا سایت جدید خود را در عمل ببینید!
## مراحل بعدی {#what-s-next}
- برای درک بهتر چگونگی نگاشت فایل‌های markdown به HTML تولید شده، به [راهنمای مسیر یابی](./routing) مراجعه کنید.
- برای کشف بیشتر درباره اینکه چه کارهایی می‌توانید در صفحه انجام دهید، مانند نوشتن محتوای markdown یا استفاده از کامپوننت‌های Vue، به بخش "نوشتن" راهنما مراجعه کنید. یک مکان عالی برای شروع یادگیری درباره [افزونه‌های Markdown](./markdown) است.
- برای کشف ویژگی‌های ارائه شده توسط تم پیش‌فرض مستندات، به [مرجع پیکربندی تم پیش‌فرض](../reference/default-theme-config) مراجعه کنید.
- اگر می‌خواهید ظاهر سایت خود را بیشتر سفارشی کنید، بررسی کنید که چگونه [تم پیش‌فرض را گسترش دهید](./extending-default-theme) یا [یک تم سفارشی بسازید](./custom-theme).
- هنگامی که سایت مستندات شما شکل گرفت، حتماً [راهنمای استقرار](./deploy) را بخوانید.

@ -0,0 +1,113 @@
# بین‌المللی‌سازی {#internationalization}
برای استفاده از ویژگی‌های داخلی بین‌المللی‌سازی، نیاز است که یک ساختار دایرکتوری به شکل زیر ایجاد کنید:
```
docs/
├─ es/
│ ├─ foo.md
├─ fr/
│ ├─ foo.md
├─ foo.md
```
سپس در `docs/.vitepress/config.ts` به شکل زیر عمل کنید:
```ts
import { defineConfig } from 'vitepress'
export default defineConfig({
// ویژگی‌های مشترک و دیگر موارد در سطح بالا...
locales: {
root: {
label: 'انگلیسی',
lang: 'en'
},
fr: {
label: 'فرانسوی',
lang: 'fr', // اختیاری، به عنوان `lang` در `html` tag اضافه خواهد شد
link: '/fr/guide' // پیش‌فرض /fr/ -- در منوی ترجمه‌ها نمایش داده می‌شود، می‌تواند خارجی باشد
// سایر ویژگی‌های مختص به هر زبان...
}
}
})
```
می‌توانید خصوصیات زیر را برای هر زبان (شامل ریشه) نیز تغییر دهید:
```ts
interface LocaleSpecificConfig<ThemeConfig = any> {
lang?: string
dir?: string
title?: string
titleTemplate?: string | boolean
description?: string
head?: HeadConfig[] // با ورودی‌های head موجود ادغام خواهد شد، meta tags تکراری به طور خودکار حذف می‌شوند
themeConfig?: ThemeConfig // ادغام سطح بالا، می‌توان اطلاعات مشترک را در ورودی themeConfig اضافه کرد
}
```
برای جزئیات درباره تنظیمات پیش‌فرض، به رابط `DefaultTheme.Config` در [اینجا](https://github.com/vuejs/vitepress/blob/main/types/default-theme.d.ts) مراجعه کنید. لطفاً خصوصیات `themeConfig.algolia` یا `themeConfig.carbonAds` را در سطح زبان تغییر ندهید. برای استفاده از جستجوی چندزبانه، به [مستندات Algolia](../reference/default-theme-search#i18n) مراجعه کنید.
**نکته حرفه‌ای:** فایل پیکربندی را می‌توانید در `docs/.vitepress/config/index.ts` نیز ذخیره کنید. این کار به شما کمک می‌کند که با ایجاد یک فایل پیکربندی برای هر زبان و سپس ادغام و صدور آنها از `index.ts`، موارد را سازماندهی کنید.
## دایرکتوری جداگانه برای هر زبان {#separate-directory-for-each-locale}
ساختار زیر به طور کاملاً صحیح است:
```
docs/
├─ en/
│ ├─ foo.md
├─ es/
│ ├─ foo.md
├─ fr/
├─ foo.md
```
با این حال، ویت‌پرس به طور پیش‌فرض به `/` به `/en/` هدایت نمی‌کند. برای این کار باید سرور خود را پیکربندی کنید. به عنوان مثال، در Netlify، می‌توانید فایل `docs/public/_redirects` را به این شکل اضافه کنید:
```
/* /es/:splat 302 Language=es
/* /fr/:splat 302 Language=fr
/* /en/:splat 302
```
**نکته حرفه‌ای:** در صورت استفاده از روش فوق، می‌توانید از کوکی `nf_lang` برای ثبت انتخاب زبان کاربر استفاده کنید:
```ts
// docs/.vitepress/theme/index.ts
import DefaultTheme from 'vitepress/theme'
import Layout from './Layout.vue'
export default {
extends: DefaultTheme,
Layout
}
```
```vue
<!-- docs/.vitepress/theme/Layout.vue -->
<script setup lang="ts">
import DefaultTheme from 'vitepress/theme'
import { useData } from 'vitepress'
import { watchEffect } from 'vue'
const { lang } = useData()
watchEffect(() => {
if (inBrowser) {
document.cookie = `nf_lang=${lang.value}; expires=Mon, 1 Jan 2030 00:00:00 UTC; path=/`
}
})
</script>
<template>
<DefaultTheme.Layout />
</template>
```
## پشتیبانی از RTL (آزمایشی) {#rtl-support-experimental}
برای پشتیبانی از RTL، `dir: 'rtl'` را در پیکربندی مشخص کنید و از پلاگین‌های PostCSS RTLCSS مانند <https://github.com/MohammadYounes/rtlcss>، <https://github.com/vkalinichev/postcss-rtl> یا <https://github.com/elchininet/postcss-rtlcss> استفاده کنید. باید پلاگین PostCSS خود را به کارگیری `:where([dir="ltr"])` و `:where([dir="rtl"])` به عنوان پیشوندها جلوگیری از مشکلات اولویت CSS استفاده کنید.

@ -0,0 +1,922 @@
# افزونه‌های Markdown {#markdown-extensions}
ویت‌پرس با افزونه‌های markdown داخلی ارائه شده است.
## لینک‌های هدر {#header-anchors}
هدرها به طور خودکار لینک‌های anchor دریافت می‌کنند. نمایش anchor ها با استفاده از گزینه `markdown.anchor` قابل پیکربندی است.
### anchor های سفارشی {#custom-anchors}
برای مشخص کردن تگ anchor سفارشی برای یک هدینگ به جای استفاده از تگ خودکار، یک پسوند به هدینگ اضافه کنید:
```
# Using custom anchors {#my-anchor}
```
این به شما امکان می‌دهد که به جای استفاده از به جای استفاده از `#using-custom-anchors`، به هدینگ به عنوان `#my-anchor` لینک دهید.
## لینک‌ها {#links}
هم لینک‌های داخلی و هم خارجی با دستورالعمل‌های خاصی ارائه می‌شوند.
### لینک‌های داخلی {#internal-links}
لینک‌های داخلی به لینک روتر برای ناوبری SPA تبدیل می‌شوند. همچنین، هر `index.md` موجود در هر زیرپوشه به طور خودکار به `index.html` تبدیل می‌شود، با URL متناظر `/`.
به عنوان مثال، با توجه به ساختار پوشه زیر:
```
.
├─ index.md
├─ foo
│ ├─ index.md
│ ├─ one.md
│ └─ two.md
└─ bar
├─ index.md
├─ three.md
└─ four.md
```
و با فرض این که شما در `foo/one.md` هستید:
```md
[Home](/) <!-- sends the user to the root index.md -->
[foo](/foo/) <!-- sends the user to index.html of directory foo -->
[foo heading](./#heading) <!-- anchors user to a heading in the foo index file -->
[bar - three](../bar/three) <!-- you can omit extension -->
[bar - three](../bar/three.md) <!-- you can append .md -->
[bar - four](../bar/four.html) <!-- or you can append .html -->
```
### پسوند صفحه {#page-suffix}
صفحات و لینک‌های داخلی به طور پیش‌فرض با پسوند `.html` تولید می‌شوند.
### لینک‌های خارجی {#external-links}
لینک‌های خروجی به طور خودکار دارای `target="_blank" rel="noreferrer"` هستند:
- [vuejs.org](https://vuejs.org)
- [ویت‌پرس در GitHub](https://github.com/vuejs/vitepress)
## Frontmatter {#frontmatter}
[YAML frontmatter](https://jekyllrb.com/docs/front-matter/) به طور پیش‌فرض پشتیبانی می‌شود:
```yaml
---
title: عنوان صفحه
lang: fa-IR
---
```
این داده‌ها برای بقیه صفحه در دسترس خواهد بود، همراه با تمامی اجزاهای سفارشی و تم.
برای اطلاعات بیشتر، به [Frontmatter](../reference/frontmatter-config) مراجعه کنید.
## جداول مانند Github {#github-style-tables}
**ورودی**
```md
| Tables | Are | Cool |
| ------------- | :-----------: | ----: |
| col 3 is | right-aligned | $1600 |
| col 2 is | centered | $12 |
| zebra stripes | are neat | $1 |
```
**خروجی**
| Tables | Are | Cool |
| ------------- | :-----------: | ----: |
| col 3 is | right-aligned | $1600 |
| col 2 is | centered | $12 |
| zebra stripes | are neat | $1 |
## اموجی :tada: {#emoji}
**ورودی**
```
:tada: :100:
```
**خروجی**
:tada: :100:
یک [لیست از همه اموجی ها](https://github.com/markdown-it/markdown-it-emoji/blob/master/lib/data/full.mjs) در دسترس است.
## فهرست مطالب {#table-of-contents}
**ورودی**
```
[[toc]]
```
**خروجی**
[[toc]]
نحوه پردازش فهرست مطالب با استفاده از گزینه `markdown.toc` قابل پیکربندی است.
## کانتینرهای سفارشی {#custom-containers}
کانتینرهای سفارشی می‌توانند توسط انواع، عناوین و محتویات خود تعریف شوند.
### عنوان پیش‌فرض {#default-title}
**ورودی**
```md
::: info
این یک جعبه اطلاعات است.
:::
::: tip
این یک نکته است.
:::
::: warning
این یک هشدار است.
:::
::: danger
این یک هشدار خطرناک است.
:::
::: details
این یک بلوک جزئیات است.
:::
```
**خروجی**
::: info اطلاعات
این یک جعبه اطلاعات است.
:::
::: tip نکته
این یک نکته است.
:::
::: warning هشدار
این یک هشدار است.
:::
::: danger خطر
این یک هشدار خطرناک است.
:::
::: details جزئیات
این یک بلوک جزئیات است.
:::
### عنوان سفارشی {#custom-title}
می‌توانید عنوان سفارشی را با اضافه کردن متن به انتهای نوع کانتینر تنظیم کنید.
**ورودی**
````md
::: danger ایست!
منطقه خطرناک، ادامه ندهید
:::
::: details برای مشاهده کد کلیک کنید
```js
console.log('Hello, ویت‌پرس!')
```
:::
````
**خروجی**
::: danger ایست!
منطقه خطرناک، ادامه ندهید
:::
::: details برای مشاهده کد کلیک کنید
```js
console.log('Hello, ویت‌پرس!')
```
:::
این همچنین امکان دارد که شما عنوان‌های سفارشی را به صورت global تنظیم کنید با اضافه کردن محتوای زیر به تنظیمات سایت. این امکان خاصا اگر به زبان انگلیسی نوشته نمی‌شود، بسیار مفید است:
```ts
// config.ts
export default defineConfig({
// ...
markdown: {
container: {
tipLabel: 'نکته',
warningLabel: 'اخطار',
dangerLabel: 'خطر',
infoLabel: 'اطلاعات',
detailsLabel: 'جزئیات'
}
}
// ...
})
```
### `raw` {#raw}
این یک کانتینر ویژه است که می‌تواند برای جلوگیری از تداخل استایل و روتر با ویت‌پرس استفاده شود. این به ویژه زمانی مفید است که شما کتابخانه‌های کامپوننت را مستند کنید. می‌توانید همچنین [whyframe](https://whyframe.dev/docs/integrations/vitepress) را برای ایزوله‌تر شدن بیشتر بررسی کنید.
**نحوه استفاده**
```md
::: raw
بسته‌بندی در یک <div class="vp-raw">
:::
```
کلاس `vp-raw` می‌تواند به صورت مستقیم بر روی عناصر استفاده شود. ایزوله‌سازی استایل در حال حاضر انتخابی است:
- `postcss` را با مدیر بسته‌های مورد علاقه‌تان نصب کنید:
```sh
$ npm add -D postcss
```
- یک فایل با نام `docs/postcss.config.mjs` ایجاد کنید و کد زیر را به آن اضافه کنید:
```js
import { postcssIsolateStyles } from 'vitepress'
export default {
plugins: [postcssIsolateStyles()]
}
```
این از [`postcss-prefix-selector`](https://github.com/postcss/postcss-load-config) استفاده می‌کند. می‌توانید گزینه‌های آن را به این صورت پاس بدهید:
```js
postcssIsolateStyles({
includeFiles: [/vp-doc\.css/] // به طور پیش‌فرض /base\.css/
})
```
## هشدارهای GitHub {#github-flavored-alerts}
ویت‌پرس همچنین [هشدارهای GitHub](https://docs.github.com/en/get-started/writing-on-github/getting-started-with-writing-and-formatting-on-github/basic-writing-and-formatting-syntax#alerts) را برای نمایش به عنوان تماس‌ها پشتیبانی می‌کند. آن‌ها به همان شکلی که [کانتینرهای سفارشی](#custom-containers) نمایش داده می‌شوند.
```md
> [!NOTE]
> اطلاعاتی که کاربران باید به آن توجه کنند، حتی اگر سریع بخوانند.
> [!TIP]
> اطلاعات اختیاری برای کمک به کاربر برای موفقیت بیشتر.
> [!IMPORTANT]
> اطلاعات حیاتی برای موفقیت کاربران.
> [!WARNING]
> محتوای بحرانی که نیاز به توجه فوری کاربر دارد به دلیل خطرات پتانسیلی.
> [!CAUTION]
> پیامدهای منفی احتمالی یک عمل.
```
> [!NOTE]
> اطلاعاتی که کاربران باید به آن توجه کنند، حتی اگر سریع بخوانند.
> [!TIP]
> اطلاعات اختیاری برای کمک به کاربر برای موفقیت بیشتر.
> [!IMPORTANT]
> اطلاعات حیاتی برای موفقیت کاربران.
> [!WARNING]
> محتوای بحرانی که نیاز به توجه فوری کاربر دارد به دلیل خطرات پتانسیلی.
> [!CAUTION]
> پیامدهای منفی احتمالی یک عمل.
## Syntax Highlighting در بلوک‌های کد {#syntax-highlighting-in-code-blocks}
ویت‌پرس از [Shiki](https://github.com/shikijs/shiki) برای syntax highlighting زبان در بلوک‌های کد Markdown با استفاده از متن رنگی استفاده می‌کند. Shiki از تنوع وسیعی از زبان‌های برنامه‌نویسی پشتیبانی می‌کند. تنها کافی است که یک نام مستعار زبان معتبر به بکتیک‌ها ابتدایی کد اضافه کنید:
**ورودی**
````
```js
export default {
name: 'MyComponent',
// ...
}
```
````
````
```html
<ul>
<li v-for="todo in todos" :key="todo.id">
{{ todo.text }}
</li>
</ul>
```
````
**خروجی**
```js
export default {
name: 'MyComponent'
// ...
}
```
```html
<ul>
<li v-for="todo in todos" :key="todo.id">
{{ todo.text }}
</li>
</ul>
```
یک [لیست از زبان‌های معتبر](https://shiki.style/languages) در مخزن Shiki موجود است.
همچنین می‌توانید تم syntax highlighting را در تنظیمات برنامه سفارشی کنید. لطفاً به [گزینه‌های Markdown](../reference/site-config#markdown) برای جزئیات بیشتر مراجعه کنید.
## برجسته‌سازی خطوط در بلوک‌های کد {#line-highlighting-in-code-blocks}
**ورودی**
````
```js{4}
export default {
data () {
return {
msg: 'برجسته‌سازی شده!'
}
}
}
```
````
**خروجی**
```js{4}
export default {
data () {
return {
msg: 'برجسته‌سازی شده!'
}
}
}
```
علاوه بر یک خط، می‌توانید چندین خط تکی، محدوده‌ها یا هر دو را نیز مشخص کنید:
- محدوده‌های خط: به عنوان مثال `{5-8}`, `{3-10}`, `{10-17}`
- چند خط تک: به عنوان مثال `{4,7,9}`
- محدوده‌های خط و خط‌های تک: به عنوان مثال `{4,7-13,16,23-27,40}`
**ورودی**
````
```js{1,4-6}
const message = 'Hello, World!';
console.log(message);
```
````
**خروجی**
```js{1,4-6}
const message = 'Hello, World!';
console.log(message);
```
## فکوس در بلاک‌های کد {#focus-in-code-blocks}
افزودن کامنت `// [!code focus]` به یک خط، روی آن فکوس می‌کند و بخش‌های دیگر کد را مات می‌کند.
به‌علاوه، می‌توانید با استفاده از `// [!code focus:<lines>]` تعدادی خط را برای فکوس تعیین کنید.
**ورودی**
````
```js
export default {
data () {
return {
msg: 'Focused!' // [!!code focus]
}
}
}
```
````
**خروجی**
```js
export default {
data() {
return {
msg: 'Focused!' // [!code focus]
}
}
}
```
## تفاوت‌های رنگی در بلاک‌های کد {#colored-diffs-in-code-blocks}
افزودن کامنت `// [!code --]` یا `// [!code ++]` به یک خط، یک تفاوت را در آن خط ایجاد می‌کند، با حفظ رنگ‌های بلاک کد.
**ورودی**
````
```js
export default {
data () {
return {
msg: 'Removed' // [!!code --]
msg: 'Added' // [!!code ++]
}
}
}
```
````
**خروجی**
```js
export default {
data () {
return {
msg: 'Removed' // [!code --]
msg: 'Added' // [!code ++]
}
}
}
```
## خطاها و هشدارها در بلاک‌های کد {#errors-and-warnings-in-code-blocks}
افزودن کامنت `// [!code warning]` یا `// [!code error]` به یک خط، آن را مطابق با نوع، رنگ می‌کند.
**ورودی**
````
```js
export default {
data () {
return {
msg: 'Error', // [!!code error]
msg: 'Warning' // [!!code warning]
}
}
}
```
````
**خروجی**
```js
export default {
data() {
return {
msg: 'Error', // [!code error]
msg: 'Warning' // [!code warning]
}
}
}
```
## شماره‌گذاری خطوط {#line-numbers}
می‌توانید با استفاده از تنظیمات، شماره‌گذاری خطوط را برای هر بلاک کد فعال کنید:
```js
export default {
markdown: {
lineNumbers: true
}
}
```
لطفاً [گزینه‌های markdown](../reference/site-config#markdown) را برای جزئیات بیشتر ببینید.
می‌توانید با استفاده از `:line-numbers` / `:no-line-numbers` در بلاک‌های کد شماره‌گذاری خطوط را نادیده بگیرید یا تنظیمات اصلی را با `=` پس از `:line-numbers` سفارشی کنید. به عنوان مثال، `:line-numbers=2` به معنای شروع شماره‌گذاری از خط `2` است.
**ورودی**
````md
```ts {1}
// شماره‌گذاری خطوط به طور پیش‌فرض غیرفعال است
const line2 = 'این خط ۲ است'
const line3 = 'این خط ۳ است'
```
```ts:line-numbers {1}
// شماره‌گذاری خطوط فعال است
const line2 = 'این خط ۲ است'
const line3 = 'این خط ۳ است'
```
```ts:line-numbers=2 {1}
// شماره‌گذاری خطوط فعال است و از خط ۲ شروع می‌شود
const line3 = 'این خط ۳ است'
const line4 = 'این خط ۴ است'
```
````
**خروجی**
```ts {1}
// شماره‌گذاری خطوط به طور پیش‌فرض غیرفعال است
const line2 = 'این خط ۲ است'
const line3 = 'این خط ۳ است'
```
```ts:line-numbers {1}
// شماره‌گذاری خطوط فعال است
const line2 = 'این خط ۲ است'
const line3 = 'این خط ۳ است'
```
```ts:line-numbers=2 {1}
// شماره‌گذاری خطوط فعال است و از خط ۲ شروع می‌شود
const line3 = 'این خط ۳ است'
const line4 = 'این خط ۴ است'
```
## وارد کردن Snippet کد {#import-code-snippets}
می‌توانید snippet های کد را از فایل‌های موجود با استفاده از دستور زیر وارد کنید:
```md
<<< @/filepath
```
این دستور [highlight کردن خط](#line-highlighting-in-code-blocks) را نیز پشتیبانی می‌کند:
```md
<<< @/filepath{highlightLines}
```
**ورودی**
```md
<<< @/snippets/snippet.js{2}
```
**فایل کد**
<<< @/snippets/snippet.js
**خروجی**
<<< @/snippets/snippet.js{2}
::: tip نکته
مقدار `@` با ریشه منبع مطابقت دارد. به‌طور پیش‌فرض، این ریشه پروژه ویت‌پرس است، مگر اینکه `srcDir` پیکربندی شده باشد. به‌طور جایگزینی، می‌توانید از مسیرهای نسبی وارد کنید:
```md
<<< ../snippets/snippet.js
```
:::
همچنین می‌توانید [ناحیه VS Code](https://code.visualstudio.com/docs/editor/codebasics#_folding) را برای اضافه کردن قسمت مربوطه فایل کد استفاده کنید. می‌توانید نام ناحیه سفارشی را پس از `#` به دنبال مسیر فایل تعیین کنید:
**ورودی**
```md
<<< @/snippets/snippet-with-region.js#snippet{1}
```
**فایل کد**
<<< @/snippets/snippet-with-region.js
**خروجی**
<<< @/snippets/snippet-with-region.js#snippet{1}
همچنین می‌توانید زبان را داخل آکولادها (`{}`) مشخص کنید:
```md
<<< @/snippets/snippet.cs{c#}
<!-- با highlight خطوط: -->
<<< @/snippets/snippet.cs{1,2,4-6 c#}
<!-- با شماره‌گذاری خطوط: -->
<<< @/snippets/snippet.cs{1,2,4-6 c#:line-numbers}
```
این قابلیت مفید است اگر زبان منبع نمی‌تواند از پسوند فایل استنتاج شود.
### گروه‌های کد {#code-groups}
می‌توانید چندین بلوک کد را به این شکل گروه‌بندی کنید:
**ورودی**
````md
::: code-group
```js [config.js]
/**
* @type {import('vitepress').UserConfig}
*/
const config = {
// ...
}
export default config
```
```ts [config.ts]
import type { UserConfig } from 'vitepress'
const config: UserConfig = {
// ...
}
export default config
```
:::
````
**خروجی**
::: code-group
```js [config.js]
/**
* @type {import('vitepress').UserConfig}
*/
const config = {
// ...
}
export default config
```
```ts [config.ts]
import type { UserConfig } from 'vitepress'
const config: UserConfig = {
// ...
}
export default config
```
:::
همچنین می‌توانید [قطعات کد](#import-code-snippets) را در گروه‌های کد وارد کنید:
**ورودی**
```md
::: code-group
<!-- به طور پیش‌فرض نام فایل به عنوان عنوان استفاده می‌شود -->
<<< @/snippets/snippet.js
<!-- می‌توانید یک عنوان سفارشی نیز ارائه دهید -->
<<< @/snippets/snippet-with-region.js#snippet{1,2 ts:line-numbers} [قطعه با منطقه]
:::
```
**خروجی**
::: code-group
<<< @/snippets/snippet.js
<<< @/snippets/snippet-with-region.js#snippet{1,2 ts:line-numbers} [قطعه با منطقه]
:::
## ادغام فایل‌های Markdown {#markdown-file-inclusion}
می‌توانید یک فایل Markdown را در یک فایل Markdown دیگر، حتی در صورت وجود تو در تو، وارد کنید.
::: tip نکته
می‌توانید مسیر Markdown را با `@` پیش‌فرض کنید. این به عنوان ریشه منبع عمل می‌کند. به طور پیش‌فرض، ریشه پروژه ویت‌پرس است، مگر اینکه `srcDir` پیکربندی شده باشد.
:::
به عنوان مثال، می‌توانید یک فایل Markdown نسبی را با استفاده از این کد وارد کنید:
**ورودی**
```md
# مستندات
## مبانی
<!--@include: ./parts/basics.md-->
```
**قسمت فایل** (`parts/basics.md`)
```md
بعضی موارد مربوط به شروع کار.
### پیکربندی
می‌توان با استفاده از `.foorc.json` ایجاد شد.
```
**کد معادل**
```md
# مستندات
## مبانی
بعضی موارد مربوط به شروع کار.
### پیکربندی
می‌توان با استفاده از `.foorc.json` ایجاد شد.
```
همچنین از انتخاب یک محدوده خطی پشتیبانی می‌کند:
**ورودی**
```md
# مستندات
## مبانی
<!--@include: ./parts/basics.md{3,}-->
```
**قسمت فایل** (`parts/basics.md`)
```md
بعضی موارد مربوط به شروع کار.
### پیکربندی
می‌توان با استفاده از `.foorc.json` ایجاد شد.
```
**کد معادل**
```md
# مستندات
## مبانی
### پیکربندی
می‌توان با استفاده از `.foorc.json` ایجاد شد.
```
قالب محدوده خطی می‌تواند شامل `{3,}`, `{,10}`, `{1,10}` باشد.
همچنین می‌توانید از [ناحیه VS Code](https://code.visualstudio.com/docs/editor/codebasics#_folding) برای اضافه کردن بخش متناظر فایل کد استفاده کنید. می‌توانید پس از `#` نام ناحیه سفارشی را پس از مسیر فایل دنبال کنید:
**ورودی**
```md
# مستندات
## مبانی
<!--@include: ./parts/basics.md#basic-usage{,2}-->
<!--@include: ./parts/basics.md#basic-usage{5,}-->
```
**قسمت فایل** (`parts/basics.md`)
```md
<!-- #region basic-usage -->
## استفاده خط 1
## استفاده خط 2
## استفاده خط 3
<!-- #endregion basic-usage -->
```
**کد معادل**
```md
# مستندات
## مبانی
## استفاده خط 1
## استفاده خط 3
```
::: warning هشدار
توجه داشته باشید که این اقدام منجر به خطا نمی‌شود اگر فایل شما وجود نداشته باشد. بنابراین، در استفاده از این ویژگی، مطمئن شوید که محتوا به درستی نمایش داده می‌شود.
:::
## معادلات ریاضی {#math-equations}
در حال حاضر این گزینه اختیاری است. برای فعال‌سازی آن، باید `markdown-it-mathjax3` را نصب کرده و `markdown.math` را در فایل پیکربندی خود به `true` تنظیم کنید:
```sh
npm add -D markdown-it-mathjax3
```
```ts
// .vitepress/config.ts
export default {
markdown: {
math: true
}
}
```
**ورودی**
```md
وقتی $a \ne 0$ است، دو حل برای $(ax^2 + bx + c = 0)$ وجود دارد و آن‌ها عبارتند از
$$ x = {-b \pm \sqrt{b^2-4ac} \over 2a} $$
**معادلات مکسول**
| equation | description |
| ------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------- |
| $\nabla \cdot \vec{\mathbf{B}} = 0$ | تنوع $\vec{\mathbf{B}}$ صفر است |
| $\nabla \times \vec{\mathbf{E}}\, +\, \frac1c\, \frac{\partial\vec{\mathbf{B}}}{\partial t} = \vec{\mathbf{0}}$ | curl $\vec{\mathbf{E}}$ نسبت به نرخ تغییر $\vec{\mathbf{B}}$ نسبی است |
| $\nabla \times \vec{\mathbf{B}} -\, \frac1c\, \frac{\partial\vec{\mathbf{E}}}{\partial t} = \frac{4\pi}{c}\vec{\mathbf{j}} \nabla \cdot \vec{\mathbf{E}} = 4 \pi \rho$ | _چیست؟_ |
```
**خروجی**
وقتی $a \ne 0$ است، دو حل برای $(ax^2 + bx + c = 0)$
وجود دارد و آن‌ها عبارتند از
$$ x = {-b \pm \sqrt{b^2-4ac} \over 2a} $$
**معادلات مکسول**
| equation | description |
| ------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------- |
| $\nabla \cdot \vec{\mathbf{B}} = 0$ | تنوع $\vec{\mathbf{B}}$ صفر است |
| $\nabla \times \vec{\mathbf{E}}\, +\, \frac1c\, \frac{\partial\vec{\mathbf{B}}}{\partial t} = \vec{\mathbf{0}}$ | curl $\vec{\mathbf{E}}$ نسبت به نرخ تغییر $\vec{\mathbf{B}}$ نسبی است |
| $\nabla \times \vec{\mathbf{B}} -\, \frac1c\, \frac{\partial\vec{\mathbf{E}}}{\partial t} = \frac{4\pi}{c}\vec{\mathbf{j}} \nabla \cdot \vec{\mathbf{E}} = 4 \pi \rho$ | _چیست؟_ |
## بارگذاری lazy تصویر {#image-lazy-loading}
می‌توانید بارگذاری تنبلی را برای هر تصویر اضافه شده از طریق Markdown با تنظیم `lazyLoading` به `true` در فایل پیکربندی فعال کنید:
```js
export default {
markdown: {
image: {
// بارگذاری تنبلی تصویر به طور پیش‌فرض غیرفعال است
lazyLoading: true
}
}
}
```
## پیکربندی پیشرفته {#advanced-configuration}
ویت‌پرس از [markdown-it](https://github.com/markdown-it/markdown-it) به عنوان نمایشگر Markdown استفاده می‌کند. اکثر افزونه‌های فوق را با استفاده از افزونه‌های سفارشی پیاده‌سازی کرده‌ایم. می‌توانید نمونه‌ای بیشتر از نمونه `markdown-it` را با استفاده از گزینه `markdown` در `.vitepress/config.js` سفارشی‌سازی کنید:
```js
import { defineConfig } from 'vitepress'
import markdownItAnchor from 'markdown-it-anchor'
import markdownItFoo from 'markdown-it-foo'
export default defineConfig({
markdown: {
// گزینه‌های markdown-it-anchor
// https://github.com/valeriangalliat/markdown-it-anchor#usage
anchor: {
permalink: markdownItAnchor.permalink.headerLink()
},
// گزینه‌های @mdit-vue/plugin-toc
// https://github.com/mdit-vue/mdit-vue/tree/main/packages/plugin-toc#options
toc: { level: [1, 2] },
config: (md) => {
// استفاده از افزونه‌های markdown-it بیشتر!
md.use(markdownItFoo)
}
}
})
```
برای دیدن لیست کامل خصوصیات قابل تنظیم، به [مرجع تنظیمات: پیکربندی برنامه](../reference/site-config#markdown) مراجعه کنید.

@ -0,0 +1,23 @@
# مهاجرت از ویت‌پرس 0.x
اگر از نسخه 0.x ویت‌پرس می‌آیید، تغییرات قابل توجهی به دلیل ویژگی‌ها و بهبودهای جدید وجود دارد. لطفاً این راهنما را دنبال کنید تا ببینید چگونه برنامه خود را به ویت‌پرس جدیدتر منتقل کنید.
## پیکربندی برنامه
- ویژگی بین‌المللی‌سازی هنوز اجرا نشده است.
## پیکربندی تم
- گزینه `sidebar` ساختار خود را تغییر داده است.
- کلید `children` حالا به نام `items` نامیده می‌شود.
- در حال حاضر ممکن است مورد بالادستی حاوی `link` نباشد. ما قصد داریم این گزینه را بازگردانیم.
- `repo`، `repoLabel`، `docsDir`، `docsBranch`، `editLinks`، `editLinkText` به منظور API انعطاف‌پذیرتر حذف شده‌اند.
- برای اضافه کردن لینک GitHub با آیکون به نوار ناوبری، از ویژگی [پیوندهای اجتماعی](../reference/default-theme-nav#navigation-links) استفاده کنید.
- برای اضافه کردن ویژگی "ویرایش این صفحه"، از ویژگی [پیوند ویرایش](../reference/default-theme-edit-link) استفاده کنید.
- گزینه `lastUpdated` حالا به `config.lastUpdated` و `themeConfig.lastUpdatedText` تقسیم شده است.
- `carbonAds.carbon` به `carbonAds.code` تغییر کرده است.
## پیکربندی Frontmatter
- گزینه `home: true` به `layout: home` تغییر کرده است. همچنین، تنظیمات مربوط به صفحه اصلی بسیار تغییر کرده‌اند تا ویژگی‌های اضافی را ارائه دهند. برای جزئیات بیشتر، [راهنمای صفحه اصلی](../reference/default-theme-home-page) را ببینید.
- گزینه `footer` به [`themeConfig.footer`](../reference/default-theme-config#footer) منتقل شده است.

@ -0,0 +1,30 @@
# مهاجرت از VuePress
## پیکربندی
### نوار کناری
نوار کناری دیگر به طور خودکار از frontmatter پر نمی‌شود. شما می‌توانید [frontmatter را خودتان بخوانید](https://github.com/vuejs/vitepress/issues/572#issuecomment-1170116225) تا نوار کناری به طور پویا پر شود. ابزارهای [اضافی برای این منظور](https://github.com/vuejs/vitepress/issues/96) ممکن است در آینده ارائه شود.
## Markdown
### تصاویر
برخلاف VuePress، ویت‌پرس وقتی شما از تصویر استاتیک استفاده می‌کنید، [`base`](./asset-handling#base-url) پیکربندی شما را به طور خودکار مدیریت می‌کند.
بنابراین، اکنون می‌توانید تصاویر را بدون استفاده از تگ `img` نمایش دهید.
```diff
- <img :src="$withBase('/foo.png')" alt="foo">
+ ![foo](/foo.png)
```
::: هشدار
برای تصاویر پویا، همچنان نیاز به استفاده از `withBase` به طوری که در [راهنمای Base URL](./asset-handling#base-url) نشان داده شده است، دارید.
:::
از عبارت `!<img.*withBase\('(.*)'\).*alt="([^"]*)".*>` برای جستجو و جایگزینی با `![$2]($1)` استفاده کنید تا تمام تصاویر را با سینتکس `![](...)` جایگزین کنید.
---
ادامه دارد...

@ -0,0 +1,23 @@
# حالت MPA <Badge type="warning" text="آزمایشی" /> {#mpa-mode}
حالت MPA (برنامه چند صفحه) می‌تواند از طریق خط فرمان با `vitepress build --mpa` فعال شود، یا از طریق تنظیمات با گزینه `mpa: true`.
در حالت MPA، همه صفحات به طور پیش‌فرض بدون هیچ جاوااسکریپتی رندر می‌شوند. به همین دلیل، سایت تولیدی احتمالاً امتیاز بهتری از ابزارهای آزمایشی در اولین بازدید دریافت خواهد کرد.
با این حال، به دلیل عدم وجود مسیریابی SPA، لینک‌های متقاطع به بازنشانی کامل صفحه منتهی می‌شوند. ناوبری پس از بارگیری در حالت MPA حساسیت به همان اندازه با حالت SPA نخواهد داشت.
همچنین توجه داشته باشید که عدم وجود JS به طور پیش‌فرض به این معنی است که شما اساساً Vue را به عنوان یک زبان قالب‌بندی سمت سرور استفاده می‌کنید. هیچ کنترل کننده رویدادی در مرورگر اضافه نمی‌شود، بنابراین هیچ تعاملی وجود نخواهد داشت. برای بارگیری JS سمت کلاینت، شما باید از تگ خاص `<script client>` استفاده کنید:
```html
<script client>
document.querySelector('h1').addEventListener('click', () => {
console.log('JavaScript سمت کلاینت!')
})
</script>
# سلام
```
`<script client>` یک ویژگی تنها برای ویت‌پرس است، نه یک ویژگی Vue. این در هر دو فایل `.md` و `.vue` کار می‌کند، اما فقط در حالت MPA. اسکریپت‌های کلاینت در تمام اجزای تم با هم بسته می‌شوند، در حالی که اسکریپت کلاینت برای یک صفحه خاص، فقط برای آن صفحه تقسیم می‌شود.
توجه داشته باشید که `<script client>` به عنوان **کد مؤلفه مؤلفه Vue** ارزیابی نمی‌شود: به عنوان یک ماژول جاوااسکریپت معمولی پردازش می‌شود. به همین دلیل، حالت MPA فقط باید در صورتی استفاده شود که سایت شما به تعامل کمینه‌ای از جانب کلاینت نیاز دارد.

@ -0,0 +1,377 @@
---
outline: deep
---
# مسیریابی {#routing}
## مسیریابی مبتنی بر فایل {#file-based-routing}
ویت‌پرس از مسیریابی مبتنی بر فایل استفاده می‌کند که به این معنی است که صفحات HTML تولید شده از ساختار دایرکتوری فایل‌های Markdown منبع نقشه‌بندی می‌شوند. به عنوان مثال، با توجه به ساختار دایرکتوری زیر:
```
.
├─ guide
│ ├─ getting-started.md
│ └─ index.md
├─ index.md
└─ prologue.md
```
صفحات HTML تولید شده به شرح زیر خواهد بود:
```
index.md --> /index.html (قابل دسترس به عنوان /)
prologue.md --> /prologue.html
guide/index.md --> /guide/index.html (قابل دسترس به عنوان /guide/)
guide/getting-started.md --> /guide/getting-started.html
```
این صفحات HTML نهایی می‌توانند بر روی هر سرور وبی که قادر به ارائه فایل‌های ایستا است، میزبانی شوند.
## ریشه و دایرکتوری منبع {#root-and-source-directory}
در ساختار فایل پروژه ویت‌پرس، دو مفهوم مهم وجود دارد: **ریشه پروژه** و **دایرکتوری منبع**.
### ریشه پروژه {#project-root}
ریشه پروژه جایی است که ویت‌پرس سعی می‌کند برای دایرکتوری ویژه `.vitepress` را بررسی کند. دایرکتوری `.vitepress` مکانی رزرو شده برای فایل پیکربندی، حافظه نهان سرور توسعه، خروجی ساخت، و کد سفارشی‌سازی موضوع اختیاری ویت‌پرس است.
زمانی که شما دستور `vitepress dev` یا `vitepress build` را از خط فرمان اجرا می‌کنید، ویت‌پرس از دایرکتوری کاری فعلی به عنوان ریشه پروژه استفاده می‌کند. برای مشخص کردن یک زیردایرکتوری به عنوان ریشه، باید مسیر نسبی را به دستور ارسال کنید. به عنوان مثال، اگر پروژه ویت‌پرس شما در `./docs` قرار دارد، باید دستور `vitepress dev docs` را اجرا کنید:
```
.
├─ docs # ریشه پروژه
│ ├─ .vitepress # دایرکتوری پیکربندی
│ ├─ getting-started.md
│ └─ index.md
└─ ...
```
```sh
vitepress dev docs
```
این عمل به نتیجه زیر منجر می‌شود:
```
docs/index.md --> /index.html (قابل دسترس به عنوان /)
docs/getting-started.md --> /getting-started.html
```
### دایرکتوری منبع {#source-directory}
دایرکتوری منبع جایی است که فایل‌های منبع Markdown شما قرار می‌گیرند. به طور پیش‌فرض، این همانند ریشه پروژه است. با این حال، شما می‌توانید آن را از طریق گزینه [`srcDir`](../reference/site-config#srcdir) پیکربندی کنید.
گزینه `srcDir` نسبت به ریشه پروژه حل می‌شود. به عنوان مثال، با `srcDir: 'src'`، ساختار فایل شما به این صورت خواهد بود:
```
. # ریشه پروژه
├─ .vitepress # دایرکتوری پیکربندی
└─ src # دایرکتوری منبع
├─ getting-started.md
└─ index.md
```
نتیجه نقشه‌بندی منبع به HTML:
```
src/index.md --> /index.html (قابل دسترس به عنوان /)
src/getting-started.md --> /getting-started.html
```
## لینک‌دهی بین صفحات {#linking-between-pages}
می‌توانید هنگام لینک‌دهی بین صفحات از مسیرهای نسبی و مطلق استفاده کنید. توجه داشته باشید که با اینکه هر دو پسوند `.md` و `.html` کار می‌کنند، بهتر است که پسوندها را حذف کنید تا ویت‌پرس بتواند URLهای نهایی را بر اساس پیکربندی شما تولید کند.
```md
<!-- درست -->
[شروع کار](./getting-started)
[شروع کار](../guide/getting-started)
<!-- نادرست -->
[شروع کار](./getting-started.md)
[شروع کار](./getting-started.html)
```
جهت آشنایی بیشتر با لینک‌دهی به منابع مانند تصاویر به [مدیریت منابع](./asset-handling) مراجعه کنید.
### لینک‌دهی به صفحات غیر ویت‌پرس {#linking-to-non-vitepress-pages}
اگر می‌خواهید به یک صفحه در وب‌سایت خود لینک دهید که توسط ویت‌پرس تولید نشده است، باید یا از URL کامل (باز می‌شود در یک تب جدید) استفاده کنید، یا هدف را به طور صریح مشخص کنید:
**ورودی**
```md
[لینک به pure.html](/pure.html){target="_self"}
```
**خروجی**
[لینک به pure.html](/pure.html){target="_self"}
::: tip توجه
در لینک‌های Markdown، `base` به طور خودکار به URL پیشوند داده می‌شود. این بدان معنی است که اگر می‌خواهید به صفحه‌ای خارج از پایه خود لینک دهید، باید چیزی شبیه `../../pure.html` را در لینک استفاده کنید (توسط مرورگر نسبت به صفحه فعلی حل می‌شود).
در غیر این صورت، می‌توانید به طور مستقیم از anchor tag syntax استفاده کنید:
```md
<a href="/pure.html" target="_self">لینک به pure.html</a>
```
:::
## تولید URLهای تمیز {#generating-clean-url}
::: warning نیازمندی پشتیبانی سرور
برای ارائه URLهای تمیز با ویت‌پرس، نیاز به پشتیبانی سمت سرور وجود دارد.
:::
به طور پیش‌فرض، ویت‌پرس لینک‌های ورودی را به URLهایی با پسوند `.html` حل می‌کند. با این حال، برخی از کاربران ممکن است از URLهای "تمیز" بدون پسوند `.html` استفاده کنند - به عنوان مثال، `example.com/path` به جای `example.com/path.html`.
برخی از سرورها یا پلتفرم‌های میزبانی (مانند Netlify، Vercel، GitHub Pages) امکان این را فراهم می‌کنند که یک URL مانند `/foo` به `/foo.html` نگاشت شود اگر موجود باشد، بدون انتقال:
- Netlify و GitHub Pages این را به طور پیش‌فرض پشتیبانی می‌کنند.
- Vercel نیاز به فعال‌سازی [`cleanUrls` در `vercel.json`](https://vercel.com/docs/concepts/projects/project-configuration#cleanurls) دارد.
اگر این ویژگی برای شما در دسترس است، می‌توانید از گزینه پیکربندی خود ویت‌پرس به نام [`cleanUrls`](../reference/site-config#cleanurls) استفاده کنید تا:
- لینک‌های ورودی بین صفحات بدون پسوند `.html` تولید شوند.
- اگر مسیر کنونی با `.html` ختم شود، مسیریاب به صورت تغییر مسیر کلاینت به مسیر بدون پسوند انجام می‌دهد.
اگر امکان پیکربندی سرور شما برای این پشتیبانی وجود نداشته باشد، شما باید به صورت دستی به ساختار دایرکتوری زیر رجوع کنید:
```
.
├─ getting-started
│ └─ index.md
├─ installation
│ └─ index.md
└─ index.md
```
## بازنویسی مسیر {#route-rewrites}
می‌توانید نقشه‌بندی بین ساختار دایرکتوری منبع و صفحات تولید شده را سفارشی‌سازی کنید. این ویژگی وقتی مفید است که یک ساختار پروژه پیچیده داشته باشید. به عنوان مثال، فرض کنید یک مونورپو با چند بسته دارید و می‌خواهید مستندات را همراه با فایل‌های منبع قرار دهید مانند این:
```
.
├─ packages
│ ├─ pkg-a
│ │ └─ src
│ │ ├─ pkg-a-code.ts
│ │ └─ pkg-a-docs.md
│ └─ pkg-b
│ └─ src
│ ├─ pkg-b-code.ts
│ └─ pkg-b-docs.md
```
و می‌خواهید صفحات ویت‌پرس به این صورت تولید شوند:
```
packages/pkg-a/src/pkg-a-docs.md --> /pkg-a/index.html
packages/pkg-b/src/pkg-b-docs.md --> /pkg-b/index.html
```
می‌توانید این کار را با پیکربندی گزینه [`rewrites`](../reference/site-config#rewrites) مانند زیر انجام دهید:
```ts
// .vitepress/config.js
export default {
rewrites: {
'packages/pkg-a/src/pkg-a-docs.md': 'pkg-a/index.md',
'packages/pkg-b/src/pkg-b-docs.md': 'pkg-b/index.md'
}
}
```
گزینه `rewrites` همچنین پارامترهای مسیر پویایی را پشتیبانی می‌کند. در مثال بالا، اگر تعداد بسیاری از بسته‌ها داشته باشید، لیست کردن همه مسیرها به شکل زیر ممکن است طولانی باشد. با توجه به اینکه همه دارای ساختار فایل یکسان هستند، می‌توانید پیکربندی را به این صورت ساده‌تر کنید:
```ts
export default {
rewrites: {
'packages/:pkg/src/(.*)': ':pkg/index.md'
}
}
```
مسیرهای بازنویسی با استفاده از بسته `path-to-regexp` ترجمه می‌شوند - برای جزئیات بیشتر به [مستندات آن](https://github.com/pillarjs/path-to-regexp#parameters) مراجعه کنید.
::: warning لینک‌های نسبی با بازنویسی
زمانی که بازنویسی‌ها فعال باشند، **لینک‌های نسبی باید بر اساس مسیرهای بازنویسی باشند**. به عنوان مثال، برای ایجاد یک لینک نسبی از `packages/pkg-a/src/pkg-a-code.md` به `packages/pkg-b/src/pkg-b-code.md`، باید از مورد زیر استفاده کنید:
```md
[لینک به PKG B](../pkg-b/pkg-b-code)
```
:::
## مسیرهای پویا {#dynamic-routes}
می‌توانید صفحات زیادی را با استفاده از یک فایل Markdown و داده‌های پویا تولید کنید. به عنوان مثال، می‌توانید یک فایل `packages/[pkg].md` ایجاد کنید که برای هر بسته در یک پروژه، یک صفحه متناظر تولید می‌کند. در اینجا، بخش `[pkg]` یک پارامتر مسیر است که هر صفحه را از دیگران تمایز می‌دهد.
### فایل بارگیری مسیرها {#paths-loader-file}
از آنجایی که ویت‌پرس یک موتور سایت ایستا است، مسیرهای ممکن باید در زمان ساخت تعیین شوند. بنابراین، یک صفحه مسیر پویا باید همراه با یک **فایل بارگیری مسیرها** همراه باشد. برای `packages/[pkg].md`، به `packages/[pkg].paths.js` (همچنین `.ts` پشتیبانی می‌شود) نیاز داریم:
```
.
└─ packages
├─ [pkg].md # قالب مسیر
└─ [pkg].paths.js # فایل بارگیری
مسیرها
```
فایل بارگیری باید یک شیء با یک متد `paths` به عنوان export پیش‌فرض ارائه دهد. متد `paths` باید آرایه‌ای از اشیاء با خصوصیت `params` را برگرداند. هر یک از این اشیاء یک صفحه متناظر را ایجاد می‌کنند.
با توجه به آرایه `paths` زیر:
```js
// packages/[pkg].paths.js
export default {
paths() {
return [
{ params: { pkg: 'foo' }},
{ params: { pkg: 'bar' }}
]
}
}
```
صفحات HTML تولید شده به شرح زیر خواهد بود:
```
.
└─ packages
├─ foo.html
└─ bar.html
```
### چندین پارامتر {#multiple-params}
یک مسیر پویا می‌تواند شامل چندین پارامتر باشد:
**ساختار فایل**
```
.
└─ packages
├─ [pkg]-[version].md
└─ [pkg]-[version].paths.js
```
**بارگیری مسیرها**
```js
export default {
paths: () => [
{ params: { pkg: 'foo', version: '1.0.0' }},
{ params: { pkg: 'foo', version: '2.0.0' }},
{ params: { pkg: 'bar', version: '1.0.0' }},
{ params: { pkg: 'bar', version: '2.0.0' }}
]
}
```
**خروجی**
```
.
└─ packages
├─ foo-1.0.0.html
├─ foo-2.0.0.html
├─ bar-1.0.0.html
└─ bar-2.0.0.html
```
### تولید پویای مسیرها {#dynamically-generating-paths}
ماژول بارگیری مسیر در Node.js اجرا می‌شود و تنها در زمان ساخت اجرا می‌شود. شما می‌توانید آرایه‌ی مسیرها را با استفاده از هر داده‌ای، سطحی یا از راه دور، به صورت پویا تولید کنید.
تولید مسیرها از فایل‌های محلی:
```js
import fs from 'fs'
export default {
paths() {
return fs
.readdirSync('packages')
.map((pkg) => {
return { params: { pkg }}
})
}
}
```
تولید مسیرها از داده‌های از راه دور:
```js
export default {
async paths() {
const pkgs = await (await fetch('https://my-api.com/packages')).json()
return pkgs.map((pkg) => {
return {
params: {
pkg: pkg.name,
version: pkg.version
}
}
})
}
}
```
### دسترسی به پارامترها در صفحه {#accessing-params-in-page}
شما می‌توانید از پارامترها برای انتقال داده‌های اضافی به هر صفحه استفاده کنید. فایل مسیر Markdown می‌تواند از پارامترهای صفحه کنونی در عبارات Vue با استفاده از خاصیت `$params` global استفاده کند:
```md
- نام بسته: {{ $params.pkg }}
- نسخه: {{ $params.version }}
```
همچنین می‌توانید به پارامترهای کنونی صفحه از طریق [`useData`](../reference/runtime-api#usedata) runtime API دسترسی داشته باشید. این در هر دو فایل Markdown و کامپوننت‌های Vue در دسترس است:
```vue
<script setup>
import { useData } from 'vitepress'
// params یک Vue ref است
const { params } = useData()
console.log(params.value)
</script>
```
### نمایش محتوای خام {#rendering-raw-content}
پارامترهای ارسال شده به صفحه در بارگذاری JavaScript کلاینت سریال می‌شوند، بنابراین باید از ارسال داده‌های سنگین در پارامترها خودداری کنید، برای مثال محتوای خام Markdown یا HTML از یک CMS از راه دور.
به جای اینکه می‌توانید محتوای چنین محتوایی را در هر صفحه با استفاده از خاصیت `content` روی هر شیء مسیر ارسال کنید:
```js
export default {
async paths() {
const posts = await (await fetch('https://my-cms.com/blog-posts')).json()
return posts.map((post) => {
return {
params: { id: post.id },
content: post.content // Markdown یا HTML خام
}
})
}
}
```
سپس، از دستورات ویژه‌ی زیر برای نمایش محتوا به عنوان بخشی از فایل Markdown استفاده کنید:
```md
<!-- @content -->
```

@ -0,0 +1,58 @@
# جنریت کردن Sitemap {#sitemap-generation}
ویت‌پرس با پشتیبانی بیرونی برای تولید فایل `sitemap.xml` برای سایت شما ارائه می‌شود. برای فعال‌سازی آن، موارد زیر را به فایل `.vitepress/config.js` خود اضافه کنید:
```ts
export default {
sitemap: {
hostname: 'https://example.com'
}
}
```
برای داشتن تگ‌های `<lastmod>` در فایل `sitemap.xml` خود، می‌توانید گزینه [`lastUpdated`](../reference/default-theme-last-updated) را فعال کنید.
## گزینه‌ها {#options}
پشتیبانی از sitemap توسط ماژول [`sitemap`](https://www.npmjs.com/package/sitemap) ارائه شده است. می‌توانید هر گزینه‌ای که توسط این ماژول پشتیبانی می‌شود را به گزینه `sitemap` در فایل پیکربندی خود منتقل کنید. این گزینه‌ها به طور مستقیم به سازنده `SitemapStream` منتقل می‌شوند. برای جزئیات بیشتر به [مستندات sitemap](https://www.npmjs.com/package/sitemap#options-you-can-pass) مراجعه کنید. مثال:
```ts
export default {
sitemap: {
hostname: 'https://example.com',
lastmodDateOnly: false
}
}
```
اگر از `base` در پیکربندی خود استفاده می‌کنید، باید آن را به گزینه `hostname` اضافه کنید:
```ts
export default {
base: '/my-site/',
sitemap: {
hostname: 'https://example.com/my-site/'
}
}
```
## هوک `transformItems` {#transformitems-hook}
می‌توانید از هوک `sitemap.transformItems` برای اصلاح موارد sitemap قبل از نوشتن آن‌ها به فایل `sitemap.xml` استفاده کنید. این هوک با یک آرایه از موارد sitemap فراخوانی می‌شود و انتظار دارد که یک آرایه از موارد sitemap بازگردانده شود. مثال:
```ts
export default {
sitemap: {
hostname: 'https://example.com',
transformItems: (items) => {
// اضافه کردن موارد جدید یا اصلاح/فیلتر کردن موارد موجود
items.push({
url: '/extra-page',
changefreq: 'monthly',
priority: 0.8
})
return items
}
}
}
```

@ -0,0 +1,136 @@
---
outline: deep
---
# تطابق SSR {#ssr-compatibility}
ویت‌پرس، با استفاده از قابلیت‌های رندرینگ سمت سرور (SSR) ارائه شده توسط Vue، اپلیکیشن را در Node.js در هنگام ساخت تولیدی پیش از رندر می‌کند. این بدان معناست که کلیه کدهای سفارشی در اجزای تم به تطابق SSR وابسته هستند.
[بخش SSR در مستندات رسمی Vue](https://vuejs.org/guide/scaling-up/ssr.html) بیشتر در مورد SSR، ارتباط بین SSR / SSG و نکات متداول در نوشتن کد‌های سازگار با SSR توضیح می‌دهد. قانون عمده این است که فقط در `beforeMount` یا `mounted` هوک‌های اجزای Vue از APIهای مرورگر / DOM استفاده کنید.
## `<ClientOnly>` {#clientonly}
اگر از اجزا یا دموهایی استفاده می‌کنید که سازگاری با SSR ندارند (برای مثال حاوی دستورالعمل‌های سفارشی هستند)، می‌توانید آن‌ها را درون کامپوننت داخلی `<ClientOnly>` قرار دهید:
```md
<ClientOnly>
<NonSSRFriendlyComponent />
</ClientOnly>
```
## کتابخانه‌هایی که در هنگام وارد کردن به API مرورگر دسترسی دارند {#libraries-that-access-browser-api-on-import}
بعضی از کتابخانه‌ها یا اجزا در هنگام وارد کردن به APIهای مرورگر **دسترسی دارند**. برای استفاده از کدی که فرض می‌کند محیطی مرورگر در هنگام وارد کردن وجود دارد، باید آن‌ها را به صورت پویا وارد کنید.
### وارد کردن در هوک Mounted {#importing-in-mounted-hook}
```vue
<script setup>
import { onMounted } from 'vue'
onMounted(() => {
import('./lib-that-access-window-on-import').then((module) => {
// استفاده از کد
})
})
</script>
```
### وارد کردن شرطی {#conditional-import}
می‌توانید همچنین وابستگی را با استفاده از `import.meta.env.SSR` (قسمتی از [متغیرهای env Vite](https://vitejs.dev/guide/env-and-mode.html#env-variables)) به شرط وارد کنید:
```js
if (!import.meta.env.SSR) {
import('./lib-that-access-window-on-import').then((module) => {
// استفاده از کد
})
}
```
از آنجا که `Theme.enhanceApp` می‌تواند async باشد، می‌توانید به صورت شرطی پلاگین‌های Vue را که دسترسی به APIهای مرورگر را هنگام وارد کردن دارند، وارد و ثبت کنید:
```js
// .vitepress/theme/index.js
/** @type {import('vitepress').Theme} */
export default {
// ...
async enhanceApp({ app }) {
if (!import.meta.env.SSR) {
const plugin = await import('plugin-that-access-window-on-import')
app.use(plugin.default)
}
}
}
```
اگر از TypeScript استفاده می‌کنید:
```ts
// .vitepress/theme/index.ts
import type { Theme } from 'vitepress'
export default {
// ...
async enhanceApp({ app }) {
if (!import.meta.env.SSR) {
const plugin = await import('plugin-that-access-window-on-import')
app.use(plugin.default)
}
}
} satisfies Theme
```
### `defineClientComponent` {#defineclientcomponent}
ویت‌پرس یک کمک‌کننده راحتی برای وارد کردن کامپوننت‌های Vue که هنگام وارد کردن به APIهای مرورگر دسترسی دارند فراهم می‌کند.
```vue
<script setup>
import { defineClientComponent } from 'vitepress'
const ClientComp = defineClientComponent(() => {
return import('component-that-access-window-on-import')
})
</script>
<template>
<ClientComp />
</template>
```
همچنین می‌توانید props/children/slots را به کامپوننت مقصد منتقل کنید:
```vue
<script setup>
import { ref } from 'vue'
import { defineClientComponent } from 'vitepress'
const clientCompRef = ref(null)
const ClientComp = defineClientComponent(
() => import('component-that-access-window-on-import'),
// آرگومان‌ها به h() منتقل می‌شوند - https://vuejs.org/api/render-function.html#h
[
{
ref: clientCompRef
},
{
default: () => 'اسلات پیش‌فرض',
foo: () => h('div', 'فو')
bar: () => [h('span', 'یک'), h('span', 'دو')]
}
],
// تابع بازخورد بعد از بارگذاری کامپوننت، می‌تواند async باشد
() => {
console.log(clientCompRef.value)
}
)
</script>
<template>
<ClientComp />
</template>
```
کامپوننت مقصد فقط در هوک Mounted کامپوننت پوشش وارد می‌شود.

@ -0,0 +1,257 @@
# استفاده از Vue در Markdown {#using-vue-in-markdown}
در ویت‌پرس، هر فایل Markdown به HTML تبدیل شده و سپس به عنوان یک [کامپوننت فایل تکی Vue](https://vuejs.org/guide/scaling-up/sfc.html) پردازش می‌شود. این بدان معنی است که شما می‌توانید از هر ویژگی Vue در داخل Markdown استفاده کنید، شامل قالب‌بندی پویا، استفاده از کامپوننت‌های Vue، یا منطق کامپوننت Vue دلخواه در داخل صفحه با افزودن تگ `<script>`.
مهم است که ویت‌پرس از کامپایلر Vue برای به‌طور خودکار شناسایی و بهینه‌سازی اجزای ثابت محتوای Markdown استفاده می‌کند. محتویات استاتیک به صورت یکنواخت به عنوان placeholder nodes بهینه‌سازی شده و از بارگذاری اولیه در JavaScript صفحه مستثنی می‌شوند. همچنین، در فرآیند hydration سمت کلاینت نیز نادیده گرفته می‌شوند. به طور خلاصه، شما فقط برای اجزای پویا در هر صفحه هزینه می‌پردازید.
::: tip سازگاری با SSR
همه استفاده‌های Vue باید با سازگاری SSR همخوانی داشته باشند. برای جزئیات و راه‌حل‌های متداول، به [سازگاری با SSR](./ssr-compat) مراجعه کنید.
:::
## قالب‌بندی {#templating}
### درون‌یابی(Interpolation) {#interpolation}
هر فایل Markdown ابتدا به HTML تبدیل شده و سپس به عنوان یک کامپوننت Vue به خط لوله فرآیند Vite ارسال می‌شود. این بدان معنی است که می‌توانید از درون‌یابی به سبک Vue در متن استفاده کنید:
**ورودی**
```md
{{ 1 + 1 }}
```
**خروجی**
<div class="language-text"><pre><code>{{ 1 + 1 }}</code></pre></div>
#### دستورالعمل‌ها {#directives}
دستورالعمل‌ها نیز کار می‌کنند (توجه داشته باشید که طراحی، HTML خام همچنین معتبر است):
**ورودی**
```html
<span v-for="i in 3">{{ i }}</span>
```
**خروجی**
<div class="language-text"><pre><code><span v-for="i in 3">{{ i }} </span></code></pre></div>
## `<script>` و `<style>` {#script-and-style}
تگ‌های `<script>` و `<style>` در سطح ریشه در فایل‌های Markdown همانند کارکرد آنها در SFC Vue کار می‌کنند، شامل `<script setup>`، `<style module>`، و غیره. تفاوت اصلی در اینجا این است که هیچ تگ `<template>` وجود ندارد: تمام محتویات سطح ریشه دیگر Markdown است. همچنین توجه داشته باشید که همه تگ‌ها باید **پس از** frontmatter قرار گیرند:
```html
---
hello: world
---
<script setup>
import { ref } from 'vue'
const count = ref(0)
</script>
## محتوای Markdown
تعداد: {{ count }}
<button :class="$style.button" @click="count++">افزایش</button>
<style module>
.button {
color: red;
font-weight: bold;
}
</style>
```
::: warning اجتناب از `<style scoped>` در Markdown
در استفاده از Markdown باید توجه داشت که `<style scoped>` نیازمند افزودن ویژگی‌های خاص به هر عنصر در صفحه فعلی است که باعث بزرگ شدن قابل‌ملاحظه اندازه صفحه می‌شود. هنگام نیاز به قالب‌بندی محلی محدود، استفاده از `<style module>` توصیه می‌شود.
:::
همچنین شما به دسترسی به APIهای runtime ویت‌پرس مانند [`useData` helper](../reference/runtime-api#usedata) دارید که امکان دسترسی به metadata صفحه فعلی را فراهم می‌کند:
**ورودی**
```html
<script setup>
import { useData } from 'vitepress'
const { page } = useData()
</script>
<pre>{{ page }}</pre>
```
**خروجی**
```json
{
"path": "/using-vue.html",
"title": "Using Vue in Markdown",
"frontmatter": {},
...
}
```
## استفاده از کامپوننت‌ها {#using-components}
شما می‌توانید کامپوننت‌های Vue را مستقیماً در فایل‌های Markdown وارد و استفاده کنید.
### وارد کردن در Markdown {#importing-in-markdown}
اگر یک کامپوننت تنها توسط چند صفحه استفاده می‌شود، توصیه می‌شود آنها را به صراحت در جایی که استفاده می‌شوند وارد کنید. این کار امکان تقسیم کد مناسب را فراهم می‌کند و فقط هنگام نمایش صفحات مربوطه بارگذاری می‌شوند:
```md
<script setup>
import CustomComponent from '../components/CustomComponent.vue'
</script>
# مستندات
این یک فایل .md با استفاده از یک کامپوننت اختصاصی است
<CustomComponent />
## مستندات بیشتر
...
```
### ثبت کامپوننت‌ها به صورت Global {#registering-components-globally}
اگر یک کامپوننت بر روی اکثر صفحات استفاده می‌شود، می‌توانید آنها را به صورت global با سفارشی‌سازی نمونه برنامه Vue ثبت کنید. برای مثال، بخش مربوطه را در [گسترش تم پیش‌فرض](./extending-default-theme#registering-global-components) بررسی کنید.
::: warning مهم
اطمینان حاصل کنید که نام یک کامپوننت سفارشی حاوی خط فاصله دارد یا به صورت PascalCase است. در غیر این صورت، به عنوان یک
عنصر داخلی تلقی می‌شود و درون یک تگ `<p>` قرار داده خواهد شد که باعث عدم هم‌سانی‌سازی hydration می‌شود چون `<p>` اجازه قرار دادن عناصر بلوک داخل آن را نمی‌دهد.
:::
### استفاده از کامپوننت‌ها در سربرگ‌ها <ComponentInHeader /> {#using-components-in-headers}
شما می‌توانید کامپوننت‌های Vue را در سربرگ‌ها استفاده کنید، اما تفاوت بین دو نحوه نگارش زیر را توجه کنید:
| Markdown | HTML خروجی | سربرگ تجزیه شده |
| ------------------------------------------------------- | ----------------------------------------- | ------------- |
| <pre v-pre><code> # text &lt;Tag/&gt; </code></pre> | `<h1>text <Tag/></h1>` | `text` |
| <pre v-pre><code> # text \`&lt;Tag/&gt;\` </code></pre> | `<h1>text <code>&lt;Tag/&gt;</code></h1>` | `text <Tag/>` |
HTML که توسط `<code>` محصور شده باشد به عنوان آن نمایش داده خواهد شد؛ تنها HTML که **محصور نشده باشد** توسط Vue تجزیه خواهد شد.
::: tip نکته
خروجی HTML توسط [Markdown-it](https://github.com/Markdown-it/Markdown-it) انجام می‌شود، در حالی که سربرگ‌های تجزیه شده توسط ویت‌پرس انجام می‌شود (و برای هر دو نوار کناری و عنوان سند استفاده می‌شود).
:::
## Escaping {#escaping}
شما می‌توانید درون‌یابی‌های Vue را با محصور کردن آنها در یک `<span>` یا عناصر دیگر با دستورالعمل `v-pre` فرار کنید:
**ورودی**
```md
This <span v-pre>{{ will be displayed as-is }}</span>
```
**خروجی**
<div class="escape-demo">
<p>This <span v-pre>{{ will be displayed as-is }}</span></p>
</div>
به طور جایگزین، می‌توانید کل پاراگراف را در یک ظرف سفارشی `v-pre` محصور کنید:
```md
::: v-pre
{{ This will be displayed as-is }}
:::
```
**خروجی**
<div class="escape-demo">
::: v-pre
{{ This will be displayed as-is }}
:::
</div>
## غیرفعال کردن در بلوک‌های کد {#unescape-in-code-blocks}
به طور پیش‌فرض، تمام بلوک‌های کد با حصار `v-pre` به صورت خودکار محصور می‌شوند، بنابراین هیچ نحوه درون‌یابی Vue در داخل آنها پردازش نمی‌شود. برای فعال کردن درون‌یابی به سبک Vue در داخل حصارها، می‌توانید زبان را با پسوند `-vue` اضافه کنید، به عنوان مثال `js-vue`:
**ورودی**
````md
```js-vue
Hello {{ 1 + 1 }}
```
````
**خروجی**
```js-vue
Hello {{ 1 + 1 }}
```
توجه داشته باشید که این ممکن است باعث جلوگیری از نمایش صحیح برخی نشانه‌ها در هایلایتینگ نحوه زبان شود.
## استفاده از پیش‌پردازنده‌های CSS {#using-css-pre-processors}
ویت‌پرس از [پشتیبانی داخلی](https://vitejs.dev/guide/features.html#css-pre-processors) برای پیش‌پردازنده‌های CSS مانند فایل‌های `.scss`، `.sass`، `.less`، `.styl` و `.stylus` پشتیبانی می‌کند. برای استفاده از آنها نیازی به نصب پلاگین‌های خاص Vite نیست، اما خود پیش‌پردازنده مربوطه باید نصب شده باشد:
```
# .scss و .sass
npm install -D sass
# .less
npm install -D less
# .styl و .stylus
npm install -D stylus
```
سپس می‌توانید در Markdown و کامپوننت‌های تم:
```vue
<style lang="sass">
.title
font-size: 20px
</style>
```
## استفاده از Teleport {#using-teleports}
در حال حاضر ویت‌پرس پشتیبانی از SSG برای teleport به body را دارد. برای اهداف دیگر، می‌توانید آنها را درون کامپوننت `<ClientOnly>` یا نشانه تله‌پورت به مکان مناسب در HTML صفحه نهایی خود از طریق [هوک postRender](../reference/site-config#postrender) درج کنید.
<ModalDemo />
::: details جزئیات
<<< @/components/ModalDemo.vue
:::
```md
<ClientOnly>
<Teleport to="#modal">
<div>
// ...
</div>
</Teleport>
</ClientOnly>
```
<script setup>
import ModalDemo from '../../components/ModalDemo.vue'
import ComponentInHeader from '../../components/ComponentInHeader.vue'
</script>
<style>
.escape-demo {
border: 1px solid var(--vp-c-border);
border-radius: 8px;
padding: 0 20px;
}
</style>

@ -0,0 +1,57 @@
# ویت‌پرس چیست؟ {#what-is-vitepress}
ویت‌پرس یک [تولید کننده سایت ایستا](https://en.wikipedia.org/wiki/Static_site_generator) (SSG) است که برای ساخت وب‌سایت‌های سریع و محتوا محور طراحی شده است. به طور خلاصه، ویت‌پرس محتوای منبع شما که به زبان [Markdown](https://en.wikipedia.org/wiki/Markdown) نوشته شده است را گرفته، یک تم بر روی آن اعمال می‌کند و صفحات HTML ایستا تولید می‌کند که به راحتی در هر جایی قابل استقرار هستند.
<div class="tip custom-block" style="padding-top: 8px">
فقط می‌خواهید آن را امتحان کنید؟ به [شروع سریع](./getting-started) بروید.
</div>
## موارد استفاده {#use-cases}
- **مستندسازی**
ویت‌پرس با یک تم پیش‌فرض طراحی شده برای مستندات فنی ارائه می‌شود. این صفحه‌ای که اکنون در حال خواندن آن هستید و همچنین مستندات [Vite](https://vitejs.dev/)، [Rollup](https://rollupjs.org/)، [Pinia](https://pinia.vuejs.org/)، [VueUse](https://vueuse.org/)، [Vitest](https://vitest.dev/)، [D3](https://d3js.org/)، [UnoCSS](https://unocss.dev/)، [Iconify](https://iconify.design/) و [بسیاری دیگر](https://www.vuetelescope.com/explore?framework.slug=vitepress) با استفاده از ویت‌پرس ساخته شده‌اند.
[مستندات رسمی Vue.js](https://vuejs.org/) نیز بر پایه ویت‌پرس ساخته شده است، اما از یک تم سفارشی که بین چندین ترجمه مشترک است استفاده می‌کند.
- **وبلاگ‌ها، نمونه کارها و سایت‌های بازاریابی**
ویت‌پرس از [تم‌های کاملاً سفارشی](./custom-theme) پشتیبانی می‌کند، با تجربه توسعه مشابه یک برنامه استاندارد Vite + Vue. با ساختن بر روی Vite، این امکان وجود دارد که مستقیماً از پلاگین‌های Vite از اکوسیستم غنی آن استفاده کنید. علاوه بر این، ویت‌پرس APIهای انعطاف‌پذیری برای [بارگذاری داده](./data-loading) (محلی یا از راه دور) و [تولید پویا مسیرها](./routing#dynamic-routes) ارائه می‌دهد. شما می‌توانید تقریباً هر چیزی را بسازید به شرطی که داده‌ها در زمان ساخت تعیین شوند.
وبلاگ رسمی [Vue.js](https://blog.vuejs.org/) یک وبلاگ ساده است که صفحه فهرست خود را بر اساس محتوای محلی تولید می‌کند.
## تجربه توسعه دهنده {#developer-experience}
ویت‌پرس هدف ارائه یک تجربه عالی برای توسعه دهنده (DX) هنگام کار با محتوای Markdown را دارد.
- **[قدرت گرفته از Vite:](https://vitejs.dev/)** شروع سرور فوری، با بازتاب ویرایش‌ها به صورت آنی (<100ms) بدون بارگذاری مجدد صفحه.
- **[افزونه‌های داخلی Markdown:](./markdown)** استفاده از Frontmatter، جداول، syntax highlighting... هرچه که بخواهید. ویت‌پرس به ویژه ویژگی‌های پیشرفته زیادی برای کار با بلوک‌های کد فراهم می‌کند، که آن را برای مستندات فنی بسیار مناسب می‌کند.
- **[Markdown بهبود یافته با Vue:](./using-vue)** هر صفحه Markdown نیز یک [کامپوننت تک فایل Vue](https://vuejs.org/guide/scaling-up/sfc.html) است، به لطف سازگاری ۱۰۰٪ سینتکسی قالب Vue با HTML. شما می‌توانید از ویژگی‌های قالب‌بندی Vue یا کامپوننت‌های وارد شده Vue برای ایجاد تعامل در محتوای ایستا خود استفاده کنید.
## عملکرد {#performance}
بر خلاف بسیاری از SSGهای سنتی که هر ناوبری منجر به بارگذاری کامل صفحه می‌شود، یک وب‌سایت تولید شده توسط ویت‌پرس در بازدید اولیه HTML ایستا را سرو می‌کند، اما برای ناوبری‌های بعدی در سایت به یک [برنامه تک صفحه‌ای](https://en.wikipedia.org/wiki/Single-page_application) (SPA) تبدیل می‌شود. به نظر ما، این مدل برای عملکرد بهترین تعادل را فراهم می‌کند:
- **بارگذاری اولیه سریع**
بازدید اولیه از هر صفحه، HTML پیش‌پردازش شده ایستا را برای سرعت بارگذاری سریع و بهینه‌سازی SEO سرو می‌کند. سپس صفحه یک بسته JavaScript را بارگذاری می‌کند که صفحه را به یک SPA Vue تبدیل می‌کند ("hydration"). بر خلاف فرضیات رایج که hydration برای SPA کند است، این فرآیند در واقع بسیار سریع است به لطف عملکرد خام Vue 3 و بهینه‌سازی‌های کامپایلر. در [PageSpeed Insights](https://pagespeed.web.dev/report?url=https%3A%2F%2Fvitepress.dev%2F)، سایت‌های معمولی ویت‌پرس حتی در دستگاه‌های موبایل پایین‌رده با شبکه کند به امتیازهای عملکردی تقریباً کامل دست می‌یابند.
- **ناوبری سریع پس از بارگذاری**
مهم‌تر از آن، مدل SPA منجر به تجربه کاربری بهتر **پس از** بارگذاری اولیه می‌شود. ناوبری‌های بعدی در سایت دیگر باعث بارگذاری کامل صفحه نمی‌شوند. در عوض، محتوای صفحه ورودی بارگذاری و به صورت پویا به‌روزرسانی می‌شود. ویت‌پرس همچنین به صورت خودکار تکه‌های صفحه را برای لینک‌هایی که در viewport هستند پیش‌بارگذاری (pre-fetch) می‌کند. در بیشتر موارد، ناوبری پس از بارگذاری به صورت آنی احساس می‌شود.
- **تعامل بدون جریمه**
برای اینکه بتوانید بخش‌های پویا Vue جاسازی شده در داخل Markdown ایستا را hydrated کنید، هر صفحه Markdown به عنوان یک کامپوننت Vue پردازش و به JavaScript کامپایل می‌شود. این ممکن است غیر بهینه به نظر برسد، اما کامپایلر Vue به اندازه کافی هوشمند است که بخش‌های ایستا و پویا را جدا کند، هزینه hydration و اندازه محموله را به حداقل برساند. برای بارگذاری اولیه صفحه، بخش‌های ایستا به صورت خودکار از محموله JavaScript حذف می‌شوند و در حین hydration نادیده گرفته می‌شوند.
## درباره VuePress چه؟ {#what-about-vuepress}
ویت‌پرس جانشین معنوی VuePress است. VuePress اصلی بر پایه Vue 2 و webpack بود. با Vue 3 و Vite در هسته، ویت‌پرس تجربه توسعه بهتر، عملکرد تولید بهتر، تم پیش‌فرض کامل‌تر و API سفارشی‌سازی انعطاف‌پذیرتری ارائه می‌دهد.
تفاوت API بین ویت‌پرس و VuePress عمدتاً در زمینه تم‌سازی و سفارشی‌سازی است. اگر از VuePress 1 با تم پیش‌فرض استفاده می‌کنید، باید مهاجرت به ویت‌پرس نسبتاً ساده باشد.
همچنین تلاش‌هایی برای VuePress 2 انجام شده است، که از Vue 3 و Vite با سازگاری بیشتر با VuePress 1 پشتیبانی می‌کند. با این حال، نگهداری دو SSG به صورت موازی پایدار نیست، بنابراین تیم Vue تصمیم گرفته است که در دراز مدت بر روی ویت‌پرس به عنوان SSG اصلی توصیه شده تمرکز کند.

@ -0,0 +1,65 @@
---
layout: home
title: ویت‌پرس
titleTemplate: Vite & Vue Powered Static Site Generator
hero:
name: ویت‌پرس
text: سازنده سایت‌های ایستا به کمک Vite و Vue
tagline: تبدیل Markdown به مستندات زیبا در چند دقیقه
actions:
- theme: brand
text: ویت‌پرس چیست؟
link: fa/guide/what-is-vitepress
- theme: alt
text: شروع سریع
link: fa/guide/getting-started
- theme: alt
text: گیت‌هاب
link: https://github.com/vuejs/vitepress
image:
src: /vitepress-logo-large.webp
alt: ویت‌پرس
features:
- icon: 📝
title: تمرکز روی محتوا
details: ایجاد سایت‌های مستند‌سازی زیبا بدون زحمت و فقط با Markdown
- icon: <svg xmlns="http://www.w3.org/2000/svg" width="30" viewBox="0 0 256 256.32"><defs><linearGradient id="a" x1="-.828%" x2="57.636%" y1="7.652%" y2="78.411%"><stop offset="0%" stop-color="#41D1FF"/><stop offset="100%" stop-color="#BD34FE"/></linearGradient><linearGradient id="b" x1="43.376%" x2="50.316%" y1="2.242%" y2="89.03%"><stop offset="0%" stop-color="#FFEA83"/><stop offset="8.333%" stop-color="#FFDD35"/><stop offset="100%" stop-color="#FFA800"/></linearGradient></defs><path fill="url(#a)" d="M255.153 37.938 134.897 252.976c-2.483 4.44-8.862 4.466-11.382.048L.875 37.958c-2.746-4.814 1.371-10.646 6.827-9.67l120.385 21.517a6.537 6.537 0 0 0 2.322-.004l117.867-21.483c5.438-.991 9.574 4.796 6.877 9.62Z"/><path fill="url(#b)" d="M185.432.063 96.44 17.501a3.268 3.268 0 0 0-2.634 3.014l-5.474 92.456a3.268 3.268 0 0 0 3.997 3.378l24.777-5.718c2.318-.535 4.413 1.507 3.936 3.838l-7.361 36.047c-.495 2.426 1.782 4.5 4.151 3.78l15.304-4.649c2.372-.72 4.652 1.36 4.15 3.788l-11.698 56.621c-.732 3.542 3.979 5.473 5.943 2.437l1.313-2.028 72.516-144.72c1.215-2.423-.88-5.186-3.54-4.672l-25.505 4.922c-2.396.462-4.435-1.77-3.759-4.114l16.646-57.705c.677-2.35-1.37-4.583-3.769-4.113Z"/></svg>
title: لذت از تجربه توسعه با Vite
details: شروع فوری سرور، به‌روزرسانی‌های سریع و استفاده از افزونه‌های اکوسیستم Vite
- icon: <svg xmlns="http://www.w3.org/2000/svg" width="30" viewBox="0 0 256 220.8"><path fill="#41B883" d="M204.8 0H256L128 220.8 0 0h97.92L128 51.2 157.44 0h47.36Z"/><path fill="#41B883" d="m0 0 128 220.8L256 0h-51.2L128 132.48 50.56 0H0Z"/><path fill="#35495E" d="M50.56 0 128 133.12 204.8 0h-47.36L128 51.2 97.92 0H50.56Z"/></svg>
title: شخصی‌سازی با Vue
details: استفاده مستقیم از syntax و کامپوننت‌های Vue در Markdown، یا ایجاد تم‌های شخصی به کمک Vue
- icon: 🚀
title: ارسال سایت های سریع
details: بارگذاری اولیه سریع با HTML ایستا، ناوبری سریع پس از بارگیری با مسیریابی سمت کلاینت
---
<style>
@import url("https://fonts.googleapis.com/css2?family=Vazirmatn:wght@100..900&display=swap");
:root {
--vp-font-family-base: "Vazirmatn", 'Inter', ui-sans-serif, system-ui, sans-serif,
'Apple Color Emoji', 'Segoe UI Emoji', 'Segoe UI Symbol', 'Noto Color Emoji';
--vp-home-hero-name-color: transparent;
--vp-home-hero-name-background: -webkit-linear-gradient(120deg, #bd34fe 30%, #41d1ff);
--vp-home-hero-image-background-image: linear-gradient(-45deg, #bd34fe 50%, #47caff 50%);
--vp-home-hero-image-filter: blur(44px);
}
@media (min-width: 640px) {
:root {
--vp-home-hero-image-filter: blur(56px);
}
}
@media (min-width: 960px) {
:root {
--vp-home-hero-image-filter: blur(68px);
}
}
</style>

@ -0,0 +1,74 @@
# رابط خط فرمان {#command-line-interface}
## `vitepress dev` {#vitepress-dev}
شروع سرور توسعه ویت‌پرس با استفاده از دایرکتوری مشخص به عنوان ریشه. به طور پیش‌فرض از دایرکتوری فعلی استفاده می‌شود. دستور `dev` همچنین می‌تواند حذف شود زمانی که در دایرکتوری فعلی اجرا می‌شود.
### استفاده {#usage}
```sh
# شروع در دایرکتوری فعلی، بدون `dev`
vitepress
# شروع در زیردایرکتوری
vitepress dev [root]
```
### گزینه‌ها {#options}
| گزینه | توضیحات |
| --------------- | ----------------------------------------------------------------- |
| `--open [path]` | باز کردن مرورگر در زمان راه‌اندازی (`boolean \| string`) |
| `--port <port>` | تعیین پورت (`number`) |
| `--base <path>` | مسیر پایه عمومی (پیش‌فرض: `/`) (`string`) |
| `--cors` | فعال‌سازی CORS |
| `--strictPort` | خروج در صورت استفاده از پورت مشخص شده (`boolean`) |
| `--force` | اجبار به نادیده گرفتن حافظه پنهان و بازسازی (`boolean`) |
## `vitepress build` {#vitepress-build}
ساخت سایت ویت‌پرس برای تولید نهایی.
### استفاده {#usage-1}
```sh
vitepress build [root]
```
### گزینه‌ها {#options-1}
| گزینه | توضیحات |
| ------------------------------ | ---------------------------------------------------------------------------------------------------------------- |
| `--mpa` (آزمایشی) | ساخت در حالت [MPA](../guide/mpa-mode) بدون هیدراسیون سمت مشتری (`boolean`) |
| `--base <path>` | مسیر پایه عمومی (پیش‌فرض: `/`) (`string`) |
| `--target <target>` | هدف ترنسپایل (پیش‌فرض: `"modules"`) (`string`) |
| `--outDir <dir>` | دایرکتوری خروجی نسبت به **cwd** (پیش‌فرض: `<root>/.vitepress/dist`) (`string`) |
| `--minify [minifier]` | فعال یا غیرفعال کردن فشرده‌سازی، یا تعیین فشرده‌سازی برای استفاده (پیش‌فرض: `"esbuild"`) (`boolean \| "terser" \| "esbuild"`) |
| `--assetsInlineLimit <number>` | آستانه تبدیل پایه ۶۴ استاتیک به بایت (پیش‌فرض: `4096`) (`number`) |
## `vitepress preview` {#vitepress-preview}
پیش‌نمایش محلی برای ساخت تولیدی را نمایش دهید.
### استفاده {#usage-2}
```sh
vitepress preview [root]
```
### گزینه‌ها {#options-2}
| گزینه | توضیحات |
| --------------- | ---------------------------------------- |
| `--base <path>` | مسیر پایه عمومی (پیش‌فرض: `/`) (`string`) |
| `--port <port>` | تعیین پورت (`number`) |
## `vitepress init` {#vitepress-init}
شروع [جادوگر راه‌اندازی](../guide/getting-started#setup-wizard) در دایرکتوری فعلی.
### استفاده {#usage-3}
```sh
vitepress init
```

@ -0,0 +1,72 @@
# نشان {#badge}
برچسب به شما امکان می‌دهد وضعیت‌های مختلفی را به سربرگ‌های خود اضافه کنید. به عنوان مثال، می‌تواند مفید باشد تا نوع بخش را مشخص کنید یا نسخه‌های پشتیبانی شده را نشان دهید.
## استفاده {#usage}
شما می‌توانید از کامپوننت `Badge` که به صورت جهانی در دسترس است، استفاده کنید.
```html
### عنوان <Badge type="info" text="پیش‌فرض" />
### عنوان <Badge type="tip" text="^1.9.0" />
### عنوان <Badge type="warning" text="بتا" />
### عنوان <Badge type="danger" text="هشدار" />
```
کد بالا به صورت زیر نمایش داده می‌شود:
### عنوان <Badge type="info" text="پیش‌فرض" /> {#title}
### عنوان <Badge type="tip" text="^1.9.0" /> {#title-1}
### عنوان <Badge type="warning" text="بتا" /> {#title-2}
### عنوان <Badge type="danger" text="هشدار" /> {#title-3}
## ارائه دادن محتوای دلخواه {#custom-children}
`<Badge>` می‌پذیرد `children` که در برچسب نمایش داده خواهد شد.
```html
### عنوان <Badge type="info">عنصر سفارشی</Badge>
```
### عنوان <Badge type="info">عنصر سفارشی</Badge>
## سفارشی‌سازی رنگ نوع {#customize-type-color}
شما می‌توانید استایل برچسب‌ها را با دوباره‌نویسی متغیرهای css سفارشی کنید. مقادیر پیش‌فرض به شرح زیر هستند:
```css
:root {
--vp-badge-info-border: transparent;
--vp-badge-info-text: var(--vp-c-text-2);
--vp-badge-info-bg: var(--vp-c-default-soft);
--vp-badge-tip-border: transparent;
--vp-badge-tip-text: var(--vp-c-brand-1);
--vp-badge-tip-bg: var(--vp-c-brand-soft);
--vp-badge-warning-border: transparent;
--vp-badge-warning-text: var(--vp-c-warning-1);
--vp-badge-warning-bg: var(--vp-c-warning-soft);
--vp-badge-danger-border: transparent;
--vp-badge-danger-text: var(--vp-c-danger-1);
--vp-badge-danger-bg: var(--vp-c-danger-soft);
}
```
## `<Badge>` {#badge-1}
کامپوننت `<Badge>` پراپ‌های زیر را می‌پذیرد:
```ts
interface Props {
// وقتی `<slot>` ارسال می‌شود، این مقدار نادیده گرفته می‌شود.
text?: string
// پیش‌فرض به `tip`.
type?: 'info' | 'tip' | 'warning' | 'danger'
}
```

@ -0,0 +1,22 @@
# تبلیغات Carbon {#carbon-ads}
ویت‌پرس پشتیبانی داخلی برای [Carbon Ads](https://www.carbonads.net/) را دارد. با تعریف مشخصات تبلیغات Carbon در تنظیمات، ویت‌پرس تبلیغات را در صفحه نمایش می‌دهد.
```js
export default {
themeConfig: {
carbonAds: {
code: 'your-carbon-code',
placement: 'your-carbon-placement'
}
}
}
```
این مقادیر برای فراخوانی اسکریپت CDN Carbon به شکل زیر استفاده می‌شوند.
```js
`//cdn.carbonads.com/carbon.js?serve=${code}&placement=${placement}`
```
برای یادگیری بیشتر درباره پیکربندی تبلیغات Carbon، لطفاً به [وب‌سایت Carbon Ads](https://www.carbonads.net/) مراجعه کنید.

@ -0,0 +1,469 @@
# پیکربندی پیش‌فرض تم {#default-theme-config}
پیکربندی تم به شما امکان می‌دهد تا تم خود را سفارشی کنید. شما می‌توانید پیکربندی تم را از طریق گزینه `themeConfig` در فایل پیکربندی تعریف کنید:
```ts
export default {
lang: 'en-US',
title: 'ویت‌پرس',
description: 'Vite & Vue powered static site generator.',
// پیکربندی‌های مربوط به تم.
themeConfig: {
logo: '/logo.svg',
nav: [...],
sidebar: { ... }
}
}
```
**گزینه‌های مستند شده در این صفحه تنها برای تم پیش‌فرض اعمال می‌شوند.** تم‌های مختلف انتظار دارند که پیکربندی تم متفاوتی داشته باشند. در هنگام استفاده از یک تم سفارشی، شیء پیکربندی تم به تم منتقل می‌شود تا تم بتواند بر اساس آن رفتار شرطی را تعریف کند.
## i18nRouting {#i18nrouting}
- نوع: `boolean`
تغییر زبان به `zh` باعث تغییر URL از `/foo` (یا `/en/foo/`) به `/zh/foo` می‌شود. شما می‌توانید این رفتار را با تنظیم `themeConfig.i18nRouting` به `false` غیرفعال کنید.
## logo {#logo}
- نوع: `ThemeableImage`
فایل لوگو برای نمایش در نوار ناوبری، به سمت راست قبل از عنوان سایت. یک رشته مسیر یا یک شیء برای تنظیم لوگو متفاوت برای حالت نوری/تاریک قبول می‌کند.
```ts
export default {
themeConfig: {
logo: '/logo.svg'
}
}
```
```ts
type ThemeableImage =
| string
| { src: string; alt?: string }
| { light: string; dark: string; alt?: string }
```
## siteTitle
- نوع: `string | false`
شما می‌توانید این مورد را سفارشی کنید تا عنوان سایت پیش‌فرض (`title` در پیکربندی برنامه) را در ناوبری جایگزین کنید. هنگامی که به `false` تنظیم می‌شود، عنوان در ناوبری غیرفعال می‌شود. این قابلیت مفید است زمانی که شما لوگو دارید که حاوی متن عنوان سایت است.
```ts
export default {
themeConfig: {
siteTitle: 'Hello World'
}
}
```
## nav
- نوع: `NavItem`
پیکربندی برای موارد منوی ناوبری. جزئیات بیشتر در [تم پیش‌فرض: ناوبری](./default-theme-nav#navigation-links).
```ts
export default {
themeConfig: {
nav: [
{ text: 'راهنما', link: '/guide' },
{
text: 'منوی کشویی',
items: [
{ text: 'مورد الف', link: '/item-1' },
{ text: 'مورد ب', link: '/item-2' },
{ text: 'مورد ج', link: '/item-3' }
]
}
]
}
}
```
```ts
type NavItem = NavItemWithLink | NavItemWithChildren
interface NavItemWithLink {
text: string
link: string
activeMatch?: string
target?: string
rel?: string
noIcon?: boolean
}
interface NavItemChildren {
text?: string
items: NavItemWithLink[]
}
interface NavItemWithChildren {
text?: string
items: (NavItemChildren | NavItemWithLink)[]
activeMatch?: string
}
```
## sidebar
- نوع: `Sidebar`
پیکربندی برای موارد منوی نوار کناری. جزئیات بیشتر در [تم پیش‌فرض: نوار کناری](./default-theme-sidebar).
```ts
export default {
themeConfig: {
sidebar: [
{
text: 'راهنما',
items: [
{ text: 'معرفی', link: '/introduction' },
{ text: 'شروع کار', link: '/getting-started' },
...
]
}
]
}
}
```
```ts
export type Sidebar = SidebarItem[] | SidebarMulti
export interface SidebarMulti {
[path: string]: SidebarItem[] | { items: SidebarItem[]; base: string }
}
export type SidebarItem = {
/**
* برچسب متنی مورد.
*/
text?: string
/**
* لینک مورد.
*/
link?: string
/**
* فرزندان مورد.
*/
items?: SidebarItem[]
/**
* اگر مشخص نشده باشد، گروه قابل جمع‌شدن نیست.
*
* اگر `true` باشد، گروه قابل جمع‌شدن است و به طور پیش‌فرض جمع شده است
*
* اگر `false` باشد، گروه قابل جمع‌شدن است اما به طور پیش‌فرض باز شده است
*/
collapsed?: boolean
/**
* مسیر پایه برای موارد فرزند.
*/
base?: string
/**
* سفارشی‌سازی متنی که در پا صفحه قبلی/بعدی نمایش داده می‌شود.
*/
docFooterText?: string
rel?: string
target?: string
}
```
## aside
- نوع: `boolean | 'left'`
- پیش‌فرض: `true`
- می‌تواند به صورت خودکار برای هر صفحه از طریق [frontmatter](./frontmatter-config#aside) بازنویسی شود.
تنظیم این مقدار به `false` از رندر کردن کانتینر اطراف خودداری می‌کند.\
تنظیم این مقدار به `true` کانتینر اطراف را به راست رندر می‌کند.\
تنظیم این مقدار به `left` کانتینر اطراف را به چپ رندر می‌کند.
اگر می‌خواهید آن را برای تمام نمایه‌گرها غیرفعال کنید، به جای آن باید از `outline: false` استفاده کنید.
## outline
- نوع: `Outline | Outline['level'] | false`
- می‌تواند به صورت خودکار برای هر صفحه از طریق [frontmatter](./frontmatter-config#outline) بازنویسی شود.
تنظیم این مقدار به `false` از
رندر کردن کانتینر آوند خودداری می‌کند. به این رابط مراجعه کنید تا جزئیات بیشتری را بدانید:
```ts
interface Outline {
/**
* سطوح سرفصل‌هایی که در آوند نمایش داده خواهند شد.
* یک عدد تک را به این معنا است که تنها سرفصل‌های آن سطح نمایش داده می‌شوند.
* اگر یک دوتایی گذر داده شود، عدد اول سطح حداقل و عدد دوم سطح حداکثر است.
* `'deep'` مانند `[2، 6]` است، که به معنای همه سرفصل‌ها از `<h2>` تا `<h6>` است.
*
* @default 2
*/
level?: number | [number، number] | 'deep'
/**
* عنوانی که باید در آوند نمایش داده شود.
*
* @default 'On this page'
*/
label?: string
}
```
## socialLinks
- نوع: `SocialLink[]`
می‌توانید این گزینه را تعریف کنید تا لینک‌های حساب اجتماعی خود را با آیکون‌ها در ناوبری نمایش دهید.
```ts
export default {
themeConfig: {
socialLinks: [
{ icon: 'github', link: 'https://github.com/vuejs/vitepress' },
{ icon: 'twitter', link: '...' },
// شما همچنین می‌توانید آیکون‌های سفارشی را با ارسال SVG به عنوان رشته اضافه کنید:
{
icon: {
svg: '<svg role="img" viewBox="0 0 24 24" xmlns="http://www.w3.org/2000/svg"><title>Dribbble</title><path d="M12...6.38z"/></svg>'
},
link: '...',
// شما همچنین می‌توانید برچسب سفارشی را برای دسترسی (اختیاری اما توصیه می‌شود) شامل کنید:
ariaLabel: 'لینک جذاب'
}
]
}
}
```
```ts
interface SocialLink {
icon: SocialLinkIcon
link: string
ariaLabel?: string
}
type SocialLinkIcon =
| 'discord'
| 'facebook'
| 'github'
| 'instagram'
| 'linkedin'
| 'mastodon'
| 'npm'
| 'slack'
| 'twitter'
| 'x'
| 'youtube'
| { svg: string }
```
## footer
- نوع: `Footer`
- می‌تواند به صورت خودکار برای هر صفحه از طریق [frontmatter](./frontmatter-config#footer) بازنویسی شود.
پیکربندی پا. شما می‌توانید پیام یا متن حق کپی را در پا اضافه کنید، با این حال، فقط زمانی نمایش داده می‌شود که صفحه شامل نوار کناری نباشد. این به دلایل طراحی است.
```ts
export default {
themeConfig: {
footer: {
message: 'منتشر شده تحت مجوز MIT.',
copyright: 'حق نشر © 2019-present Evan You'
}
}
}
```
```ts
export interface Footer {
message?: string
copyright?: string
}
```
## editLink
- نوع: `EditLink`
- می‌تواند به صورت خودکار برای هر صفحه از طریق [frontmatter](./frontmatter-config#editlink) بازنویسی شود.
پیوند ویرایش به شما امکان می‌دهد که یک لینک به ویرایش صفحه را در خدمات مدیریت گیت مانند GitHub یا GitLab نمایش دهید. برای جزئیات بیشتر به [تم پیش‌فرض: لینک ویرایش](./default-theme-edit-link) مراجعه کنید.
```ts
export default {
themeConfig: {
editLink: {
pattern: 'https://github.com/vuejs/vitepress/edit/main/docs/:path',
text: 'ویرایش این صفحه در GitHub'
}
}
}
```
```ts
export interface EditLink {
pattern: string
text?: string
}
```
## lastUpdated
- نوع: `LastUpdatedOptions`
امکانات سفارشی‌سازی برای متن به‌روز شده و فرمت تاریخ.
```ts
export default {
themeConfig: {
lastUpdated: {
text: 'به‌روزرسانی شده در',
formatOptions: {
dateStyle: 'full',
timeStyle: 'medium'
}
}
}
}
```
```ts
export interface LastUpdatedOptions {
/**
* @default 'آخرین به‌روزرسانی'
*/
text?: string
/**
* @default
* { dateStyle: 'short', timeStyle: 'short' }
*/
formatOptions?: Intl.DateTimeFormatOptions & { forceLocale?: boolean }
}
```
## algolia
- نوع: `AlgoliaSearch`
یک گزینه برای پشتیبانی از جستجو در سایت مستندات خود با استفاده از [Algolia DocSearch](https://docsearch.algolia.com/docs/what-is-docsearch). بیشتر در [تم پیش‌فرض: جستجو](./default-theme-search) بیاموزید.
```ts
export interface AlgoliaSearchOptions extends DocSearchProps {
locales?: Record<string, Partial<DocSearchProps>>
}
```
گزینه‌های کامل را [اینجا](https://github.com/vuejs/vitepress/blob/main/types/docsearch.d.ts) مشاهده کنید.
## carbonAds {#carbon-ads}
- نوع: `CarbonAdsOptions`
یک گزینه برای نمایش [Carbon Ads](https://www.carbonads.net/).
```ts
export default {
themeConfig: {
carbonAds: {
code: 'your-carbon-code',
placement: 'your-carbon-placement'
}
}
}
```
```ts
export interface CarbonAdsOptions {
code: string
placement: string
}
```
بیشتر در [تم پیش‌فرض: Carbon Ads](./default-theme-carbon-ads) بیاموزید.
## docFooter
- نوع: `DocFooter`
می‌تواند برای سفارشی‌سازی متنی که در بالای لینک‌های قبلی و بعدی نمایش داده می‌شود استفاده شود. مفید است اگر مستندات خود را به زبانی غیر از انگلیسی نوشته باشید. همچنین می‌تواند برای غیرفعال کردن لینک‌های قبلی/بعدی به صورت جهانی استفاده شود. اگر می‌خواهید لینک‌های قبلی/بعدی را به صورت انتخابی فعال
/غیرفعال کنید، می‌توانید از [frontmatter](./default-theme-prev-next-links) استفاده کنید.
```ts
export default {
themeConfig: {
docFooter: {
prev: 'صفحه قبلی',
next: 'صفحه بعدی'
}
}
}
```
```ts
export interface DocFooter {
prev?: string | false
next?: string | false
}
```
## darkModeSwitchLabel
- نوع: `string`
- پیش‌فرض: `ظاهر`
می‌تواند برای سفارشی‌سازی برچسب سوئیچ حالت تاریک استفاده شود. این برچسب تنها در نمای تلفن همراه نمایش داده می‌شود.
## lightModeSwitchTitle
- نوع: `string`
- پیش‌فرض: `تغییر به تم روشن`
می‌تواند برای سفارشی‌سازی عنوان سوئیچ حالت روشن که در بالا حاشیه دار می‌شود، استفاده شود.
## darkModeSwitchTitle
- نوع: `string`
- پیش‌فرض: `تغییر به تم تاریک`
می‌تواند برای سفارشی‌سازی عنوان سوئیچ حالت تاریک که در بالا حاشیه دار می‌شود، استفاده شود.
## sidebarMenuLabel
- نوع: `string`
- پیش‌فرض: `منو`
می‌تواند برای سفارشی‌سازی برچسب منوی نوار کناری استفاده شود. این برچسب تنها در نمای تلفن همراه نمایش داده می‌شود.
## returnToTopLabel
- نوع: `string`
- پیش‌فرض: `بازگشت به بالا`
می‌تواند برای سفارشی‌سازی برچسب دکمه بازگشت به بالا استفاده شود. این برچسب تنها در نمای تلفن همراه نمایش داده می‌شود.
## langMenuLabel
- نوع: `string`
- پیش‌فرض: `تغییر زبان`
می‌تواند برای سفارشی‌سازی برچسب aria- توگل زبان در ناوبری استفاده شود. این فقط در صورت استفاده از [i18n](../guide/i18n) استفاده می‌شود.
## externalLinkIcon
- نوع: `boolean`
- پیش‌فرض: `false`
آیا باید نمایش آیکون لینک خارجی کنار لینک‌های خارجی در مارک‌داون باشد.

@ -0,0 +1,60 @@
# پیوند ویرایش {#edit-link}
## پیکربندی سطح سایت {#site-level-config}
پیوند ویرایش به شما این امکان را می‌دهد که یک پیوند به صفحه ویرایش را در خدمات مدیریت گیت مانند GitHub یا GitLab نمایش دهید. برای فعال‌سازی آن، گزینه `themeConfig.editLink` را به پیکربندی خود اضافه کنید.
```js
export default {
themeConfig: {
editLink: {
pattern: 'https://github.com/vuejs/vitepress/edit/main/docs/:path'
}
}
}
```
گزینه `pattern` ساختار URL را برای پیوند تعیین می‌کند و `:path` با مسیر صفحه جایگزین خواهد شد.
همچنین می‌توانید یک تابع خالص ارائه دهید که `PageData` را به عنوان آرگومان دریافت کرده و رشته URL را برمی‌گرداند.
```js
export default {
themeConfig: {
editLink: {
pattern: ({ filePath }) => {
if (filePath.startsWith('packages/')) {
return `https://github.com/acme/monorepo/edit/main/${filePath}`
} else {
return `https://github.com/acme/monorepo/edit/main/docs/${filePath}`
}
}
}
}
}
```
این تابع نباید اثر جانبی داشته باشد و هیچ چیز خارج از دامنه خود را دسترسی ندهد، زیرا که در مرورگر سریالیزه و اجرا خواهد شد.
به طور پیش‌فرض، این عبارت "ویرایش این صفحه" را در پایین صفحه مستندات اضافه می‌کند. می‌توانید این متن را با تعریف گزینه `text` سفارشی‌سازی کنید.
```js
export default {
themeConfig: {
editLink: {
pattern: 'https://github.com/vuejs/vitepress/edit/main/docs/:path',
text: 'ویرایش این صفحه در GitHub'
}
}
}
```
## پیکربندی Frontmatter {#frontmatter-config}
می‌توانید این امکان را برای هر صفحه با استفاده از گزینه `editLink` در frontmatter غیرفعال کنید:
```yaml
---
editLink: false
---
```

@ -0,0 +1,53 @@
# پاورقی {#footer}
وقتی `themeConfig.footer` حاضر باشد، ویت‌پرس پاورقی جهانی را در پایین صفحه نمایش می‌دهد.
```ts
export default {
themeConfig: {
footer: {
message: 'Released under the MIT License.',
copyright: 'Copyright © 2019-present Evan You'
}
}
}
```
```ts
export interface Footer {
// پیام نمایش داده شده درست قبل از حق نسخه.
message?: string
// متن حق نسخه واقعی.
copyright?: string
}
```
پیکربندی بالا همچنین از رشته‌های HTML پشتیبانی می‌کند. بنابراین، به عنوان مثال، اگر می‌خواهید متن پاورقی دارای برخی از لینک‌ها باشد، می‌توانید پیکربندی را به شکل زیر تنظیم کنید:
```ts
export default {
themeConfig: {
footer: {
message: 'Released under the <a href="https://github.com/vuejs/vitepress/blob/main/LICENSE">MIT License</a>.',
copyright: 'Copyright © 2019-present <a href="https://github.com/yyx990803">Evan You</a>'
}
}
}
```
::: warning هشدار
تنها عناصر مستقیم می‌توانند در `message` و `copyright` استفاده شوند زیرا در داخل یک عنصر `<p>` رندر می‌شوند. اگر می‌خواهید عناصر بلوکی را اضافه کنید، در نظر داشته باشید که به جای این، از [اسلات `layout-bottom`](../guide/extending-default-theme#layout-slots) استفاده کنید.
:::
توجه داشته باشید که پاورقی نمایش داده نمی‌شود زمانی که [نوار کناری](./default-theme-sidebar) قابل مشاهده باشد.
## پیکربندی Frontmatter {#frontmatter-config}
این می‌تواند برای هر صفحه با استفاده از گزینه `footer` در frontmatter غیرفعال شود:
```yaml
---
footer: false
---
```

@ -0,0 +1,193 @@
# صفحه اصلی {#home-page}
قالب پیش‌فرض ویت‌پرس یک طرح صفحه اصلی فراهم می‌کند که می‌توانید آن را همچنین در [صفحه اصلی این سایت](../) مشاهده کنید. شما می‌توانید آن را در هر یک از صفحات خود با تعیین `layout: home` در [frontmatter](./frontmatter-config) استفاده کنید.
```yaml
---
layout: home
---
```
اما این گزینه به تنهایی خیلی کاربردی نخواهد بود. شما می‌توانید با اضافه کردن بخش‌های "قالب‌های پیش‌فرض" مختلف، چندین بخش متفاوت را به صفحه اصلی اضافه کنید مانند `hero` و `features`.
## بخش Hero {#hero-section}
بخش Hero در بالای صفحه اصلی قرار دارد. در ادامه می‌توانید نحوه پیکربندی بخش Hero را ببینید.
```yaml
---
layout: home
hero:
name: ویت‌پرس
text: Vite & Vue powered static site generator.
tagline: Lorem ipsum...
image:
src: /logo.png
alt: ویت‌پرس
actions:
- theme: brand
text: Get Started
link: /guide/what-is-vitepress
- theme: alt
text: View on GitHub
link: https://github.com/vuejs/vitepress
---
```
```ts
interface Hero {
// رشته نمایش داده شده در بالای `text`. همراه با رنگ برند و انتظار می‌رود که کوتاه باشد، مانند نام محصول.
name?: string
// متن اصلی بخش Hero. این به عنوان تگ `h1` تعریف می‌شود.
text: string
// تگ‌لاین نمایش داده شده زیر `text`.
tagline?: string
// تصویر که در کنار ناحیه متن و تگ‌لاین نمایش داده می‌شود.
image?: ThemeableImage
// دکمه‌های اقدام برای نمایش در بخش Hero صفحه اصلی.
actions?: HeroAction[]
}
type ThemeableImage =
| string
| { src: string; alt?: string }
| { light: string; dark: string; alt?: string }
interface HeroAction {
// رنگ تم دکمه. به طور پیش‌فرض `brand` است.
theme?: 'brand' | 'alt'
// برچسب دکمه.
text: string
// مقصد لینک دکمه.
link: string
// ویژگی هدف لینک.
target?: string
// ویژگی rel لینک.
rel?: string
}
```
### سفارشی‌سازی رنگ نام {#customizing-the-name-color}
ویت‌پرس از رنگ برند (`--vp-c-brand-1`) برای `name` استفاده می‌کند. با این حال، شما می‌توانید این رنگ را با جایگذاری متغیر `--vp-home-hero-name-color` سفارشی کنید.
```css
:root {
--vp-home-hero-name-color: blue;
}
```
همچنین می‌توانید با ترکیب `--vp-home-hero-name-background`، رنگ گرادیانت `name` را تعیین کنید.
```css
:root {
--vp-home-hero-name-color: transparent;
--vp-home-hero-name-background: -webkit-linear-gradient(120deg, #bd34fe, #41d1ff);
}
```
## {#features-section} بخش ویژگی‌ها
در بخش ویژگی‌ها، می‌توانید هر تعدادی ویژگی که مایلید پس از بخش Hero نمایش دهید، لیست کنید. برای پیکربندی آن، گزینه `features` را به frontmatter ارسال کنید.
می‌توانید برای هر ویژگی آیکونی ارائه دهید که می‌تواند یک ایموجی یا هر نوع تصویر دیگری باشد. زمانی که آیکون پیکربندی شده یک تصویر است (svg، png، jpeg...). باید آیکون را با عرض و ارتفاع مناسب ارائه دهید. شما همچنین می‌توانید توضیحات، اندازه داخلی آن و نسخه‌های آن برای تم تاریک و روشن را ارائه دهید هنگام لزوم.
```yaml
---
layout: home
features:
- icon: 🛠️
title: ساده و کم حجم، همیشه
details: Lorem ipsum...
- icon:
src: /cool-feature-icon.svg
title: ویژگی جالب دیگر
details: Lorem ipsum...
- icon:
dark: /dark-feature-icon.svg
light: /light-feature-icon.svg
title: ویژگی جالب دیگر
details: Lorem ipsum...
---
```
```ts
interface Feature {
// نمایش آیکون در هر جعبه ویژگی.
icon?: FeatureIcon
// عنوان ویژگی.
title: string
// جزئیات ویژگی.
details: string
// لینک زمانی که بر روی جزئیات کلیک می‌کنید. لینک می‌تواند داخلی یا خارجی باشد.
//
// به عنوان مثال: `guide/reference/default-theme-home-page` یا `https://example.com`
link?: string
// متن لینکی که داخل جزئیات کامپوننت نمایش داده می‌شود. بهتر است با گزینه `link` استفاده شود.
//
// به عنوان مثال: `بیشتر بدانید`، `صفحه بازدید` و غیره.
linkText?: string
// ویژگی rel لینک برای گزینه `link`.
//
// به عنوان مثال: `external`
rel?: string
// ویژگی target لینک برای گزینه `link`.
target?: string
}
type FeatureIcon =
| string
| { src: string; alt?: string; width?: string; height: string }
| {
light: string
dark: string
alt?: string
width?: string
height: string
}
```
## محتوای Markdown {#markdown-content}
می‌توانید محتوای اضافی را به صفحه اصلی سایت خود اضافه کنید فقط با افزودن Markdown زیر تقسیم‌کننده `---` در پایین frontmatter.
````md
---
layout: home
hero:
name
: ویت‌پرس
text: Vite & Vue powered static site generator.
---
## شروع کردن
می‌توانید بلافاصله با استفاده از `npx` از ویت‌پرس شروع کنید!
```sh
npm init
npx vitepress init
```
````
::: info اطلاعات
ویت‌پرس همیشه استایل اضافی محتوای صفحه `layout: home` را خودکار نمی‌کند. برای بازگشت به رفتار قدیمی، می‌توانید `markdownStyles: false` را به frontmatter اضافه کنید.
:::

@ -0,0 +1,27 @@
# آخرین بروزرسانی {#last-updated}
زمان به روزرسانی آخرین محتوا در گوشه پایین سمت راست صفحه نمایش داده خواهد شد. برای فعال‌سازی آن، گزینه `lastUpdated` را به پیکربندی خود اضافه کنید.
::: tip نکته
برای دیدن زمان به‌روزرسانی، باید فایل Markdown را commit کنید.
:::
## پیکربندی سطح سایت {#site-level-config}
```js
export default {
lastUpdated: true
}
```
## پیکربندی Frontmatter {#frontmatter-config}
می‌توانید این امکان را برای هر صفحه با استفاده از گزینه `lastUpdated` در frontmatter غیرفعال کنید:
```yaml
---
lastUpdated: false
---
```
همچنین به [پیکربندی پیش‌فرض: آخرین بروزرسانی](./default-theme-config#lastupdated) مراجعه کنید تا اطلاعات بیشتری دریافت کنید. هر مقدار حقیقی در سطح تم از ویژگی را فعال خواهد کرد مگر آنکه به صورت صریح در سطح سایت یا صفحه غیرفعال شود.

@ -0,0 +1,62 @@
# طرح بندی {#layout}
می‌توانید طرح صفحه را با تنظیم گزینه `layout` در [frontmatter](./frontmatter-config) صفحه انتخاب کنید. سه گزینه طرح وجود دارد، `doc`، `page` و `home`. اگر هیچ چیز مشخص نشده باشد، صفحه به عنوان صفحه `doc` در نظر گرفته می‌شود.
```yaml
---
layout: doc
---
```
## طرح Doc {#doc-layout}
گزینه `doc` طرح پیش‌فرض است و تمام محتوای Markdown را به "نمایشگاه" درست می‌کند. این با پوشاندن کل محتوا در داخل کلاس css `vp-doc` کار می‌کند و استایل‌های لازم را بر روی عناصر زیرش اعمال می‌کند.
تقریباً همه عناصر عمومی مانند `p` یا `h2` استایل‌های خاصی دارند. بنابراین، به یاد داشته باشید که اگر HTML سفارشی‌ای درون محتوای Markdown اضافه کنید، این استایل‌ها روی آن‌ها هم اعمال خواهند شد.
این طرح ویژگی‌های خاص مستندسازی زیر را فراهم می‌کند. این ویژگی‌ها فقط در این طرح فعال هستند.
- پیوند ویرایش
- پیوند قبلی و بعدی
- ساختار
- [تبلیغات Carbon](./default-theme-carbon-ads)
## طرح Page {#page-layout}
گزینه `page` به عنوان "صفحه خالی" در نظر گرفته می‌شود. Markdown همچنان تجزیه و تحلیل می‌شود و تمامی [توسعه‌های Markdown](../guide/markdown) به عنوان طرح `doc` کار می‌کنند، اما هیچ استایل پیش‌فرضی به آن اعمال نمی‌شود.
طرح صفحه به شما این امکان را می‌دهد که همه چیز را به دلخواه خود شخصی‌سازی کنید بدون این که طرح ویت‌پرس بر روی مارک‌آپ تاثیر بگذارد. این کار بسیار مفید است زمانی که می‌خواهید صفحه سفارشی خود را ایجاد کنید.
توجه داشته باشید که حتی در این طرح، نوار کناری نیز نمایش داده می‌شود اگر صفحه دارای پیکربندی نوار کناری مطابق باشد.
## طرح Home {#home-layout}
گزینه `home` صفحه "خانه" قالب‌بندی می‌کند. در این طرح، می‌توانید گزینه‌های اضافی مانند `hero` و `features` را برای دلخواه‌سازی محتوا تنظیم کنید. لطفاً [صفحه پیش‌فرض: صفحه خانه](./default-theme-home-page) را برای اطلاعات بیشتر مشاهده کنید.
## بدون طرح {#no-layout}
اگر نمی‌خواهید هیچ طرحی داشته باشید، می‌توانید با گذراندن `layout: false` از frontmatter، از این گزینه استفاده کنید. این گزینه مفید است اگر صفحهٔ نخستی کاملاً قابل تنظیم (بدون هیچ نوار کناری، نوار ناوبری یا پاورقی به صورت پیش‌فرض) را می‌خواهید.
## طرح سفارشی {#custom-layout}
همچنین می‌توانید از یک طرح سفارشی استفاده کنید:
```md
---
layout: foo
---
```
این دستور به دنبال یک کامپوننت به نام `foo` ثبت شده در محیط است. به عنوان مثال، می‌توانید کامپوننت خود را به صورت گلوبال در `.vitepress/theme/index.ts` ثبت کنید:
```ts
import DefaultTheme from 'vitepress/theme'
import Foo from './Foo.vue'
export default {
extends: DefaultTheme,
enhanceApp({ app }) {
app.component('foo', Foo)
}
}
```

@ -0,0 +1,217 @@
# ناوبری {#nav}
ناوبری نوار ناوبری است که در بالای صفحه نمایش داده می‌شود و شامل عنوان سایت، لینک‌های منوی جهانی، و غیره می‌باشد.
## عنوان سایت و لوگو {#site-title-and-logo}
به طور پیش‌فرض، ناو نام سایت را با ارجاع به مقدار [`config.title`](./site-config#title) نمایش می‌دهد. اگر می‌خواهید تغییر دهید که چه چیزی در ناو نمایش داده شود، می‌توانید متن سفارشی را در گزینه `themeConfig.siteTitle` تعریف کنید.
```js
export default {
themeConfig: {
siteTitle: 'عنوان سفارشی من'
}
}
```
اگر برای سایت خود لوگو دارید، می‌توانید آن را با ارسال مسیر تصویر نمایش دهید. شما باید لوگو را در دایرکتوری `public` قرار داده و مسیر مطلق آن را تعریف کنید.
```js
export default {
themeConfig: {
logo: '/my-logo.svg'
}
}
```
هنگام افزودن یک لوگو، آن به همراه عنوان سایت نمایش داده می‌شود. اگر لوگوی شما همه چیزی است که نیاز دارید و اگر می‌خواهید متن عنوان سایت را پنهان کنید، گزینه `siteTitle` را برابر با `false` قرار دهید.
```js
export default {
themeConfig: {
logo: '/my-logo.svg',
siteTitle: false
}
}
```
همچنین می‌توانید به عنوان لوگو یک شیء را نیز ارسال کنید اگر می‌خواهید ویژگی `alt` را اضافه کنید یا آن را بر اساس حالت تاریک / روشن سفارشی‌سازی کنید. برای جزئیات بیشتر به [`themeConfig.logo`](./default-theme-config#logo) مراجعه کنید.
## لینک‌های ناوبری {#navigation-links}
شما می‌توانید گزینه `themeConfig.nav` را تعریف کنید تا لینک‌ها را به ناوبری خود اضافه کنید.
```js
export default {
themeConfig: {
nav: [
{ text: 'راهنما', link: '/guide' },
{ text: 'پیکربندی', link: '/config' },
{ text: 'تغییرات', link: 'https://github.com/...' }
]
}
}
```
`text` متن واقعی است که در ناوبری نمایش داده می‌شود و `link` لینکی است که هنگام کلیک بر روی متن به آن ناوبری می‌شود. برای لینک، مسیر را به صورت واقعی بدون پیشوند `.md` تنظیم کنید و همیشه با `/` شروع کنید.
لینک‌های ناوبری همچنین می‌توانند منوهای کشویی باشند. برای این کار، کلید `items` را در گزینه لینک تنظیم کنید.
```js
export default {
themeConfig: {
nav: [
{ text: 'راهنما', link: '/guide' },
{
text: 'منوی کشویی',
items: [
{ text: 'مورد الف', link: '/item-1' },
{ text: 'مورد ب', link: '/item-2' },
{ text: 'مورد ج', link: '/item-3' }
]
}
]
}
}
```
لطفا توجه داشته باشید که عنوان منوی کشویی (`منوی کشویی` در مثال بالا) نمی‌تواند خاصیت `link` داشته باشد زیرا این دکمه برای باز کردن صفحه گفتگوی کشویی می‌شود.
همچنین می‌توانید بخش‌هایی را نیز به موارد منوی کشویی با ارسال موارد بیشتر تو در تو اضافه کنید.
```js
export default {
themeConfig: {
nav: [
{ text: 'راهنما', link: '/guide' },
{
text: 'منوی کشویی',
items: [
{
// عنوان بخش
text: 'عنوان بخش A',
items: [
{ text: 'آیتم A بخش A', link: '...' },
{ text: 'آیتم B بخش B', link: '...' }
]
}
]
},
{
text: 'منوی کشویی',
items: [
{
// شما همچنین می‌توانید عنوان را حذف کنید.
items: [
{ text: 'آیتم A بخش A', link: '...' },
{ text: 'آیتم B بخش B', link: '...' }
]
}
]
}
]
}
}
```
### سفارشی‌سازی وضعیت "فعال" لینک {#customize-link-s-active-state}
موارد منوی ناوبری زمانی که صفحه فعلی زیر مسیر مطابقت دارد، مشخص می‌شوند. اگر می‌خواهید مسیر مطابقت را سفارشی کنید، ویژگی `activeMatch` و regex را به عنوان مقدار رشته تعریف کنید.
```js
export default {
themeConfig: {
nav: [
// این لینک وضعیت فعال را در زمانی که کاربر در مسیر `/config/` است، دریافت می‌کند.
{
text: 'راهنما',
link: '/guide',
activeMatch: '/config/'
}
]
}
}
```
::: warning هشدار
`activeMatch` انتظار می‌رود که به عنوان یک رشته regex باشد، اما شما باید آن را به عنوان یک رشته تعریف کنید. ما نمی‌توانیم از شیء RegExp واقعی اینجا استفاده کنیم زیرا در زمان ساخت غیر قابل سریالیز کردن است.
:::
### سفارشی‌سازی ویژگی‌های "target" و "rel" لینک {#customize-link-s-target-and-rel-attributes}
به طور پیش‌فرض، ویت‌پرس به طور خودکار ویژگی‌های
`target` و `rel` را بر اساس اینکه لینک یک لینک خارجی است یا خیر، تعیین می‌کند. اما اگر می‌خواهید، شما همچنین می‌توانید آن‌ها را سفارشی کنید.
```js
export default {
themeConfig: {
nav: [
{
text: 'کالای معاملاتی',
link: 'https://www.thegithubshop.com/',
target: '_self',
rel: 'sponsored'
}
]
}
}
```
## لینک‌های اجتماعی {#social-links}
به [`socialLinks`](./default-theme-config#sociallinks) مراجعه کنید.
## اجزای سفارشی
می‌توانید اجزای سفارشی را در نوار ناوبری با استفاده از گزینه `component` اضافه کنید. کلید `component` باید نام مؤلفه Vue باشد و باید به صورت جهانی با استفاده از [Theme.enhanceApp](../guide/custom-theme#theme-interface) ثبت شود.
```js
// .vitepress/config.js
export default {
themeConfig: {
nav: [
{
text: 'منوی من',
items: [
{
component: 'MyCustomComponent',
// پارامترهای اختیاری برای ارسال به مؤلفه
props: {
title: 'مؤلفه سفارشی من'
}
}
]
},
{
component: 'AnotherCustomComponent'
}
]
}
}
```
سپس، شما باید مؤلفه را به صورت جهانی ثبت کنید:
```js
// .vitepress/theme/index.js
import DefaultTheme from 'vitepress/theme'
import MyCustomComponent from './components/MyCustomComponent.vue'
import AnotherCustomComponent from './components/AnotherCustomComponent.vue'
/** @type {import('vitepress').Theme} */
export default {
extends: DefaultTheme,
enhanceApp({ app }) {
app.component('MyCustomComponent', MyCustomComponent)
app.component('AnotherCustomComponent', AnotherCustomComponent)
}
}
```
اجزای شما در نوار ناوبری نمایش داده خواهد شد. ویت‌پرس ویژگی‌های اضافی زیر را به مؤلفه ارائه می‌دهد:
- `screenMenu`: یک بولین اختیاری که نشان می‌دهد آیا مؤلفه در منوی ناوبری تلفن همراه است یا خیر
می‌توانید یک نمونه را در آزمایش‌های e2e [اینجا](https://github.com/vuejs/vitepress/tree/main/__tests__/e2e/.vitepress) بررسی کنید.

@ -0,0 +1,43 @@
# پیوندهای قبلی و بعدی {#prev-next-links}
شما می‌توانید متن و پیوند برای صفحات قبلی و بعدی را سفارشی‌سازی کنید (نمایش داده شده در پایین صفحه مستندات). این مفید است اگر می‌خواهید متن دیگری را در این قسمت نمایش دهید که با آنچه در نوار کناری دارید، متفاوت باشد. همچنین، ممکن است مفید باشد که فوتر را غیرفعال کنید یا به یک صفحه لینک کنید که در نوار کناری شما وجود ندارد.
## prev
- نوع: `string | false | { text?: string; link?: string }`
- جزئیات:
مشخص می‌کند متن/لینکی که برای لینک به صفحه قبلی نمایش داده خواهد شد. اگر این را در frontmatter تنظیم نکنید، متن/لینک از تنظیمات نوار کناری استخراج خواهد شد.
- مثال‌ها:
- برای فقط سفارشی‌سازی متن:
```yaml
---
prev: 'شروع کنید | مارک‌داون'
---
```
- برای سفارشی‌سازی هم متن و هم لینک:
```yaml
---
prev:
text: 'مارک‌داون'
link: '/guide/markdown'
---
```
- برای مخفی کردن صفحه قبلی:
```yaml
---
prev: false
---
```
## next
مشابه `prev` اما برای صفحه بعدی.

@ -0,0 +1,386 @@
---
outline: deep
---
# جستجو {#search}
## جستجوی محلی {#local-search}
ویت‌پرس از جستجوی متن کامل نامتقارن با استفاده از یک فهرست در مرورگر با تشکر از [minisearch](https://github.com/lucaong/minisearch/) پشتیبانی می‌کند. برای فعال‌سازی این ویژگی، کافی است گزینه `themeConfig.search.provider` را به `'local'` در فایل `.vitepress/config.ts` خود تنظیم کنید:
```ts
import { defineConfig } from 'vitepress'
export default defineConfig({
themeConfig: {
search: {
provider: 'local'
}
}
})
```
نمونه نتیجه:
![تصویر نمایشی از مودال جستجو](/search.png)
همچنین، می‌توانید از [Algolia DocSearch](#algolia-search) یا برخی افزونه‌های جامعه‌ای مانند <https://www.npmjs.com/package/vitepress-plugin-search> یا <https://www.npmjs.com/package/vitepress-plugin-pagefind> استفاده کنید.
### بین‌المللی‌سازی {#local-search-i18n}
می‌توانید با استفاده از تنظیماتی مانند این برای جستجوی چندزبانه استفاده کنید:
```ts
import { defineConfig } from 'vitepress'
export default defineConfig({
themeConfig: {
search: {
provider: 'local',
options: {
locales: {
zh: { // اگر می‌خواهید زبان پیش‌فرض را ترجمه کنید، این را به `root` تغییر دهید
translations: {
button: {
buttonText: 'جستجو',
buttonAriaLabel: 'جستجو'
},
modal: {
displayDetails: 'نمایش جزئیات',
resetButtonTitle: 'بازنشانی جستجو',
backButtonTitle: 'بستن جستجو',
noResultsText: 'نتیجه‌ای یافت نشد',
footer: {
selectText: 'انتخاب',
selectKeyAriaLabel: 'ورود',
navigateText: 'پیمایش',
navigateUpKeyAriaLabel: 'کلید بالا',
navigateDownKeyAriaLabel: 'کلید پایین',
closeText: 'بستن',
closeKeyAriaLabel: 'esc'
}
}
}
}
}
}
}
}
})
```
### گزینه‌های miniSearch {#minisearch-options}
می‌توانید MiniSearch را به این صورت پیکربندی کنید:
```ts
import { defineConfig } from 'vitepress'
export default defineConfig({
themeConfig: {
search: {
provider: 'local',
options: {
miniSearch: {
/**
* @type {Pick<import('minisearch').Options, 'extractField' | 'tokenize' | 'processTerm'>}
*/
options: {
/* ... */
},
/**
* @type {import('minisearch').SearchOptions}
* @default
* { fuzzy: 0.2, prefix: true, boost: { title: 4, text: 2, titles: 1 } }
*/
searchOptions: {
/* ... */
}
}
}
}
}
})
```
برای کسب اطلاعات بیشتر به [اسناد MiniSearch](https://lucaong.github.io/minisearch/classes/MiniSearch.MiniSearch.html) مراجعه کنید.
### سفارشی‌سازی رندر محتوا {#custom-content-renderer}
می‌توانید تابع استفاده شده برای رندر محتوای Markdown قبل از فهرست‌بندی آن را سفارشی‌سازی کنید:
```ts
import { defineConfig } from 'vitepress'
export default defineConfig({
themeConfig: {
search: {
provider: 'local',
options: {
/**
* @param {string} src
* @param {import('vitepress').MarkdownEnv} env
* @param {import('markdown-it')} md
*/
_render(src, env, md) {
// بازگشت رشته HTML
}
}
}
}
})
```
این تابع از داده‌های سایت سمت کلاینت پاک خواهد شد، بنابراین شما می‌توانید از APIهای Node.js در آن استفاده کنید.
#### مثال: استثنای صفحات از جستجو {#example-excluding-pages-from-search}
می‌توانید با اضافه کردن `search: false` به frontmatter صفحه، صفحات را از جستجو استثنا دهید. به طور جایگزین:
```ts
import { defineConfig } from 'vitepress'
export default defineConfig({
themeConfig: {
search: {
provider: 'local',
options: {
_render(src, env, md) {
const html = md.render(src, env)
if (env.frontmatter?.search === false) return ''
if (env.relativePath.startsWith('some/path')) return ''
return html
}
}
}
}
})
```
::: warning توجه
در صورت ارائه تابع `_render` سفارشی، باید خودتان بررسی کنید که آیا frontmatter `search: false` را مدیریت می‌کند یا خیر. همچنین، شی env قبل از فراخوانی `md.render` کاملاً پر نمی‌شود، بنابراین هر بررسی‌ای روی ویژگی‌های اختیاری env مانند `frontmatter` باید بعد از آن انجام شود.
:::
#### مثال: تبدیل محتوا - افزودن لینک‌های صفحه {#example-transforming-content-adding-anchors}
```ts
import { defineConfig } from 'vitepress'
export default defineConfig({
themeConfig: {
search: {
provider: 'local',
options: {
_render(src, env, md) {
const html = md.render(src, env)
if (env.frontmatter?.title)
return md.render(`# ${env.frontmatter.title}`) + html
return html
}
}
}
}
})
```
## جستجوی Algolia {#algolia-search}
ویت‌پرس از جستجو در سایت مستندات شما با استفاده از [Algolia DocSearch](https://docsearch.algolia.com/docs/what-is-docsearch) پشتیبانی می‌کند. به راهنمای شروع کار آن‌ها مراجعه کنید. در فایل `.vitepress/config.ts` شما نیاز دارید که حداقل موارد زیر را فراهم کنید تا کار کند:
```ts
import { defineConfig } from 'vitepress'
export default defineConfig({
themeConfig: {
search: {
provider: 'algolia',
options: {
appId: '...',
apiKey: '...',
indexName: '...'
}
}
}
})
```
### بین‌المللی‌سازی {#algolia-search-i18n}
می‌توانید با استفاده از تنظیماتی مانند این برای جستجوی چندزبانه استفاده کنید:
```ts
import { defineConfig } from 'vitepress'
export default defineConfig({
themeConfig:
{
search: {
provider: 'algolia',
options: {
appId: '...',
apiKey: '...',
indexName: '...',
locales: {
zh: {
placeholder: 'جستجو در مستندات',
translations: {
button: {
buttonText: 'جستجو در مستندات',
buttonAriaLabel: 'جستجو در مستندات'
},
modal: {
searchBox: {
resetButtonTitle: 'پاک کردن شرایط جستجو',
resetButtonAriaLabel: 'پاک کردن شرایط جستجو',
cancelButtonText: 'لغو',
cancelButtonAriaLabel: 'لغو'
},
startScreen: {
recentSearchesTitle: 'تاریخچه جستجو',
noRecentSearchesText: 'هیچ تاریخچه جستجویی وجود ندارد',
saveRecentSearchButtonTitle: 'ذخیره در تاریخچه جستجو',
removeRecentSearchButtonTitle: 'حذف از تاریخچه جستجو'
},
errorScreen: {
titleText: 'نمایش نتایج امکان‌پذیر نیست',
helpText: 'شما ممکن است نیاز به بررسی اتصال اینترنت خود داشته باشید'
},
footer: {
selectText: 'انتخاب',
navigateText: 'جابجایی',
closeText: 'بستن',
searchByText: 'جستجو توسط'
},
noResultsScreen: {
noResultsText: 'نتیجه‌ای پیدا نشد',
suggestedQueryText: 'می‌توانید امتحان کنید',
reportMissingResultsText: 'فکر می‌کنید باید نتایجی وجود داشته باشد؟',
reportMissingResultsLinkText: 'برای بازخورد کلیک کنید'
}
}
}
}
}
}
}
}
})
```
این [گزینه‌ها](https://github.com/vuejs/vitepress/blob/main/types/docsearch.d.ts) می‌توانند بازنویسی شوند. برای یادگیری بیشتر درباره آن‌ها به اسناد رسمی Algolia مراجعه کنید.
### پیکربندی Crawler {#crawler-config}
در اینجا یک پیکربندی نمونه بر اساس آنچه که این سایت استفاده می‌کند آمده است:
```ts
new Crawler({
appId: '...',
apiKey: '...',
rateLimit: 8,
startUrls: ['https://vitepress.dev/'],
renderJavaScript: false,
sitemaps: [],
exclusionPatterns: [],
ignoreCanonicalTo: false,
discoveryPatterns: ['https://vitepress.dev/**'],
schedule: 'at 05:10 on Saturday',
actions: [
{
indexName: 'vitepress',
pathsToMatch: ['https://vitepress.dev/**'],
recordExtractor: ({ $, helpers }) => {
return helpers.docsearch({
recordProps: {
lvl1: '.content h1',
content: '.content p, .content li',
lvl0: {
selectors: '',
defaultValue: 'Documentation'
},
lvl2: '.content h2',
lvl3: '.content h3',
lvl4: '.content h4',
lvl5: '.content h5'
},
indexHeadings: true
})
}
}
],
initialIndexSettings: {
vitepress: {
attributesForFaceting: ['type', 'lang'],
attributesToRetrieve: ['hierarchy', 'content', 'anchor', 'url'],
attributesToHighlight: ['hierarchy', 'hierarchy_camel', 'content'],
attributesToSnippet: ['content:10'],
camelCaseAttributes: ['hierarchy', 'hierarchy_radio', 'content'],
searchableAttributes: [
'unordered(hierarchy_radio_camel.lvl0)',
'unordered(hierarchy_radio.lvl0)',
'unordered(hierarchy_radio_camel.lvl1)',
'unordered(hierarchy_radio.lvl1)',
'unordered(hierarchy_radio_camel.lvl2)',
'unordered(hierarchy_radio.lvl2)',
'unordered(hierarchy_radio_camel.lvl3)',
'unordered(hierarchy_radio.lvl3)',
'unordered(hierarchy_radio_camel.lvl4)',
'unordered(hierarchy_radio.lvl4)',
'unordered(hierarchy_radio_camel.lvl5)',
'unordered(hierarchy_radio.lvl5)',
'unordered(hierarchy_radio_camel.lvl6)',
'unordered(hierarchy_radio.lvl6)',
'unordered(hierarchy_camel.lvl0)',
'unordered(hierarchy.lvl0)',
'unordered(hierarchy_camel.lvl1)',
'unordered(hierarchy.lvl1)',
'unordered(hierarchy_camel.lvl2)',
'unordered(hierarchy.lvl2)',
'unordered(hierarchy_camel.lvl3)',
'unordered(hierarchy.lvl3)',
'unordered(hierarchy_camel.lvl4)',
'unordered(hierarchy.lvl4)',
'unordered(hierarchy_camel.lvl5)',
'unordered(hierarchy.lvl5)',
'unordered(hierarchy_camel.lvl6)',
'unordered(hierarchy.lvl6)',
'content'
],
distinct: true,
attributeForDistinct: 'url',
customRanking: [
'desc(weight.pageRank)',
'desc(weight.level)',
'asc(weight.position)'
],
ranking: [
'words',
'filters',
'typo',
'attribute',
'proximity',
'exact',
'custom'
],
highlightPreTag: '<span class="algolia-docsearch-suggestion--highlight">',
highlightPostTag: '</span>',
minWordSizefor1Typo: 3,
minWordSizefor2Typos: 7,
allowTyposOnNumericTokens: false,
minProximity: 1,
ignorePlurals: true,
advancedSyntax: true,
attributeCriteriaComputedByMinProximity: true,
removeWordsIfNoResults: 'allOptional'
}
}
})
```
<style>
img[src="/search.png"] {
width: 100%;
aspect-ratio: 1 / 1;
}
</style>

@ -0,0 +1,215 @@
# نوار کناری {#sidebar}
نوار کناری بلوک اصلی ناوبری برای مستندات شما است. شما می‌توانید منوی نوار کناری را در [`themeConfig.sidebar`](./default-theme-config#sidebar) پیکربندی کنید.
```js
export default {
themeConfig: {
sidebar: [
{
text: 'راهنما',
items: [
{ text: 'مقدمه', link: '/introduction' },
{ text: 'شروع کردن', link: '/getting-started' },
...
]
}
]
}
}
```
## مبانی {#the-basics}
ساده‌ترین فرم منوی نوار کناری ارسال یک آرایه تکی از لینک‌هاست. آیتم سطح اول "بخش" نوار کناری را تعریف می‌کند. باید شامل `text` باشد که عنوان بخش است و `items` که لینک‌های واقعی ناوبری هستند.
```js
export default {
themeConfig: {
sidebar: [
{
text: 'عنوان بخش A',
items: [
{ text: 'آیتم A', link: '/item-a' },
{ text: 'آیتم B', link: '/item-b' },
...
]
},
{
text: 'عنوان بخش B',
items: [
{ text: 'آیتم C', link: '/item-c' },
{ text: 'آیتم D', link: '/item-d' },
...
]
}
]
}
}
```
هر `link` باید مسیر به فایل واقعی را با `/` آغاز کند. اگر شما `/` را به انتهای لینک اضافه کنید، صفحه `index.md` دایرکتوری متناظر را نمایش می‌دهد.
```js
export default {
themeConfig: {
sidebar: [
{
text: 'راهنما',
items: [
// این صفحه `/guide/index.md` را نمایش می‌دهد.
{ text: 'مقدمه', link: '/guide/' }
]
}
]
}
}
```
شما می‌توانید آیتم‌های نوار کناری را تا عمق ۶ سطح تعویض کنید که از سطح ریشه شمارش می‌شود. توجه داشته باشید که عمق بیشتر از ۶ سطح از آیتم‌های تو در تو نادیده گرفته می‌شود و در نوار کناری نمایش داده نمی‌شود.
```js
export default {
themeConfig: {
sidebar: [
{
text: 'سطح ۱',
items: [
{
text: 'سطح ۲',
items: [
{
text: 'سطح ۳',
items: [
...
]
}
]
}
]
}
]
}
}
```
## نوارهای کناری چندگانه {#multiple-sidebars}
می‌توانید بسته به مسیر صفحه، نوار کناری مختلفی را نمایش دهید. به عنوان مثال، همانطور که در این سایت نشان داده شده است، ممکن است بخواهید برای مستندات خود بخش‌های جداگانه مانند صفحه "راهنما" و صفحه "پیکربندی" را ایجاد کنید.
برای این کار، ابتدا صفحات خود را در دایرکتوری‌های مختلف برای هر بخش مورد نظر خود سازماندهی کنید:
```
.
├─ guide/
│ ├─ index.md
│ ├─ one.md
│ └─ two.md
└─ config/
├─ index.md
├─ three.md
└─ four.md
```
سپس، پیکربندی خود را برای تعریف نوار کناری برای هر بخش تعیین کنید. در این موارد، شما باید به جای یک آرایه، یک شیء را ارسال کنید.
```js
export default {
themeConfig: {
sidebar: {
// این نوار کناری نمایش داده می‌شود زمانی که کاربر در دایرکتوری `guide` است.
'/guide/': [
{
text: 'راهنما',
items: [
{ text: 'فهرست', link: '/guide/' },
{ text: 'یک', link: '/guide/one' },
{ text: 'دو', link: '/guide/two' }
]
}
],
// این نوار کناری نمایش داده می‌شود زمانی که کاربر در دایرکتوری `config` است.
'/config/': [
{
text: 'پیکربندی',
items: [
{ text: 'فهرست', link: '/config/' },
{ text: 'سه', link: '/config/three' },
{ text: 'چهار', link: '/config/four' }
]
}
]
}
}
}
```
## گروه‌های نوار کناری قابل جمع و جور {#collapsible-sidebar-groups}
با اضافه کردن گزینه `collapsed` به گروه نوار کناری، دکمه جداگانه‌ای برای پنهان کردن/نمایش هر بخش نمایش داده می‌شود.
```js
export default {
themeConfig: {
sidebar: [
{
text: 'عنوان بخش A',
collapsed: false,
items: [...]
}
]
}
}
```
تمام بخش‌ها به طور پیش‌فرض "باز" هستند. اگر می‌خواهید آن‌ها را در بارگذاری اولیه صفحه "بسته" کنید، گزینه `collapsed` را به `true` تنظیم کنید.
```js
export default {
themeConfig: {
sidebar: [
{
text: 'عنوان بخش A',
collapsed: true,
items: [...]
}
]
}
}
```
## `useSidebar` <Badge type="info" text="composable" /> {#usesidebar}
داده‌های مربوط به نوار کناری را برمی‌گرداند. شیء برگردانده شده دارای نوع‌های زیر است:
```ts
export interface DocSidebar {
isOpen: Ref<boolean>
sidebar: ComputedRef<DefaultTheme.SidebarItem[]>
sidebarGroups: ComputedRef<DefaultTheme.SidebarItem[]>
hasSidebar: ComputedRef<boolean>
hasAside: ComputedRef<boolean>
leftAside: ComputedRef<boolean>
isSidebarEnabled: ComputedRef<boolean>
open: () => void
close: () => void
toggle: () => void
}
```
**مثال:**
```vue
<script setup>
import { useSidebar } from 'vitepress/theme'
const { hasSidebar } = useSidebar()
</script>
<template>
<div v-if="hasSidebar">فقط ن
مایش داده شود زمانی که نوار کناری وجود دارد</div>
</template>
```

@ -0,0 +1,255 @@
<script setup>
import { VPTeamMembers } from 'vitepress/theme'
const members = [
{
avatar: 'https://github.com/yyx990803.png',
name: 'Evan You',
title: 'Creator',
links: [
{ icon: 'github', link: 'https://github.com/yyx990803' },
{ icon: 'twitter', link: 'https://twitter.com/youyuxi' }
]
},
{
avatar: 'https://github.com/kiaking.png',
name: 'Kia King Ishii',
title: 'Developer',
links: [
{ icon: 'github', link: 'https://github.com/kiaking' },
{ icon: 'twitter', link: 'https://twitter.com/KiaKing85' }
]
}
]
</script>
# صفحه تیم {#team-page}
اگر می‌خواهید تیم خود را معرفی کنید، می‌توانید از کامپوننت‌های تیم برای ساخت صفحه تیم استفاده کنید. دو راه برای استفاده از این کامپوننت‌ها وجود دارد. یکی اینکه آنها را در صفحه مستندات قرار دهید و دیگری اینکه یک صفحه کامل تیم ایجاد کنید.
## نمایش اعضای تیم در یک صفحه {#show-team-members-in-a-page}
می‌توانید از کامپوننت `<VPTeamMembers>` که از `vitepress/theme` قابل دسترسی است، برای نمایش لیست اعضای تیم در هر صفحه‌ای استفاده کنید.
```html
<script setup>
import { VPTeamMembers } from 'vitepress/theme'
const members = [
{
avatar: 'https://www.github.com/yyx990803.png',
name: 'Evan You',
title: 'Creator',
links: [
{ icon: 'github', link: 'https://github.com/yyx990803' },
{ icon: 'twitter', link: 'https://twitter.com/youyuxi' }
]
},
...
]
</script>
# تیم ما
با سلام به تیم فوق‌العاده‌ی ما خوش آمدید.
<VPTeamMembers size="small" :members="members" />
```
بالا به صورت عنصری با شکل کارتی اعضای تیم را نمایش می‌دهد. باید به شکل زیر نمایش داده شود.
<VPTeamMembers size="small" :members="members" />
کامپوننت `<VPTeamMembers>` دارای دو اندازه مختلف، `small` و `medium` است. معمولاً اندازه `small` برای استفاده در صفحات مستندات مناسب‌تر است. همچنین می‌توانید ویژگی‌های بیشتری برای هر عضو اضافه کنید مانند "توضیحات" یا "دکمه حامی". جهت کسب اطلاعات بیشتر به [`<VPTeamMembers>`](#vpteammembers) مراجعه کنید.
قرار دادن اعضای تیم در صفحه مستندات برای تیم‌های کوچک مناسب است که ایجاد یک صفحه کامل تیم ممکن است بیش از حد باشد یا معرفی اعضا به عنوان مرجع در زمینه مستندات.
اگر تعداد اعضا بسیار زیاد است یا به سادگی می‌خواهید بیشتر فضا برای نمایش اعضای تیم داشته باشید، در نظر بگیرید [ایجاد یک صفحه کامل تیم](#create-a-full-team-page).
## ایجاد یک صفحه کامل تیم {#create-a-full-team-page}
بجای اضافه کردن اعضای تیم به صفحه مستندات، می‌توانید یک صفحه کامل تیم را ایجاد کنید، مشابه اینکه چگونه می‌توانید یک [صفحه خانگی سفارشی](./default-theme-home-page) ایجاد کنید.
برای ایجاد یک صفحه تیم، ابتدا یک فایل md جدید بسازید. نام فایل مهم نیست، اما در اینجا آن را `team.md` می‌نامیم. در این فایل، گزینه `layout: page` را در فرانت‌ماتر تنظیم کنید، سپس می‌توانید ساختار صفحه خود را با استفاده از کامپوننت‌های `TeamPage` ایجاد کنید.
```html
---
layout: page
---
<script setup>
import {
VPTeamPage,
VPTeamPageTitle,
VPTeamMembers
} from 'vitepress/theme'
const members = [
{
avatar: 'https://www.github.com/yyx990803.png',
name: 'Evan You',
title: 'Creator',
links: [
{ icon: 'github', link: 'https://github.com/yyx990803' },
{ icon: 'twitter', link: 'https://twitter.com/youyuxi' }
]
},
...
]
</script>
<VPTeamPage>
<VPTeamPageTitle>
<template #title>
تیم ما
</template>
<template #lead>
توسعه ویت‌پرس توسط تیمی بین‌المللی راهنمایی می‌شود، برخی از اعضا که انتخاب کرده‌اند تا در زیر نمایش داده شوند.
</template>
</VPTeamPageTitle>
<VPTeamMembers
:members="members"
/>
</VPTeamPage>
```
در ایجاد یک صفحه کامل تیم، به یاد داشته باشید که همهٔ کامپوننت‌ها را با کامپوننت `<VPTeamPage>` بپوشانید. این کامپوننت تضمین می‌کند که همهٔ کامپوننت‌های مرتبط با تیم در ساختار طراحی مناسبی مانند فضاهای خالی قرار می‌گیرند.
کامپوننت `<VPPageTitle>` بخش عنوان صفحه را اضافه می‌کند. عنوان به عنوان `<h1>` نمایش داده می‌شود. از اسلات‌های `#title` و `#lead` برای مستندسازی در مورد تیم خود استفاده کنید.
`<VPMembers>` به عنوان زمانی که در یک صفحه مستند استفاده می‌شود، کار می‌کند. این لیست اعضا را نمایش می‌دهد.
### اضافه کردن بخش‌ها برای تقسیم اعضای تیم {#add-sections-to-divide-team-members}
می‌توانید بخش‌ها را به صفحه تیم اضافه کنید. به عنوان مثال، ممکن است اعضای مختلف تیمی مانند اعضای تیم اصلی و شرکای اجتماعی داشته باشید. شما می‌توانید این اعضا را به بخش‌ها تقسیم کنید تا نقش هر گروه بهتر توضیح داده شود.
برای این کار، کامپوننت `<VPTeamPageSection>` را به فایل `team.md` اضافه کنید که قبلاً ایجاد کردیم.
```html
---
layout: page
---
<script setup>
import {
VPTeamPage,
VPTeamPageTitle,
VPTeamMembers,
VPTeamPageSection
} from 'vitepress/theme'
const coreMembers = [...]
const partners = [...]
</script>
<VPTeamPage>
<VPTeamPageTitle>
<template #title>تیم ما</template>
<template #lead>...</template>
</VPTeamPageTitle>
<VPTeamMembers size="medium" :members="coreMembers" />
<VPTeamPageSection>
<template #title>شرکای تجاری</template>
<template #lead>...</template>
<template #members>
<VPTeamMembers size="small" :members="partners" />
</template>
</VPTeamPageSection>
</VPTeamPage>
```
کامپوننت `<VPTeamPageSection>` می‌تواند همچون کامپوننت `VPTeamPageTitle` دارای اسلات‌های `#title` و `#lead` باشد و همچنین اسلات `#members` را برای نمایش اعضای تیم پذیرفته است.
به یاد داشته باشید که کامپوننت `<VPTeamMembers>` را درون اسلات `#members` قرار دهید.
## `<VPTeamMembers>` {#vpteammembers}
کامپوننت `<VPTeamMembers>` لیست داده‌شده از اعضا را نمایش می‌دهد.
```html
<VPTeamMembers
size="medium"
:members="[
{ avatar: '...', name: '...' },
{ avatar: '...', name: '...' },
...
]"
/>
```
```ts
interface Props {
// اندازه هر عضو. پیش‌فرض به `medium`.
size?: 'small' | 'medium'
// لیست اعضا برای نمایش.
members: TeamMember[]
}
interface TeamMember {
// تصویر آواتار برای عضو.
avatar: string
// نام عضو.
name: string
// عنوانی که زیر نام عضو نمایش داده خواهد شد.
// برای مثال، توسعه‌دهنده، مهندس نرم‌افزار و غیره.
title?: string
// سازمانی که عضو به آن تعلق دارد.
org?: string
// پیوند URL برای سازمان.
orgLink?: string
// توضیحات برای عضو.
desc?: string
// پیوندهای اجتماعی. برای مثال، GitHub، Twitter و غیره. می‌توانید شیء پیوندهای اجتماعی را در اینجا ارسال کنید.
// مشاهده: https://vitepress.dev/reference/default-theme-config.html#sociallinks
links?: SocialLink[]
// URL برای صفحه حامی برای عضو.
sponsor?: string
// متن برای لینک حامی. پیش‌فرض به 'حمایت‌کننده'.
actionText?: string
}
```
## `<VPTeamPage>` {#vpteampage}
کامپوننت ریشه هنگام ایجاد یک صفحه کامل تیم. فقط یک اسلات را قبول می‌کند. این همه کامپوننت‌های مربوط به تیم را استایل می‌کند.
## `<VPTeamPageTitle>` {#vpteampagetitle}
بخش "عنوان" صفحه را اضافه می‌کند. بهترین استفاده را در ابتدایی‌ترین جای زیر `<VPTeamPage>` داشته باشد. این اسلات‌های `#title` و `#lead` را قبول می‌کند.
```html
<VPTeamPage>
<VPTeamPageTitle>
<template #title>
تیم ما
</template>
<template #lead>
توسعه ویت‌پرس توسط تیمی بین‌المللی راهنمایی می‌شود، برخی از اعضا که انتخاب کرده‌اند تا در زیر نمایش داده شوند.
</template>
</VPTeamPageTitle>
</VPTeamPage>
```
## `<VPTeamPageSection>` {#vpteampagesection}
یک "بخش" را درون صفحه تیم ایجاد می‌کند. اسلات‌های `#title`، `#lead` و `#members` را قبول می‌کند. می‌توانید هر تعداد بخش را درون `<VPTeamPage>` اضافه کنید.
```html
<VPTeamPage>
...
<VPTeamPageSection>
<template #title>شرکای تجاری</template>
<template #lead>Lorem ipsum...</template>
<template #members>
<VPTeamMembers :members="data" />
</template>
</VPTeamPageSection>
</VPTeamPage>
```

@ -0,0 +1,223 @@
---
outline: deep
---
# تنظیمات Frontmatter {#frontmatter-config}
Frontmatter امکان پیکربندی بر اساس صفحه را فراهم می‌کند. در هر فایل markdown، شما می‌توانید از تنظیمات frontmatter برای بازنویسی تنظیمات سطح سایت یا تم استفاده کنید. همچنین، تنظیماتی وجود دارند که فقط می‌توانید آن‌ها را در frontmatter تعریف کنید.
نمونه استفاده:
```md
---
title: مستندات با ویت‌پرس
editLink: true
---
```
شما می‌توانید به داده‌های frontmatter از طریق `$frontmatter` در بیانیه‌های Vue دسترسی داشته باشید:
```md
{{ $frontmatter.title }}
```
## title
- نوع: `string`
عنوان صفحه. همانطور که در [config.title](./site-config#title) است، این تنظیمات سطح سایت را بازنویسی می‌کند.
```yaml
---
title: ویت‌پرس
---
```
## titleTemplate
- نوع: `string | boolean`
پسوند برای عنوان. همانطور که در [config.titleTemplate](./site-config#titletemplate) است، این تنظیمات سطح سایت را بازنویسی می‌کند.
```yaml
---
title: ویت‌پرس
titleTemplate: Vite & Vue powered static site generator
---
```
## description
- نوع: `string`
توضیحات صفحه. همانطور که در [config.description](./site-config#description) است، این تنظیمات سطح سایت را بازنویسی می‌کند.
```yaml
---
description: ویت‌پرس
---
```
## head
- نوع: `HeadConfig[]`
تگ‌های head اضافی برای درج در صفحه فعلی. پس از تگ‌های head تزریق شده توسط تنظیمات سطح سایت، این تنظیمات درج می‌شوند.
```yaml
---
head:
- - meta
- name: description
content: hello
- - meta
- name: keywords
content: super duper SEO
---
```
```ts
type HeadConfig =
| [string, Record<string, string>]
| [string, Record<string, string>, string]
```
## فقط برای تم پیش‌فرض {#default-theme-only}
گزینه‌های frontmatter زیر فقط زمانی قابل استفاده هستند که از تم پیش‌فرض استفاده می‌کنید.
### layout
- نوع: `doc | home | page`
- پیش‌فرض: `doc`
تعیین چیدمان صفحه.
- `doc` - این چیدمان استایل‌های مستندات پیش‌فرض را به محتوای markdown اعمال می‌کند.
- `home` - چیدمان ویژه برای "صفحه اصلی". شما می‌توانید گزینه‌های اضافی مانند `hero` و `features` را اضافه کنید تا به سرعت یک صفحه نخست زیبا ایجاد کنید.
- `page` - مشابه `doc` عمل می‌کند اما هیچ استایلی به محتوا اعمال نمی‌شود. مفید است زمانی که می‌خواهید یک صفحه کاملاً سفارشی ایجاد کنید.
```yaml
---
layout: doc
---
```
### hero <Badge type="info" text="فقط برای صفحه اصلی" /> {#hero}
تعیین محتویات بخش hero صفحه اصلی هنگامی که `layout` به `home` تنظیم شده است. جزئیات بیشتر در [تم پیش‌فرض: صفحه اصلی](./default-theme-home-page).
### features <Badge type="info" text="فقط برای صفحه اصلی" /> {#features}
تعیین مواردی که در بخش ویژگی‌ها باید نمایش داده شوند هنگامی که `layout` به `home` تنظیم شده است. جزئیات بیشتر در [تم پیش‌فرض: صفحه اصلی](./default-theme-home-page).
### navbar
- نوع: `boolean`
- پیش‌فرض: `true`
آیا باید [نوار ناوبری](./default-theme-nav) نمایش داده شود یا خیر؟
```yaml
---
navbar: false
---
```
### sidebar
- نوع: `boolean`
- پیش‌فرض: `true`
آیا باید [نوار کناری](./default-theme-sidebar) نمایش داده شود یا خیر؟
```yaml
---
sidebar: false
---
```
### aside
- نوع: `boolean | 'left'`
- پیش‌فرض: `true`
تعیین مکان کامپوننت aside در چیدمان `doc`.
- اگر این مقدار را به `false` تنظیم کنید، اجرای کانتینر aside جلوگیری می‌کند.
- اگر این مقدار را به `true` تنظیم کنید، aside به راست اجرا می‌شود.
- اگر این مقدار را به `'left'` تنظیم کنید، aside به چپ اجرا می‌شود.
```yaml
---
aside: false
---
```
### outline
- نوع: `number | [number, number] | 'deep' | false`
- پیش‌فرض: `2`
سطوح سرفصل‌های مورد نمایش برای صفحه. همانطور که در [config.themeConfig.outline.level](./default-theme-config#outline) است، این مقدار سطح مجموعه سایت را بازنویسی می‌کند.
### lastUpdated
- نوع: `boolean | Date`
- پیش‌فرض: `true`
آیا متن [آخرین به‌روزرسانی](./default-theme-last-updated) را در پاورقی صفحه فعلی نمایش دهد یا خیر؟ اگر تاریخ و زمان مشخص شده باشد، به جای زمان اصلاح شده git نمایش داده می‌شود.
```yaml
---
lastUpdated: false
---
```
### editLink
- نوع: `boolean`
- پیش‌فرض: `true`
آیا [پیوند ویرایش](./default-theme-edit-link) را در پاورقی صفحه فعلی نمایش دهد یا خیر؟
```yaml
---
editLink: false
---
```
### footer
- نوع: `boolean`
- پیش‌فرض: `true`
آیا [پاورقی](./default-theme-footer) را
نمایش دهد یا خیر؟
```yaml
---
footer: false
---
```
### pageClass
- نوع: `string`
افزودن نام کلاس اضافی به یک صفحه خاص.
```yaml
---
pageClass: custom-page-class
---
```
سپس می‌توانید استایل‌های این صفحه خاص را در فایل `.vitepress/theme/custom.css` سفارشی کنید:
```css
.custom-page-class {
/* استایل‌های مخصوص صفحه */
}
```

@ -0,0 +1,168 @@
# API زمان اجرا {#runtime-api}
ویت‌پرس چندین API داخلی را ارائه می‌دهد تا به شما امکان دسترسی به داده‌های برنامه را بدهد. همچنین، ویت‌پرس با چندین کامپوننت داخلی همراه است که می‌توانید به صورت جهانی از آن‌ها استفاده کنید.
متدهای کمکی به صورت جهانی از `vitepress` قابل وارد کردن هستند و معمولاً در کامپوننت‌های Vue سفارشی تم استفاده می‌شوند. با این حال، آن‌ها همچنین در صفحات `.md` قابل استفاده هستند زیرا فایل‌های markdown به [کامپوننت‌های فایل تکی](https://vuejs.org/guide/scaling-up/sfc.html) Vue ترجمه می‌شوند.
متدهایی که با `use*` آغاز می‌شوند نشان می‌دهند که این یک تابع [API ترکیبی Vue 3](https://vuejs.org/guide/introduction.html#composition-api) ("Composable") است که فقط می‌تواند در `setup()` یا `<script setup>` استفاده شود.
## `useData` <Badge type="info" text="composable" /> {#usedata}
داده‌های خاص به صفحه را برمی‌گرداند. شیء برگشتی این نوع را دارد:
```ts
interface VitePressData<T = any> {
/**
* Metadata سطح سایت
*/
site: Ref<SiteData<T>>
/**
* themeConfig از .vitepress/config.js
*/
theme: Ref<T>
/**
* Metadata سطح صفحه
*/
page: Ref<PageData>
/**
* Frontmatter صفحه
*/
frontmatter: Ref<PageData['frontmatter']>
/**
* پارامترهای مسیر دینامیک
*/
params: Ref<PageData['params']>
title: Ref<string>
description: Ref<string>
lang: Ref<string>
isDark: Ref<boolean>
dir: Ref<string>
localeIndex: Ref<string>
/**
* مکان فعلی hash
*/
hash: Ref<string>
}
interface PageData {
title: string
titleTemplate?: string | boolean
description: string
relativePath: string
filePath: string,
headers: Header[]
frontmatter: Record<string, any>
params?: Record<string, any>
isNotFound?: boolean
lastUpdated?: number
}
```
**مثال:**
```vue
<script setup>
import { useData } from 'vitepress'
const { theme } = useData()
</script>
<template>
<h1>{{ theme.footer.copyright }}</h1>
</template>
```
## `useRoute` <Badge type="info" text="composable" /> {#useroute}
شیء مسیر فعلی را با این نوع برمی‌گرداند:
```ts
interface Route {
path: string
data: PageData
component: Component | null
}
```
## `useRouter` <Badge type="info" text="composable" /> {#userouter}
نمونه راوتر ویت‌پرس را برمی‌گرداند تا بتوانید به صورت برنامه‌ریزی‌شده به صفحه دیگری ناوبری کنید.
```ts
interface Router {
/**
* Route فعلی
*/
route: Route
/**
* به URL جدید ناوبری کنید.
*/
go: (to?: string) => Promise<void>
/**
* قبل از تغییر مسیر فراخوانی می‌شود. برای لغو ناوبری `false` را برگردانید.
*/
onBeforeRouteChange?: (to: string) => Awaitable<void | boolean>
/**
* قبل از بارگذاری مؤلفه صفحه فراخوانی می‌شود (پس از به‌روزرسانی وضعیت تاریخچه). برای لغو ناوبری `false` را برگردانید.
*/
onBeforePageLoad?: (to: string) => Awaitable<void | boolean>
/**
* پس از تغییر مسیر فراخوانی می‌شود.
*/
onAfterRouteChanged?: (to: string) => Awaitable<void>
}
```
## `withBase` <Badge type="info" text="helper" /> {#withbase}
- **نوع**: `(path: string) => string`
پایه [پیکربندی‌شده](./site-config#base) را به یک مسیر URL داده شده اضافه می‌کند. همچنین به [آدرس پایه](../guide/asset-handling#base-url) مراجعه کنید.
## `<Content />` <Badge type="info" text="component" /> {#content}
کامپوننت `<Content />` محتوای markdown را نمایش می‌دهد. مفید است [هنگام ایجاد تم شخصی شما](../guide/custom-theme).
```vue
<template>
<h1>چیدمان شخصی!</h1>
<Content />
</template>
```
## `<ClientOnly />` <Badge type="info" text="component" /> {#clientonly}
کامپوننت `<ClientOnly />` فقط اسلات خود را در سمت مشتری رندر می‌کند.
چون برنامه‌های ویت‌پرس هنگام ایجاد از سمت سرور در Node.js رندر می‌شوند، هر استفاده از Vue باید به الزامات کد یکپارچه دنیا پاسخ دهد. به طور خلاصه، اطمینان حاصل کنید که فقط در قالب hooks `beforeMount` یا `mounted` به APIهای Browser / DOM دسترسی دارید.
اگر از کامپوننت‌هایی استفاده یا نمایش دهنده‌هایی که با SSR سازگار نیستند (مانند دستورالعمل‌های سفارشی) استفاده می‌کنید، می‌توانید آن‌ها را داخل کامپوننت `ClientOnly` قرار دهید.
```vue-html
<ClientOnly>
<NonSSRFriendlyComponent />
</ClientOnly>
```
- مرتبط: [سازگاری با SSR](../guide/ssr-compat)
## `$frontmatter` <Badge type="info" text="template global" /> {#frontmatter}
در بیانیه‌های Vue، به صورت مستقیم به [داده‌های frontmatter](../guide/frontmatter) صفحه فعلی دسترسی پیدا کنید.
```md
---
title: سلام
---
# {{ $frontmatter.title }}
```
## `$params` <Badge type="info" text="template global" /> {#params}
در بیانیه‌های Vue، به صورت مستقیم به [پارامترهای مسیر دینامیک](../guide/routing#dynamic-routes) صفحه فعلی دسترسی پیدا کنید.
```md
- نام بسته: {{ $params.pkg }}
- نسخه: {{ $params.version }}
```

@ -0,0 +1,726 @@
---
outline: deep
---
# تنظیمات سایت {#site-config}
تنظیمات سایت جایی است که می‌توانید تنظیمات جهانی سایت را تعریف کنید. گزینه‌های تنظیمات برنامه شامل تنظیماتی است که برای هر سایت ویت‌پرس اعمال می‌شود، صرف نظر از اینکه از چه تمی استفاده می‌کند. برای مثال، دایرکتوری پایه یا عنوان سایت.
## مروری کلی {#overview}
### رفع تنظیمات {#config-resolution}
فایل تنظیمات همیشه از `<root>/.vitepress/config.[ext]` رفع می‌شود، جایی که `<root>` ریشه پروژه ویت‌پرس شما است و `[ext]` یکی از پسوندهای فایل پشتیبانی شده است. تایپ‌اسکریپت به طور پیش‌فرض پشتیبانی می‌شود. پسوندهای پشتیبانی شده شامل `.js`, `.ts`, `.mjs` و `.mts` هستند.
توصیه می‌شود از سینتکس ماژول‌های ES در فایل‌های تنظیمات استفاده کنید. فایل تنظیمات باید به طور پیش‌فرض یک شیء صادر کند:
```ts
export default {
// گزینه‌های تنظیمات سطح برنامه
lang: 'en-US',
title: 'ویت‌پرس',
description: 'مولد سایت استاتیک توسط Vite & Vue.',
...
}
```
:::details تنظیمات پویا (غیرهمزمان)
اگر نیاز دارید به طور پویا تنظیمات را تولید کنید، می‌توانید یک تابع صادر کنید. به عنوان مثال:
```ts
import { defineConfig } from 'vitepress'
export default async () => {
const posts = await (await fetch('https://my-cms.com/blog-posts')).json()
return defineConfig({
// گزینه‌های تنظیمات سطح برنامه
lang: 'en-US',
title: 'ویت‌پرس',
description: 'مولد سایت استاتیک توسط Vite & Vue.',
// گزینه‌های تنظیمات سطح تم
themeConfig: {
sidebar: [
...posts.map((post) => ({
text: post.name,
link: `/posts/${post.name}`
}))
]
}
})
}
```
همچنین می‌توانید از `await` سطح بالا استفاده کنید. به عنوان مثال:
```ts
import { defineConfig } from 'vitepress'
const posts = await (await fetch('https://my-cms.com/blog-posts')).json()
export default defineConfig({
// گزینه‌های تنظیمات سطح برنامه
lang: 'en-US',
title: 'ویت‌پرس',
description: 'مولد سایت استاتیک توسط Vite & Vue.',
// گزینه‌های تنظیمات سطح تم
themeConfig: {
sidebar: [
...posts.map((post) => ({
text: post.name,
link: `/posts/${post.name}`
}))
]
}
})
```
:::
### هوشمندی تنظیمات {#config-intellisense}
استفاده از تابع `defineConfig` هوشمندی تایپ‌اسکریپت را برای گزینه‌های تنظیمات فراهم می‌کند. فرض کنید IDE شما از آن پشتیبانی می‌کند، این باید هم در جاوااسکریپت و هم تایپ‌اسکریپت کار کند.
```js
import { defineConfig } from 'vitepress'
export default defineConfig({
// ...
})
```
### تنظیمات تایپ‌شده تم {#typed-theme-config}
به طور پیش‌فرض، تابع `defineConfig` انتظار دارد نوع تنظیمات تم از تم پیش‌فرض باشد:
```ts
import { defineConfig } from 'vitepress'
export default defineConfig({
themeConfig: {
// نوع `DefaultTheme.Config`
}
})
```
اگر از تم سفارشی استفاده می‌کنید و می‌خواهید بررسی نوع برای تنظیمات تم داشته باشید، باید به جای آن از `defineConfigWithTheme` استفاده کنید و نوع تنظیمات تم سفارشی خود را از طریق یک آرگومان جنریک منتقل کنید:
```ts
import { defineConfigWithTheme } from 'vitepress'
import type { ThemeConfig } from 'your-theme'
export default defineConfigWithTheme<ThemeConfig>({
themeConfig: {
// نوع `ThemeConfig`
}
})
```
### تنظیمات Vite, Vue و Markdown {#vite-vue-markdown-config}
- **Vite**
شما می‌توانید نمونه پایه Vite را با استفاده از گزینه [vite](#vite) در تنظیمات ویت‌پرس خود پیکربندی کنید. نیازی به ایجاد فایل تنظیمات Vite جداگانه نیست.
- **Vue**
ویت‌پرس از قبل پلاگین رسمی Vue برای Vite ([@vitejs/plugin-vue](https://github.com/vitejs/vite-plugin-vue)) را شامل می‌شود. شما می‌توانید گزینه‌های آن را با استفاده از گزینه [vue](#vue) در تنظیمات ویت‌پرس خود پیکربندی کنید.
- **Markdown**
شما می‌توانید نمونه پایه [Markdown-It](https://github.com/markdown-it/markdown-it) را با استفاده از گزینه [markdown](#markdown) در تنظیمات ویت‌پرس خود پیکربندی کنید.
## متاداده‌های سایت {#site-metadata}
### عنوان {#title}
- نوع: `string`
- پیش‌فرض: `ویت‌پرس`
- می‌تواند به ازای هر صفحه از طریق [frontmatter](./frontmatter-config#title) جایگزین شود.
عنوان سایت. هنگامی که از تم پیش‌فرض استفاده می‌کنید، این در نوار ناوبری نمایش داده می‌شود.
همچنین به عنوان پسوند پیش‌فرض برای تمام عناوین صفحات فردی استفاده می‌شود، مگر اینکه [`titleTemplate`](#titletemplate) تعریف شده باشد. عنوان نهایی صفحه‌ای به محتوای متنی اولین هدر `<h1>` آن صفحه ترکیب می‌شود با `title` جهانی به عنوان پسوند. به عنوان مثال با تنظیمات زیر و محتوای صفحه:
```ts
export default {
title: 'سایت فوق‌العاده من'
}
```
```md
# سلام
```
عنوان صفحه خواهد بود `سلام | سایت فوق‌العاده من`.
### قالب عنوان {##titletemplate}
- نوع: `string | boolean`
- می‌تواند به ازای هر صفحه از طریق [frontmatter](./frontmatter-config#titletemplate) جایگزین شود.
اجازه می‌دهد پسوند عنوان هر صفحه یا کل عنوان را سفارشی کنید. به عنوان مثال:
```ts
export default {
title: 'سایت فوق‌العاده من',
titleTemplate: 'پسوند سفارشی'
}
```
```md
# سلام
```
عنوان صفحه خواهد بود `سلام | پسوند سفارشی`.
برای سفارشی کردن کامل نحوه نمایش عنوان، می‌توانید از نماد `:title` در `titleTemplate` استفاده کنید:
```ts
export default {
titleTemplate: ':title - پسوند سفارشی'
}
```
اینجا `:title` با متن استنباط شده از اولین هدر `<h1>` صفحه جایگزین می‌شود. عنوان صفحه مثال قبلی خواهد بود `سلام - پسوند سفارشی`.
این گزینه می‌تواند به `false` تنظیم شود تا پسوندهای عنوان غیرفعال شوند.
### توضیحات {#description}
- نوع: `string`
- پیش‌فرض: `یک سایت ویت‌پرس`
- می‌تواند به ازای هر صفحه از طریق [frontmatter](./frontmatter-config#description) جایگزین شود.
توضیحات برای سایت. این به عنوان یک تگ `<meta>` در HTML صفحه رندر خواهد شد.
```ts
export default {
description: 'یک سایت ویت‌پرس'
}
```
### head
- نوع: `HeadConfig[]`
- پیش‌فرض: `[]`
- می‌تواند به ازای هر صفحه از طریق [frontmatter](./frontmatter-config#head) افزوده شود.
عناصر اضافی برای رندر در تگ `<head>` در HTML صفحه. تگ‌های افزوده شده توسط کاربر قبل از بسته شدن تگ `head`، پس از تگ‌های ویت‌پرس رندر می‌شوند.
```ts
type HeadConfig =
| [string, Record<string, string>]
| [string, Record<string, string>, string]
```
#### مثال: اضافه کردن یک favicon {#example-adding-a-favicon}
```ts
export default {
head: [['link', { rel: 'icon', href: '/favicon.ico' }]]
} // favicon.ico را در دایرکتوری عمومی قرار دهید، اگر base تنظیم شده است، از /base/favicon.ico استفاده کنید.
/* رندر خواهد شد:
<link rel="icon" href="/favicon.ico">
*/
```
#### مثال: اضافه کردن فونت‌های گوگل {#example-adding-google-fonts}
```ts
export default {
head: [
[
'link',
{ rel: 'preconnect', href: 'https://fonts.googleapis.com' }
],
[
'link',
{ rel: 'preconnect', href: 'https://fonts.gstatic.com', crossorigin: '' }
],
[
'link',
{ href: 'https://fonts.googleapis.com/css2?family=Roboto&display=swap', rel: 'stylesheet' }
]
]
}
/* رندر خواهد شد:
<link rel="preconnect" href="https://fonts.googleapis.com">
<link rel="preconnect" href="https://fonts.gstatic.com" crossorigin>
<link href="https://fonts.googleapis.com/css2?family=Roboto&display=swap" rel="stylesheet">
*/
```
#### مثال: ثبت یک سرویس ورکر {#example-registering-a-service-worker}
```ts
export default {
head: [
[
'script',
{ id: 'register-sw' },
`;(() => {
if ('serviceWorker' in navigator) {
navigator.serviceWorker.register('/sw.js')
}
})()`
]
]
}
/* رندر خواهد شد
:
<script id="register-sw">
;(() => {
if ('serviceWorker' in navigator) {
navigator.serviceWorker.register('/sw.js')
}
})()
</script>
*/
```
#### مثال: استفاده از گوگل آنالیتیکس {#example-using-google-analytics}
```ts
export default {
head: [
[
'script',
{ async: '', src: 'https://www.googletagmanager.com/gtag/js?id=TAG_ID' }
],
[
'script',
{},
`window.dataLayer = window.dataLayer || [];
function gtag(){dataLayer.push(arguments);}
gtag('js', new Date());
gtag('config', 'TAG_ID');`
]
]
}
/* رندر خواهد شد:
<script async src="https://www.googletagmanager.com/gtag/js?id=TAG_ID"></script>
<script>
window.dataLayer = window.dataLayer || [];
function gtag(){dataLayer.push(arguments);}
gtag('js', new Date());
gtag('config', 'TAG_ID');
</script>
*/
```
### زبان {#lang}
- نوع: `string`
- پیش‌فرض: `en-US`
ویژگی زبان برای سایت. این به عنوان یک تگ `<html lang="en-US">` در HTML صفحه رندر خواهد شد.
```ts
export default {
lang: 'en-US'
}
```
### پایه {#base}
- نوع: `string`
- پیش‌فرض: `/`
آدرس پایه‌ای که سایت در آن مستقر خواهد شد. اگر قصد دارید سایت خود را در یک مسیر فرعی مستقر کنید، باید این تنظیم را انجام دهید، به عنوان مثال، صفحات GitHub. اگر قصد دارید سایت خود را در `https://foo.github.io/bar/` مستقر کنید، باید پایه را به `'/bar/'` تنظیم کنید. این باید همیشه با یک اسلش شروع و پایان یابد.
پایه به طور خودکار به تمام آدرس‌های URL که با / شروع می‌شوند در سایر گزینه‌ها اضافه می‌شود، بنابراین فقط باید آن را یک بار مشخص کنید.
```ts
export default {
base: '/base/'
}
```
## مسیریابی {#routing}
### cleanUrls
- نوع: `boolean`
- پیش‌فرض: `false`
وقتی تنظیم شود به `true`، ویت‌پرس `.html` انتهایی را از URL ها حذف می‌کند. همچنین ببینید [تولید URL تمیز](../guide/routing#generating-clean-url).
::: هشدار نیاز به پشتیبانی سرور
فعال کردن این ممکن است نیاز به پیکربندی اضافی در پلتفرم میزبان شما داشته باشد. برای اینکه کار کند، سرور شما باید بتواند `/foo.html` را زمانی که `/foo` بازدید می‌شود **بدون ریدایرکت** سرو کند.
:::
### rewrites
- نوع: `Record<string, string>`
تعریف نقشه‌برداری‌های سفارشی دایرکتوری <-> URL. جزئیات بیشتر را در [مسیریابی: بازنویسی مسیرها](../guide/routing#route-rewrites) ببینید.
```ts
export default {
rewrites: {
'source/:page': 'destination/:page'
}
}
```
## ساخت {#build}
### srcDir
- نوع: `string`
- پیش‌فرض: `.`
دایرکتوری که صفحات مارک‌داون شما در آن ذخیره شده‌اند، نسبت به ریشه پروژه. همچنین ببینید [دایرکتوری ریشه و منبع](../guide/routing#root-and-source-directory).
```ts
export default {
srcDir: './src'
}
```
### srcExclude
- نوع: `string`
- پیش‌فرض: `undefined`
یک [الگوی glob](https://github.com/mrmlnc/fast-glob#pattern-syntax) برای تطبیق فایل‌های مارک‌داون که باید به عنوان محتوای منبع حذف شوند.
```ts
export default {
srcExclude: ['**/README.md', '**/TODO.md']
}
```
### outDir
- نوع: `string`
- پیش‌فرض: `./.vitepress/dist`
مکان خروجی ساخت برای سایت، نسبت به [ریشه پروژه](../guide/routing#root-and-source-directory).
```ts
export default {
outDir: '../public'
}
```
### assetsDir
- نوع: `string`
- پیش‌فرض: `assets`
دایرکتوری برای قرار دادن دارایی‌های تولید شده را مشخص کنید. مسیر باید داخل [`outDir`](#outdir) باشد و نسبت به آن حل شود.
```ts
export default {
assetsDir: 'static'
}
```
### cacheDir
- نوع: `string`
- پیش‌فرض: `./.vitepress/cache`
دایرکتوری برای فایل‌های کش، نسبت به [ریشه پروژه](../guide/routing#root-and-source-directory). همچنین ببینید: [cacheDir](https://vitejs.dev/config/shared-options.html#cachedir).
```ts
export default {
cacheDir: './.vitepress/.vite'
}
```
### ignoreDeadLinks
- نوع: `boolean | 'localhostLinks' | (string | RegExp | ((link: string) => boolean))[]`
- پیش‌فرض: `false`
زمانی که به `true` تنظیم شود، ویت‌پرس به دلیل لینک‌های مرده ساخت‌ها را شکست نخواهد داد.
وقتی به `'localhostLinks'` تنظیم شود، ساخت بر روی لینک‌های مرده شکست خواهد خورد، اما لینک‌های `localhost` بررسی نخواهند شد.
```ts
export default {
ignoreDeadLinks: true
}
```
همچنین می‌تواند یک آرایه از رشته‌های URL دقیق، الگوهای رگکس، یا توابع فیلتر سفارشی باشد.
```ts
export default {
ignoreDeadLinks: [
// نادیده گرفتن URL دقیق "/playground"
'/playground',
// نادیده گرفتن همه لینک‌های localhost
/^https?:\/\/localhost/,
// نادیده گرفتن همه لینک‌های شامل "/repl/""
/\/repl\//,
// تابع سفارشی، نادیده گرفتن همه لینک‌های شامل "ignore"
(url) => {
return url.toLowerCase().includes('ignore')
}
]
}
```
### metaChunk <Badge type="warning" text="experimental" /> {#metachunk}
- نوع: `boolean`
- پیش‌فرض: `false`
زمانی که به `true` تنظیم شود، فراداده‌های صفحات را به یک قسمت جداگانه جاوااسکریپت استخراج می‌کند به جای درون‌گذاری آن در HTML اولیه. این کار باعث کاهش بار HTML هر صفحه می‌شود و فراداده‌های صفحات قابل کش شدن می‌شود، که منجر به کاهش پهنای باند سرور می‌شود وقتی که صفحات زیادی در سایت دارید.
### mpa <Badge type="warning" text="experimental" /> {#mpa}
- نوع: `boolean`
- پیش‌فرض: `false`
زمانی که به `true` تنظیم شود، اپلیکیشن تولید شده در [حالت MPA](../guide/mpa-mode) ساخته خواهد شد. حالت MPA به طور پیش‌فرض 0 کیلوبایت جاوااسکریپت ارسال می‌کند، به هزینه غیرفعال کردن ناوبری سمت کاربر و نیاز به opt-in صریح برای تعامل.
## تم‌سازی {#theming}
### appearance
- نوع: `boolean | 'dark' | 'force-dark' | 'force-auto' | import('@vueuse/core').UseDarkOptions`
- پیش‌فرض: `true`
آیا حالت تاریک فعال شود یا نه (با اضافه کردن کلاس `.dark` به عنصر `<html>`).
- اگر گزینه به `true` تنظیم شود، تم پیش‌فرض با توجه به طرح رنگ مورد نظر کاربر تعیین می‌شود.
- اگر گزینه به `dark` تنظیم شود، تم به صورت پیش‌فرض تاریک خواهد بود، مگر اینکه کاربر آن را به صورت دستی تغییر دهد.
- اگر گزینه به `false` تنظیم شود، کاربران قادر به تغییر تم نخواهند بود.
- اگر گزینه به `force-dark` تنظیم شود، تم همیشه تاریک خواهد بود و کاربران نمی‌توانند آن را تغییر دهند.
- اگر گزینه به `force-auto` تنظیم شود، تم همیشه با توجه به طرح رنگ مورد نظر کاربر تعیین می‌شود و کاربران نمی‌توانند آن را تغییر دهند.
این گزینه یک اسکریپت داخلی تزریق می‌کند که تنظیمات کاربران را از حافظه محلی با استفاده از کلید `vitepress-theme-appearance` بازیابی می‌کند. این اطمینان حاصل می‌شود که کلاس `.dark` قبل از رندر شدن صفحه اعمال می‌شود تا از پرش جلوگیری شود.
`appearance.initialValue` فقط می‌تواند `dark` یا `undefined` باشد. Refs یا getters پشتیبانی نمی‌شوند.
### lastUpdated
- نوع: `boolean`
- پیش‌فرض: `false`
آیا زمان آخرین به‌روزرسانی برای هر صفحه با استفاده از Git دریافت شود. این زمان در داده‌های هر صفحه گنجانده خواهد شد و از طریق [`useData`](./runtime-api#usedata) قابل دسترسی خواهد بود.
وقتی از تم پیش‌فرض استفاده می‌کنید، فعال کردن این گزینه زمان آخرین به‌روزرسانی هر صفحه را نمایش می‌دهد. می‌توانید متن را از طریق گزینه [`themeConfig.lastUpdatedText`](./default-theme-config#lastupdatedtext) سفارشی کنید.
## سفارشی‌سازی {#customization}
### markdown
- نوع: `MarkdownOption`
گزینه‌های پارسر مارک‌داون را تنظیم کنید. ویت‌پرس از [Markdown-it](https://github.com/markdown-it/markdown-it) به عنوان پارسر استفاده می‌کند و [Shiki](https://github.com/shikijs/shiki) را برای برجسته‌سازی نحو زبان استفاده می‌کند. در داخل این گزینه، می‌توانید گزینه‌های مختلف مرتبط با مارک‌داون را بر اساس نیازهای خود ارسال کنید.
```js
export default {
markdown: {...}
}
```
برای مشاهده اعلامیه نوع و jsdocs برای همه گزینه‌های موجود، [type declaration and jsdocs](https://github.com/vuejs/vitepress/blob/main/src/node/markdown/markdown.ts) را بررسی کنید.
### vite
- نوع: `import('vite').UserConfig`
پیکربندی خام [Vite Config](https://vitejs.dev/config/) را به سرور توسعه داخلی / بسته‌بند Vite ارسال کنید.
```js
export default {
vite: {
// گزینه‌های پیکربندی Vite
}
}
```
### vue
- نوع: `import('@vitejs/plugin-vue').Options`
گزینه‌های خام [`@vitejs/plugin-vue` options](https://github.com/vitejs/vite-plugin-vue/tree/main/packages/plugin-vue#options) را به نمونه افزونه داخلی ارسال کنید.
```js
export default {
vue: {
// گزینه‌های @vitejs/plugin-vue
}
}
```
## قلاب‌های ساخت {#build-hooks}
قلاب‌های ساخت ویت‌پرس به شما امکان اضافه کردن عملکرد و رفتارهای جدید به وب‌سایت خود را می‌دهند:
- نقشه سایت
- شاخص‌بندی جستجو
- PWA
- Teleports
### buildEnd
- نوع: `(siteConfig: SiteConfig) => Awaitable<void>`
`buildEnd` یک قلاب CLI ساخت است، که بعد از اتمام ساخت (SSG) اجرا می‌شود اما قبل از خروج از فرآیند CLI ویت‌پرس.
```ts
export default {
async buildEnd(siteConfig) {
// ...
}
}
```
### postRender
- نوع: `(context: SSGContext) => Awaitable<SSGContext | void>`
`postRender` یک قلاب ساخت است که زمانی که رندر SSG انجام شد، فراخوانی می‌شود. این امکان را به شما می‌دهد که محتوای teleports را در حین SSG مدیریت کنید.
```ts
export default {
async postRender(context) {
// ...
}
}
```
```ts
interface SSGContext {
content: string
teleports?: Record<string, string>
[key: string]: any
}
```
### transformHead
- نوع: `(context: TransformContext) => Awaitable<HeadConfig[]>`
`transformHead` یک قلاب ساخت است که برای تغییر head قبل از تولید هر صفحه استفاده می‌شود. این امکان را به شما می‌دهد که ورودی‌های head اضافه کنید که نمی‌توانند به صورت استاتیک به تنظیمات ویت‌پرس اضافه شوند. شما فقط باید ورودی‌های اضافی را برگردانید، آنها به صورت خودکار با موارد موجود ترکیب می‌شوند.
::: warning هشدار
هیچ‌چیزی را در داخل `context` تغییر ندهید.
:::
```ts
export default {
async transform
Head(context) {
// ...
}
}
```
```ts
interface TransformContext {
page: string // به عنوان مثال index.md (نسبت به srcDir)
assets: string[] // همه دارایی‌های غیر js/css به عنوان URL عمومی کاملاً حل شده
siteConfig: SiteConfig
siteData: SiteData
pageData: PageData
title: string
description: string
head: HeadConfig[]
content: string
}
```
توجه داشته باشید که این قلاب فقط زمانی که سایت به صورت استاتیک تولید می‌شود فراخوانی می‌شود. در زمان توسعه فراخوانی نمی‌شود. اگر نیاز به اضافه کردن ورودی‌های head دینامیک در زمان توسعه دارید، می‌توانید به جای آن از قلاب [`transformPageData`](#transformpagedata) استفاده کنید:
```ts
export default {
transformPageData(pageData) {
pageData.frontmatter.head ??= []
pageData.frontmatter.head.push([
'meta',
{
name: 'og:title',
content:
pageData.frontmatter.layout === 'home'
? `ویت‌پرس`
: `${pageData.title} | ویت‌پرس`
}
])
}
}
```
#### مثال: اضافه کردن یک canonical URL `<link>` {#example-adding-a-canonical-url-link}
```ts
export default {
transformPageData(pageData) {
const canonicalUrl = `https://example.com/${pageData.relativePath}`
.replace(/index\.md$/, '')
.replace(/\.md$/, '.html')
pageData.frontmatter.head ??= []
pageData.frontmatter.head.push([
'link',
{ rel: 'canonical', href: canonicalUrl }
])
}
}
```
### transformHtml
- نوع: `(code: string, id: string, context: TransformContext) => Awaitable<string | void>`
`transformHtml` یک قلاب ساخت است که برای تغییر محتوای هر صفحه قبل از ذخیره به دیسک استفاده می‌شود.
::: warning هشدار
هیچ‌چیزی را در داخل `context` تغییر ندهید. همچنین، تغییر محتوای html ممکن است باعث مشکلات هیدراتاسیون در زمان اجرا شود.
:::
```ts
export default {
async transformHtml(code, id, context) {
// ...
}
}
```
### transformPageData
- نوع: `(pageData: PageData, context: TransformPageContext) => Awaitable<Partial<PageData> | { [key: string]: any } | void>`
`transformPageData` یک قلاب است که برای تغییر `pageData` هر صفحه استفاده می‌شود. شما می‌توانید `pageData` را به صورت مستقیم تغییر دهید یا مقادیر تغییر یافته را برگردانید که به داده‌های صفحه ادغام خواهند شد.
::: warning هشدار
هیچ‌چیزی را در داخل `context` تغییر ندهید و دقت کنید که این ممکن است بر عملکرد سرور توسعه تاثیر بگذارد، به ویژه اگر در این قلاب درخواست‌های شبکه یا محاسبات سنگین (مانند تولید تصاویر) داشته باشید. می‌توانید برای منطق شرطی بررسی کنید `process.env.NODE_ENV === 'production'`.
:::
```ts
export default {
async transformPageData(pageData, { siteConfig }) {
pageData.contributors = await getPageContributors(pageData.relativePath)
}
// یا داده‌ها را برای ادغام برگردانید
async transformPageData(pageData, { siteConfig }) {
return {
contributors: await getPageContributors(pageData.relativePath)
}
}
}
```
```ts
interface TransformPageContext {
siteConfig: SiteConfig
}
```

@ -6,7 +6,7 @@
},
"files": [
{
"location": ".vitepress/config/{en,zh,pt,ru,es,ko}.ts",
"location": ".vitepress/config/{en,zh,pt,ru,es,ko,fa}.ts",
"pattern": ".vitepress/config/@lang.ts",
"type": "universal"
},
@ -40,6 +40,10 @@
{
"label": "한국어",
"lang": "ko"
},
{
"label": "فارسی",
"lang": "fa"
}
],
"outDir": ".vitepress/dist/_translations",

@ -13,6 +13,7 @@
"@lunariajs/core": "^0.1.1",
"markdown-it-mathjax3": "^4.3.2",
"open-cli": "^8.0.0",
"postcss-rtlcss": "^5.5.1",
"vitepress": "workspace:*"
}
}

@ -320,6 +320,9 @@ importers:
open-cli:
specifier: ^8.0.0
version: 8.0.0
postcss-rtlcss:
specifier: ^5.5.1
version: 5.5.1(postcss@8.4.47)
vitepress:
specifier: workspace:*
version: link:..
@ -1622,6 +1625,10 @@ packages:
engines: {node: '>=18'}
hasBin: true
escalade@3.2.0:
resolution: {integrity: sha512-WUj2qlxaQtO4g6Pq5c29GTcWGDyd8itL8zTlipgECz3JesAiiOKotd8JU6otB3PACgG6xkJUyVhboMS+bje/jA==}
engines: {node: '>=6'}
escape-goat@3.0.0:
resolution: {integrity: sha512-w3PwNZJwRxlp47QGzhuEBldEqVHHhh8/tIPcl6ecf2Bou99cdAt0knihBV0Ecc7CGxYduXVBDheH1K2oADRlvw==}
engines: {node: '>=10'}
@ -2307,6 +2314,12 @@ packages:
peerDependencies:
postcss: ^8.0.0
postcss-rtlcss@5.5.1:
resolution: {integrity: sha512-xwA+RhS/6hV7n95rElQn2fLtcYfuXpk/t0EPuxu4LFJ/ma/f+tzN1EH4nN1vaBzRECBo4Xld+TI/QqxWfO61Nw==}
engines: {node: '>=18.0.0'}
peerDependencies:
postcss: ^8.4.21
postcss@8.4.47:
resolution: {integrity: sha512-56rxCq7G/XfB4EkXq9Egn5GCqugWvDFjafDOThIdMBsI15iqPqR5r15TfSr1YPYeEI19YeaXMCbY6u88Y76GLQ==}
engines: {node: ^10 || ^12 || >=14}
@ -2413,6 +2426,11 @@ packages:
engines: {node: '>=18.0.0', npm: '>=8.0.0'}
hasBin: true
rtlcss@4.3.0:
resolution: {integrity: sha512-FI+pHEn7Wc4NqKXMXFM+VAYKEj/mRIcW4h24YVwVtyjI+EqGrLc2Hx/Ny0lrZ21cBWU2goLy36eqMcNj3AQJig==}
engines: {node: '>=12.0.0'}
hasBin: true
run-applescript@7.0.0:
resolution: {integrity: sha512-9by4Ij99JUr/MCFBUkDKLWK3G9HVXmabKz9U5MlIAIuvuzkiOicRYs8XJLxX+xahD+mLiiCYDqF9dKAgtzKP1A==}
engines: {node: '>=18'}
@ -2572,6 +2590,10 @@ packages:
resolution: {integrity: sha512-aulFJcD6YK8V1G7iRB5tigAP4TsHBZZrOV8pjV++zdUwmeV8uzbY7yn6h9MswN62adStNZFuCIx4haBnRuMDaw==}
engines: {node: '>=18'}
strip-json-comments@3.1.1:
resolution: {integrity: sha512-6fPc+R4ihwqP6N/aIv2f1gMH8lOVtWQHoqC4yK6oSDVVocumAsfCqjkXnqiYMhmMwS/mEHLp7Vehlt3ql6lEig==}
engines: {node: '>=8'}
strtok3@7.1.1:
resolution: {integrity: sha512-mKX8HA/cdBqMKUr0MMZAFssCkIGoZeSCMXgnt79yKxNFguMLVFgRe6wB+fsL0NmoHDbeyZXczy7vEPSoo3rkzg==}
engines: {node: '>=16'}
@ -4159,6 +4181,8 @@ snapshots:
'@esbuild/win32-ia32': 0.24.0
'@esbuild/win32-x64': 0.24.0
escalade@3.2.0: {}
escape-goat@3.0.0: {}
esm@3.2.25: {}
@ -4837,6 +4861,11 @@ snapshots:
dependencies:
postcss: 8.4.47
postcss-rtlcss@5.5.1(postcss@8.4.47):
dependencies:
postcss: 8.4.47
rtlcss: 4.3.0
postcss@8.4.47:
dependencies:
nanoid: 3.3.7
@ -4963,6 +4992,13 @@ snapshots:
'@rollup/rollup-win32-x64-msvc': 4.24.4
fsevents: 2.3.3
rtlcss@4.3.0:
dependencies:
escalade: 3.2.0
picocolors: 1.1.1
postcss: 8.4.47
strip-json-comments: 3.1.1
run-applescript@7.0.0: {}
run-parallel@1.2.0:
@ -5119,6 +5155,8 @@ snapshots:
strip-final-newline@4.0.0: {}
strip-json-comments@3.1.1: {}
strtok3@7.1.1:
dependencies:
'@tokenizer/token': 0.3.0

@ -125,7 +125,7 @@ function scrollToTop() {
vertical-align: middle;
margin-left: 2px;
font-size: 14px;
transform: rotate(0deg);
transform: rotate(0)/*rtl:rotate(180deg)*/;
transition: transform 0.25s;
}
@ -140,6 +140,7 @@ function scrollToTop() {
}
.open > .icon {
/*rtl:ignore*/
transform: rotate(90deg);
}

@ -227,12 +227,13 @@ function onCaretClick() {
.caret-icon {
font-size: 18px;
/*rtl:ignore*/
transform: rotate(90deg);
transition: transform 0.25s;
}
.VPSidebarItem.collapsed .caret-icon {
transform: rotate(0);
transform: rotate(0)/*rtl:rotate(180deg)*/;
}
.VPSidebarItem.level-1 .items,

@ -493,6 +493,7 @@
border: 1px solid var(--vp-code-copy-code-hover-border-color);
/*rtl:ignore*/
border-right: 0;
/*rtl:ignore*/
border-radius: 4px 0 0 4px;
padding: 0 10px;
width: fit-content;
@ -566,6 +567,7 @@
--icon: url("data:image/svg+xml, %3Csvg xmlns='http://www.w3.org/2000/svg' viewBox='0 0 24 24' %3E%3Cpath d='M0 0h24v24H0V0z' fill='none' /%3E%3Cpath d='M9 5v2h6.59L4 18.59 5.41 20 17 8.41V15h2V5H9z' /%3E%3C/svg%3E");
-webkit-mask-image: var(--icon);
mask-image: var(--icon);
/*rtl:raw:transform: scaleX(-1);*/
}
.vp-external-link-icon::after {

@ -39,14 +39,17 @@
}
.vpi-chevron-down,
.vpi-arrow-down {
/*rtl:ignore*/
transform: rotate(90deg);
}
.vpi-chevron-left,
.vpi-arrow-left {
/*rtl:ignore*/
transform: rotate(180deg);
}
.vpi-chevron-up,
.vpi-arrow-up {
/*rtl:ignore*/
transform: rotate(-90deg);
}
.vpi-square-pen {

@ -174,15 +174,15 @@
* -------------------------------------------------------------------------- */
:root {
--vp-c-text-1: rgba(60, 60, 67);
--vp-c-text-2: rgba(60, 60, 67, 0.78);
--vp-c-text-3: rgba(60, 60, 67, 0.56);
--vp-c-text-1: #3c3c43;
--vp-c-text-2: #67676c;
--vp-c-text-3: #929295;
}
.dark {
--vp-c-text-1: rgba(255, 255, 245, 0.86);
--vp-c-text-2: rgba(235, 235, 245, 0.6);
--vp-c-text-3: rgba(235, 235, 245, 0.38);
--vp-c-text-1: #dfdfd6;
--vp-c-text-2: #98989f;
--vp-c-text-3: #6a6a71;
}
/**
@ -366,6 +366,23 @@
--vp-code-tab-active-bar-color: var(--vp-c-brand-1);
}
:lang(es),
:lang(pt) {
--vp-code-copy-copied-text-content: 'Copiado';
}
:lang(fa) {
--vp-code-copy-copied-text-content: 'کپی شد';
}
:lang(ko) {
--vp-code-copy-copied-text-content: '복사됨';
}
:lang(ru) {
--vp-code-copy-copied-text-content: 'Скопировано';
}
:lang(zh) {
--vp-code-copy-copied-text-content: '已复制';
}
/**
* Component: Button
* -------------------------------------------------------------------------- */

Loading…
Cancel
Save