docusaurus search local

غير متصل / بحث محلي عن Docusaurus v2+

بحث محلي/غير متصل بالإنترنت عن Docusaurus v2+ الذي يعمل خلف جدار الحماية الخاص بك.

أبرز الميزات:

• يدعم إصدارات وثائق متعددة
• يدعم الوثائق المكتوبة بلغات أخرى غير الإنجليزية
• يسلط الضوء على نتائج البحث
• محللون مخصصون للمستندات والمدونات والصفحات العامة
• كسول - تحميل الفهرس

ملاحظة: نستخدم مكتبة algolia/الإكمال التلقائي مفتوحة المصدر لمربع البحث. يتم استخدام هذه المكتبة فقط كواجهة أمامية، وعلى عكس تجربة بحث Docusaurus الافتراضية (algolia/docsearch)، لا تتصل بأي خوادم Algolia أو خوادم خارجية .

تثبيت

npm install @cmfcmf/docusaurus-search-local

أو

yarn add @cmfcmf/docusaurus-search-local

الاستخدام

أضف هذا المكون الإضافي إلى مصفوفة plugins في docusaurus.config.js .

 module . exports = {
  // ...
  plugins : [ require . resolve ( "@cmfcmf/docusaurus-search-local" ) ] ,

  // or, if you want to specify options:

  // ...
  plugins : [
    [
      require . resolve ( "@cmfcmf/docusaurus-search-local" ) ,
      {
        // Options here
      } ,
    ] ,
  ] ,
} ;

تتوفر الخيارات التالية (الافتراضيات موضحة أدناه):

 {
  // whether to index docs pages
  indexDocs : true ,

  // Whether to also index the titles of the parent categories in the sidebar of a doc page.
  // 0 disables this feature.
  // 1 indexes the direct parent category in the sidebar of a doc page
  // 2 indexes up to two nested parent categories of a doc page
  // 3...
  //
  // Do _not_ use Infinity, the value must be a JSON-serializable integer.
  indexDocSidebarParentCategories : 0 ,

  // Includes parent categories path in search result
  includeParentCategoriesInPageTitle : false ,

  // whether to index blog pages
  indexBlog : true ,

  // whether to index static pages
  // /404.html is never indexed
  indexPages : false ,

  // language of your documentation, see next section
  language : "en" ,

  // setting this to "none" will prevent the default CSS to be included. The default CSS
  // comes from autocomplete-theme-classic, which you can read more about here:
  // https://www.algolia.com/doc/ui-libraries/autocomplete/api-reference/autocomplete-theme-classic/
  // When you want to overwrite CSS variables defined by the default theme, make sure to suffix your
  // overwrites with `!important`, because they might otherwise not be applied as expected. See the
  // following comment for more information: https://github.com/cmfcmf/docusaurus-search-local/issues/107#issuecomment-1119831938.
  style : undefined ,

  // The maximum number of search results shown to the user. This does _not_ affect performance of
  // searches, but simply does not display additional search results that have been found.
  maxSearchResults : 8 ,

  // lunr.js-specific settings
  lunr : {
    // When indexing your documents, their content is split into "tokens".
    // Text entered into the search box is also tokenized.
    // This setting configures the separator used to determine where to split the text into tokens.
    // By default, it splits the text at whitespace and dashes.
    //
    // Note: Does not work for "ja" and "th" languages, since these use a different tokenizer.
    tokenizerSeparator : / [s-]+ / ,
    // https://lunrjs.com/guides/customising.html#similarity-tuning
    //
    // This parameter controls the importance given to the length of a document and its fields. This
    // value must be between 0 and 1, and by default it has a value of 0.75. Reducing this value
    // reduces the effect of different length documents on a term’s importance to that document.
    b : 0.75 ,
    // This controls how quickly the boost given by a common word reaches saturation. Increasing it
    // will slow down the rate of saturation and lower values result in quicker saturation. The
    // default value is 1.2. If the collection of documents being indexed have high occurrences
    // of words that are not covered by a stop word filter, these words can quickly dominate any
    // similarity calculation. In these cases, this value can be reduced to get more balanced results.
    k1 : 1.2 ,
    // By default, we rank pages where the search term appears in the title higher than pages where
    // the search term appears in just the text. This is done by "boosting" title matches with a
    // higher value than content matches. The concrete boosting behavior can be controlled by changing
    // the following settings.
    titleBoost : 5 ,
    contentBoost : 1 ,
    tagsBoost : 3 ,
    parentCategoriesBoost : 2 , // Only used when indexDocSidebarParentCategories > 0
  }
}

يمكنك الآن استخدام شريط البحث للبحث في وثائقك.

هام: يعمل البحث فقط مع الوثائق التي تم إنشاؤها بشكل ثابت (على سبيل المثال، بعد تشغيل npm run docusaurus build في مجلد الوثائق الخاص بك).

البحث لا يعمل أثناء التطوير (أي عند تشغيل npm run docusaurus start ). إذا كنت ترغب في اختبار البحث محليًا، فقم أولاً ببناء الوثائق باستخدام npm run docusaurus build ، ثم قم بتقديمها عبر npm run docusaurus serve .

وثائق غير الإنجليزية

استخدم خيار language إذا لم تكن وثائقك مكتوبة باللغة الإنجليزية. يمكنك إما تحديد لغة واحدة أو مجموعة من اللغات المتعددة. اللغات التالية متوفرة:

 ar, da, de, en, es, fi, fr, hi, hu, it, ja, nl, no, pt, ro, ru, sv, th, tr, vi, zh

هام: لدعم اللغة الصينية ( zh )، يتعين عليك أيضًا تثبيت حزمة nodejieba npm على ^2.5.0 || ^3.0.0 .

إصدارات التوثيق

يتم دعم إصدارات التوثيق التي تم إنشاؤها باستخدام البرنامج الإضافي الرسمي لمستندات Docusaurus. يتم تعيين شريط البحث افتراضيًا على أحدث إصدار (ليس next ، ولكن أحدث إصدار محدد في versions.json ) عندما لا يكون موجودًا في صفحة التوثيق (على سبيل المثال، عند النظر إلى منشور مدونة أو صفحة ثابتة). إذا قام المستخدم بزيارة صفحة التوثيق، فسيتم استخراج الإصدار من الصفحة وسيبحث البحث فقط في وثائق هذا الإصدار. يعكس نص العنصر النائب لشريط البحث دائمًا إصدار الوثائق المكتشف حاليًا.

تدويل

يدعم هذا البرنامج الإضافي التوثيق باستخدام Docusaurus i18n خارج الصندوق. يرجى المساهمة بترجمات إضافية عن طريق إنشاء ملف ترجمة جديد في المجلد الفرعي codeTranslations وإرسال العلاقات العامة.

يمكنك أيضًا ضبط الترجمات عن طريق تعديل الترجمات الموجودة في <yourfolder>/i18n/<locale>/code.json التي تبدأ بـ cmfcmf/dsl. . اقرأ المزيد على: https://docusaurus.io/docs/i18n/tutorial#translate-json-files

تصحيح الأخطاء

إذا أدى إنشاء الوثائق الخاصة بك إلى حدوث خطأ، فيمكنك إنشائها في وضع التصحيح لمعرفة الصفحة التي تسبب ذلك. للقيام بذلك، ما عليك سوى تعيين متغير البيئة DEBUG عند إنشاء الوثائق الخاصة بك: DEBUG=1 npm run docusaurus build .

المساهمة

الرجاء مراجعة ملف CONTRIBUTING.md للحصول على مزيد من المعلومات.

رخصة

معهد ماساتشوستس للتكنولوجيا