vitepress/docs/fa/reference/default-theme-search.md

outline
deep

جستجو

جستجوی محلی

ویت‌پرس از جستجوی متن کامل نامتقارن با استفاده از یک فهرست در مرورگر با تشکر از minisearch پشتیبانی می‌کند. برای فعال‌سازی این ویژگی، کافی است گزینه themeConfig.search.provider را به 'local' در فایل .vitepress/config.ts خود تنظیم کنید:

import { defineConfig } from 'vitepress'

export default defineConfig({
  themeConfig: {
    search: {
      provider: 'local'
    }
  }
})

نمونه نتیجه:

همچنین، می‌توانید از Algolia DocSearch یا برخی افزونه‌های جامعه‌ای مانند https://www.npmjs.com/package/vitepress-plugin-search یا https://www.npmjs.com/package/vitepress-plugin-pagefind استفاده کنید.

بین‌المللی‌سازی

می‌توانید با استفاده از تنظیماتی مانند این برای جستجوی چندزبانه استفاده کنید:

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 را به این صورت پیکربندی کنید:

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 مراجعه کنید.

سفارشی‌سازی رندر محتوا

می‌توانید تابع استفاده شده برای رندر محتوای Markdown قبل از فهرست‌بندی آن را سفارشی‌سازی کنید:

import { defineConfig } from 'vitepress'

export default defineConfig({
  themeConfig: {
    search: {
      provider: 'local',
      options: {
        /**
         * @param {string} src
         * @param {import('vitepress').MarkdownEnv} env
         * @param {import('markdown-it-async')} md
         */
        async _render(src, env, md) {
          // بازگشت رشته HTML
        }
      }
    }
  }
})

این تابع از داده‌های سایت سمت کلاینت پاک خواهد شد، بنابراین شما می‌توانید از API‌های Node.js در آن استفاده کنید.

مثال: استثنای صفحات از جستجو

می‌توانید با اضافه کردن search: false به frontmatter صفحه، صفحات را از جستجو استثنا دهید. به طور جایگزین:

import { defineConfig } from 'vitepress'

export default defineConfig({
  themeConfig: {
    search: {
      provider: 'local',
      options: {
        async _render(src, env, md) {
          const html = await md.renderAsync(src, env)
          if (env.frontmatter?.search === false) return ''
          if (env.relativePath.startsWith('some/path')) return ''
          return html
        }
      }
    }
  }
})

::: warning توجه در صورت ارائه تابع _render سفارشی، باید خودتان بررسی کنید که آیا frontmatter search: false را مدیریت می‌کند یا خیر. همچنین، شی env قبل از فراخوانی md.renderAsync کاملاً پر نمی‌شود، بنابراین هر بررسی‌ای روی ویژگی‌های اختیاری env مانند frontmatter باید بعد از آن انجام شود. :::

مثال: تبدیل محتوا - افزودن لینک‌های صفحه

import { defineConfig } from 'vitepress'

export default defineConfig({
  themeConfig: {
    search: {
      provider: 'local',
      options: {
        async _render(src, env, md) {
          const html = await md.renderAsync(src, env)
          if (env.frontmatter?.title)
            return await md.renderAsync(`# ${env.frontmatter.title}`) + html
          return html
        }
      }
    }
  }
})

جستجوی Algolia

ویت‌پرس از جستجو در سایت مستندات شما با استفاده از Algolia DocSearch پشتیبانی می‌کند. به راهنمای شروع کار آن‌ها مراجعه کنید. در فایل .vitepress/config.ts شما نیاز دارید که حداقل موارد زیر را فراهم کنید تا کار کند:

import { defineConfig } from 'vitepress'

export default defineConfig({
  themeConfig: {
    search: {
      provider: 'algolia',
      options: {
        appId: '...',
        apiKey: '...',
        indexName: '...'
      }
    }
  }
})

بین‌المللی‌سازی

می‌توانید با استفاده از تنظیماتی مانند این برای جستجوی چندزبانه استفاده کنید:

برای باز کردن کلیک کنید

<<< @/snippets/algolia-i18n.ts

برای اطلاعات بیشتر به مستندات رسمی Algolia مراجعه کنید. برای شروع سریع‌تر، می‌توانید ترجمه‌های استفاده‌شده در این سایت را از مخزن GitHub ما کپی کنید.

پشتیبانی Algolia Ask AI

برای فعال‌سازی Ask AI کافی است گزینه askAi را اضافه کنید:

options: {
  appId: '...',
  apiKey: '...',
  indexName: '...',
  askAi: {
    assistantId: 'XXXYYY'
  }
}

::: warning نکته اگر فقط به جستجوی کلمات کلیدی نیاز دارید، askAi را اضافه نکنید. :::

پنل کناری Ask AI

DocSearch v4.5+ از پنل کناری Ask AI اختیاری پشتیبانی می‌کند. وقتی فعال باشد، به طور پیش‌فرض می‌توان آن را با Ctrl/Cmd+I باز کرد. مرجع API پنل کناری شامل لیست کامل گزینه‌ها است.

import { defineConfig } from 'vitepress'

export default defineConfig({
  themeConfig: {
    search: {
      provider: 'algolia',
      options: {
        appId: '...',
        apiKey: '...',
        indexName: '...',
        askAi: {
          assistantId: 'XXXYYY',
          sidePanel: {
            // آینه API @docsearch/sidepanel-js SidepanelProps
            panel: {
              variant: 'floating', // یا 'inline'
              side: 'right',
              width: '360px',
              expandedWidth: '580px',
              suggestedQuestions: true
            }
          }
        }
      }
    }
  }
})

اگر نیاز به غیرفعال کردن میانبر صفحه‌کلید دارید، از گزینه keyboardShortcuts پنل کناری استفاده کنید:

import { defineConfig } from 'vitepress'

export default defineConfig({
  themeConfig: {
    search: {
      provider: 'algolia',
      options: {
        appId: '...',
        apiKey: '...',
        indexName: '...',
        askAi: {
          assistantId: 'XXXYYY',
          sidePanel: {
            keyboardShortcuts: {
              'Ctrl/Cmd+I': false
            }
          }
        }
      }
    }
  }
})

حالت (auto / sidePanel / hybrid / modal)

می‌توانید به صورت اختیاری نحوه ادغام جستجوی کلمات کلیدی و Ask AI در VitePress را کنترل کنید:

• mode: 'auto' (پیش‌فرض): وقتی جستجوی کلمات کلیدی پیکربندی شده باشد hybrid را استنباط می‌کند، در غیر این صورت وقتی پنل کناری Ask AI پیکربندی شده باشد sidePanel را استنباط می‌کند.
• mode: 'sidePanel': فقط پنل کناری را اعمال می‌کند (دکمه جستجوی کلمات کلیدی را پنهان می‌کند).
• mode: 'hybrid': مودال جستجوی کلمات کلیدی + پنل کناری Ask AI را فعال می‌کند (نیاز به پیکربندی جستجوی کلمات کلیدی دارد).
• mode: 'modal': Ask AI را درون مودال DocSearch نگه می‌دارد (حتی اگر پنل کناری را پیکربندی کرده باشید).

فقط Ask AI (بدون جستجوی کلمات کلیدی)

اگر می‌خواهید فقط پنل کناری Ask AI را استفاده کنید، می‌توانید پیکربندی جستجوی کلمات کلیدی سطح بالا را حذف کرده و اعتبارنامه‌ها را در askAi ارائه دهید:

import { defineConfig } from 'vitepress'

export default defineConfig({
  themeConfig: {
    search: {
      provider: 'algolia',
      options: {
        mode: 'sidePanel',
        askAi: {
          assistantId: 'XXXYYY',
          appId: '...',
          apiKey: '...',
          indexName: '...',
          sidePanel: true
        }
      }
    }
  }
})

پیکربندی Crawler

در اینجا یک پیکربندی نمونه بر اساس آنچه که این سایت استفاده می‌کند آمده است:

<<< @/snippets/algolia-crawler.js