import{_ as e,c as h,ag as t,j as i,a,G as l,B as p,o as k}from"./chunks/framework.C1C4sYC0.js";const m=JSON.parse('{"title":"تنظیمات سایت","description":"","frontmatter":{"outline":"deep"},"headers":[],"relativePath":"fa/reference/site-config.md","filePath":"fa/reference/site-config.md","lastUpdated":1734087948000}'),d={name:"fa/reference/site-config.md"},r={id:"metachunk",tabindex:"-1"},E={id:"mpa",tabindex:"-1"};function g(o,s,c,y,F,u){const n=p("Badge");return k(),h("div",null,[s[6]||(s[6]=t(`

تنظیمات سایت ​

تنظیمات سایت جایی است که می‌توانید تنظیمات جهانی سایت را تعریف کنید. گزینه‌های تنظیمات برنامه شامل تنظیماتی است که برای هر سایت ویت‌پرس اعمال می‌شود، صرف نظر از اینکه از چه تمی استفاده می‌کند. برای مثال، دایرکتوری پایه یا عنوان سایت.

مروری کلی ​

رفع تنظیمات ​

فایل تنظیمات همیشه از <root>/.vitepress/config.[ext] رفع می‌شود، جایی که <root> ریشه پروژه ویت‌پرس شما است و [ext] یکی از پسوندهای فایل پشتیبانی شده است. تایپ‌اسکریپت به طور پیش‌فرض پشتیبانی می‌شود. پسوندهای پشتیبانی شده شامل .js, .ts, .mjs و .mts هستند.

توصیه می‌شود از سینتکس ماژول‌های ES در فایل‌های تنظیمات استفاده کنید. فایل تنظیمات باید به طور پیش‌فرض یک شیء صادر کند:

ts
export default {
  // گزینه‌های تنظیمات سطح برنامه
  lang: 'en-US',
  title: 'ویت‌پرس',
  description: 'مولد سایت استاتیک توسط Vite & Vue.',
  ...
}
تنظیمات پویا (غیرهمزمان)

اگر نیاز دارید به طور پویا تنظیمات را تولید کنید، می‌توانید یک تابع صادر کنید. به عنوان مثال:

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}\`
      }))
    ]
  }
})

هوشمندی تنظیمات ​

استفاده از تابع defineConfig هوشمندی تایپ‌اسکریپت را برای گزینه‌های تنظیمات فراهم می‌کند. فرض کنید IDE شما از آن پشتیبانی می‌کند، این باید هم در جاوااسکریپت و هم تایپ‌اسکریپت کار کند.

js
import { defineConfig } from 'vitepress'

export default defineConfig({
  // ...
})

تنظیمات تایپ‌شده تم ​

به طور پیش‌فرض، تابع 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 ​

متاداده‌های سایت ​

عنوان ​

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

همچنین به عنوان پسوند پیش‌فرض برای تمام عناوین صفحات فردی استفاده می‌شود، مگر اینکه titleTemplate تعریف شده باشد. عنوان نهایی صفحه‌ای به محتوای متنی اولین هدر <h1> آن صفحه ترکیب می‌شود با title جهانی به عنوان پسوند. به عنوان مثال با تنظیمات زیر و محتوای صفحه:

ts
export default {
  title: 'سایت فوق‌العاده من'
}
md
# سلام

عنوان صفحه خواهد بود سلام | سایت فوق‌العاده من.

قالب عنوان ​

اجازه می‌دهد پسوند عنوان هر صفحه یا کل عنوان را سفارشی کنید. به عنوان مثال:

ts
export default {
  title: 'سایت فوق‌العاده من',
  titleTemplate: 'پسوند سفارشی'
}
md
# سلام

عنوان صفحه خواهد بود سلام | پسوند سفارشی.

برای سفارشی کردن کامل نحوه نمایش عنوان، می‌توانید از نماد :title در titleTemplate استفاده کنید:

ts
export default {
  titleTemplate: ':title - پسوند سفارشی'
}

اینجا :title با متن استنباط شده از اولین هدر <h1> صفحه جایگزین می‌شود. عنوان صفحه مثال قبلی خواهد بود سلام - پسوند سفارشی.

این گزینه می‌تواند به false تنظیم شود تا پسوندهای عنوان غیرفعال شوند.

توضیحات ​

توضیحات برای سایت. این به عنوان یک تگ <meta> در HTML صفحه رندر خواهد شد.

ts
export default {
  description: 'یک سایت ویت‌پرس'
}

عناصر اضافی برای رندر در تگ <head> در HTML صفحه. تگ‌های افزوده شده توسط کاربر قبل از بسته شدن تگ head، پس از تگ‌های ویت‌پرس رندر می‌شوند.

ts
type HeadConfig =
  | [string, Record<string, string>]
  | [string, Record<string, string>, string]

مثال: اضافه کردن یک favicon ​

ts
export default {
  head: [['link', { rel: 'icon', href: '/favicon.ico' }]]
} // favicon.ico را در دایرکتوری عمومی قرار دهید، اگر base تنظیم شده است، از /base/favicon.ico استفاده کنید.

/* رندر خواهد شد:
  <link rel="icon" href="/favicon.ico">
*/

مثال: اضافه کردن فونت‌های گوگل ​

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">
*/

مثال: ثبت یک سرویس ورکر ​

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>
*/

مثال: استفاده از گوگل آنالیتیکس ​

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>
*/

زبان ​

ویژگی زبان برای سایت. این به عنوان یک تگ <html lang="en-US"> در HTML صفحه رندر خواهد شد.

ts
export default {
  lang: 'en-US'
}

پایه ​

آدرس پایه‌ای که سایت در آن مستقر خواهد شد. اگر قصد دارید سایت خود را در یک مسیر فرعی مستقر کنید، باید این تنظیم را انجام دهید، به عنوان مثال، صفحات GitHub. اگر قصد دارید سایت خود را در https://foo.github.io/bar/ مستقر کنید، باید پایه را به '/bar/' تنظیم کنید. این باید همیشه با یک اسلش شروع و پایان یابد.

پایه به طور خودکار به تمام آدرس‌های URL که با / شروع می‌شوند در سایر گزینه‌ها اضافه می‌شود، بنابراین فقط باید آن را یک بار مشخص کنید.

ts
export default {
  base: '/base/'
}

مسیریابی ​

cleanUrls ​

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

::: هشدار نیاز به پشتیبانی سرور فعال کردن این ممکن است نیاز به پیکربندی اضافی در پلتفرم میزبان شما داشته باشد. برای اینکه کار کند، سرور شما باید بتواند /foo.html را زمانی که /foo بازدید می‌شود بدون ریدایرکت سرو کند. :::

rewrites ​

تعریف نقشه‌برداری‌های سفارشی دایرکتوری <-> URL. جزئیات بیشتر را در مسیریابی: بازنویسی مسیرها ببینید.

ts
export default {
  rewrites: {
    'source/:page': 'destination/:page'
  }
}

ساخت ​

srcDir ​

دایرکتوری که صفحات مارک‌داون شما در آن ذخیره شده‌اند، نسبت به ریشه پروژه. همچنین ببینید دایرکتوری ریشه و منبع.

ts
export default {
  srcDir: './src'
}

srcExclude ​

یک الگوی glob برای تطبیق فایل‌های مارک‌داون که باید به عنوان محتوای منبع حذف شوند.

ts
export default {
  srcExclude: ['**/README.md', '**/TODO.md']
}

outDir ​

مکان خروجی ساخت برای سایت، نسبت به ریشه پروژه.

ts
export default {
  outDir: '../public'
}

assetsDir ​

دایرکتوری برای قرار دادن دارایی‌های تولید شده را مشخص کنید. مسیر باید داخل outDir باشد و نسبت به آن حل شود.

ts
export default {
  assetsDir: 'static'
}

cacheDir ​

دایرکتوری برای فایل‌های کش، نسبت به ریشه پروژه. همچنین ببینید: cacheDir.

ts
export default {
  cacheDir: './.vitepress/.vite'
}

زمانی که به 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')
    }
  ]
}
`,98)),i("h3",r,[s[0]||(s[0]=a("metaChunk ")),l(n,{type:"warning",text:"experimental"}),s[1]||(s[1]=a()),s[2]||(s[2]=i("a",{class:"header-anchor",href:"#metachunk","aria-label":'Permalink to "metaChunk {#metachunk}"'},"​",-1))]),s[7]||(s[7]=i("ul",null,[i("li",null,[a("نوع: "),i("code",null,"boolean")]),i("li",null,[a("پیش‌فرض: "),i("code",null,"false")])],-1)),s[8]||(s[8]=i("p",null,[a("زمانی که به "),i("code",null,"true"),a(" تنظیم شود، فراداده‌های صفحات را به یک قسمت جداگانه جاوااسکریپت استخراج می‌کند به جای درون‌گذاری آن در HTML اولیه. این کار باعث کاهش بار HTML هر صفحه می‌شود و فراداده‌های صفحات قابل کش شدن می‌شود، که منجر به کاهش پهنای باند سرور می‌شود وقتی که صفحات زیادی در سایت دارید.")],-1)),i("h3",E,[s[3]||(s[3]=a("mpa ")),l(n,{type:"warning",text:"experimental"}),s[4]||(s[4]=a()),s[5]||(s[5]=i("a",{class:"header-anchor",href:"#mpa","aria-label":'Permalink to "mpa {#mpa}"'},"​",-1))]),s[9]||(s[9]=t(`

زمانی که به true تنظیم شود، اپلیکیشن تولید شده در حالت MPA ساخته خواهد شد. حالت MPA به طور پیش‌فرض 0 کیلوبایت جاوااسکریپت ارسال می‌کند، به هزینه غیرفعال کردن ناوبری سمت کاربر و نیاز به opt-in صریح برای تعامل.

تم‌سازی ​

appearance ​

آیا حالت تاریک فعال شود یا نه (با اضافه کردن کلاس .dark به عنصر <html>).

این گزینه یک اسکریپت داخلی تزریق می‌کند که تنظیمات کاربران را از حافظه محلی با استفاده از کلید vitepress-theme-appearance بازیابی می‌کند. این اطمینان حاصل می‌شود که کلاس .dark قبل از رندر شدن صفحه اعمال می‌شود تا از پرش جلوگیری شود.

appearance.initialValue فقط می‌تواند dark یا undefined باشد. Refs یا getters پشتیبانی نمی‌شوند.

lastUpdated ​

آیا زمان آخرین به‌روزرسانی برای هر صفحه با استفاده از Git دریافت شود. این زمان در داده‌های هر صفحه گنجانده خواهد شد و از طریق useData قابل دسترسی خواهد بود.

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

سفارشی‌سازی ​

markdown ​

گزینه‌های پارسر مارک‌داون را تنظیم کنید. ویت‌پرس از Markdown-it به عنوان پارسر استفاده می‌کند و Shiki را برای برجسته‌سازی نحو زبان استفاده می‌کند. در داخل این گزینه، می‌توانید گزینه‌های مختلف مرتبط با مارک‌داون را بر اساس نیازهای خود ارسال کنید.

js
export default {
  markdown: {...}
}

برای مشاهده اعلامیه نوع و jsdocs برای همه گزینه‌های موجود، type declaration and jsdocs را بررسی کنید.

vite ​

پیکربندی خام Vite Config را به سرور توسعه داخلی / بسته‌بند Vite ارسال کنید.

js
export default {
  vite: {
    // گزینه‌های پیکربندی Vite
  }
}

vue ​

گزینه‌های خام @vitejs/plugin-vue options را به نمونه افزونه داخلی ارسال کنید.

js
export default {
  vue: {
    // گزینه‌های @vitejs/plugin-vue
  }
}

قلاب‌های ساخت ​

قلاب‌های ساخت ویت‌پرس به شما امکان اضافه کردن عملکرد و رفتارهای جدید به وب‌سایت خود را می‌دهند:

buildEnd ​

buildEnd یک قلاب CLI ساخت است، که بعد از اتمام ساخت (SSG) اجرا می‌شود اما قبل از خروج از فرآیند CLI ویت‌پرس.

ts
export default {
  async buildEnd(siteConfig) {
    // ...
  }
}

postRender ​

postRender یک قلاب ساخت است که زمانی که رندر SSG انجام شد، فراخوانی می‌شود. این امکان را به شما می‌دهد که محتوای teleports را در حین SSG مدیریت کنید.

ts
export default {
  async postRender(context) {
    // ...
  }
}
ts
interface SSGContext {
  content: string
  teleports?: Record<string, string>
  [key: string]: any
}

transformHead ​

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

هشدار

هیچ‌چیزی را در داخل 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 استفاده کنید:

ts
export default {
  transformPageData(pageData) {
    pageData.frontmatter.head ??= []
    pageData.frontmatter.head.push([
      'meta',
      {
        name: 'og:title',
        content:
          pageData.frontmatter.layout === 'home'
            ? \`ویت‌پرس\`
            : \`\${pageData.title} | ویت‌پرس\`
      }
    ])
  }
}
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 ​

transformHtml یک قلاب ساخت است که برای تغییر محتوای هر صفحه قبل از ذخیره به دیسک استفاده می‌شود.

هشدار

هیچ‌چیزی را در داخل context تغییر ندهید. همچنین، تغییر محتوای html ممکن است باعث مشکلات هیدراتاسیون در زمان اجرا شود.

ts
export default {
  async transformHtml(code, id, context) {
    // ...
  }
}

transformPageData ​

transformPageData یک قلاب است که برای تغییر pageData هر صفحه استفاده می‌شود. شما می‌توانید pageData را به صورت مستقیم تغییر دهید یا مقادیر تغییر یافته را برگردانید که به داده‌های صفحه ادغام خواهند شد.

هشدار

هیچ‌چیزی را در داخل 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
}
`,60))])}const f=e(d,[["render",g]]);export{m as __pageData,f as default};