docs: Search

.yfm

@@ -8,6 +8,8 @@ resources:
 translate:
   folder: b1gpieerntm5sa95psrk
 
+search: true
+
 docs-viewer:
   project-name: diplodoc
   langs: ['en','ru']

ru/changelog.md

@@ -1,3 +1,7 @@
+---
+noindex: true
+---
+
 # История изменений
 
 ## Декабрь 2022

ru/project/search.md

@@ -0,0 +1,77 @@
+---
+keywords:
+    - search
+    - lunr
+    - solr
+    - поиск
+---
+
+# Интеграция с поисковыми системами
+
+Чтобы включить в документации поддержку поисковой системы, нужно указать в настройках секцию `search`.
+После этого в интерфейсе в правом верхнем углу должен появиться элемент поиска.
+
+По умолчанию поддерживается локальный поиск, реализованный с помощью [lunrjs](https://lunrjs.com/)
+
+```yaml
+search:
+  provider: local
+```
+
+## Локальный поиск
+
+### Конфигурация
+
+```yaml
+search:
+  provider: local
+  toleranse: 2
+  confidense: phrased
+```
+
+#### confidense
+
+Переключает режим дополнительного ранжирования результатов поиска.
+
+`confidense: phrased` - значение по умолчанию. Дополнительно ранжирует результаты по длине найденной фразы.
+
+`confidense: sparsed` - Использует обычное ранжирование из LunrJS. Т.е. просто считает количество найденных в документе слов, не учитывая расстояние между ними.
+
+#### tolerance
+
+Переключает диапазон поискового запроса.
+
+`tolerance: 0` - Ищет точное совпадение слов.
+
+`tolerance: 1` - Если результатов `tolerance=0` недостаточно, ищет “хвостики”. т.е `word*`.
+
+`tolerance: 2` - (по умолчанию) Если результатов `tolerance=1` недостаточно, ищет “шапочкки” т.е `*word*`.
+
+### Архитектура
+
+LunrJS строит поисковый индекс при сборке документации и ищет по нему синхронно.
+Это накладывает на систему ряд ограничений:
+
+#### Объем
+
+Поисковый индекс может быть достаточно большим. В среднем он занимает в три раза больше места чем объем текстовой информации в индексируемых документах.
+
+При этом индекс заново инициализируется на каждой новой вкладке документации (в момент фокуса в элементе поиска).
+
+Это может негативно сказаться на объеме памяти, занимаемой браузером и на скорости инициализации результатов поиска.
+
+В случае если поисковый индекс превышает 100Mb, стоит подумать об интеграции с другой поисковой системой.
+
+Объем индекса можно посмотреть в директории собранной документации в разделе `_search/<lang>/index.js`.
+
+#### Синхронность
+
+Из-за того что LunrJS имеет синхронную реализацию, основная часть его логики вынесена в WebWorker.
+
+У WebWorker есть [ряд ограничений](https://stackoverflow.com/questions/21408510/chrome-cant-load-web-worker) по работе с файловой системой, если вы открываете документацию полностью локально (`file:///some-documentation`).
+
+Реализация в Diplodoc старается обойти эти ограничения, но не гарантирует, что в будущих политиках браузера все будет работать.
+
+### Проблемы
+
+О проблемах в локальном поиске стоит сообщать в [issues](https://github.com/diplodoc-platform/search-extension/issues) соответствующего проекта.

ru/toc.yaml

@@ -29,6 +29,9 @@ navigation:
       - text: "Github"
         type: "link"
         url: "https://github.com/diplodoc-platform/"
+    rightItems:
+      - type: search
+      - type: controls
 items:
   - name: Обзор системы
     href: about.md
@@ -84,6 +87,8 @@ items:
             href: project/navigation.md
           - name: Разводящая страница
             href: project/leading-page.md
+          - name: Поиск
+            href: project/search.md
           - name: Page constructor
             items:
               - name: Обзор
@@ -120,14 +125,15 @@ items:
                 href: tools/docs/build.md
               - name: Настройки сборки
                 href: tools/docs/settings.md
-              - name: Перевод
+              - name: Локализация
                 href: tools/docs/translate.md
               - name: Одностраничная сборка
                 href: tools/docs/singlepage.md
               - name: Выкладка на S3
                 href: tools/docs/publish-s3.md
           - name: Библиотека Mermaid
             href: tools/mermaid.md
+            hidden: true
       - name: Плагины
         items:
           - name: Обзор