Поиск по документации

Зачем это нужно

Документация, в которой больше 20 страниц, перестаёт полноценно
«читаться». Люди вместо чтения ищут ответы: «где у нас про
аутентификацию?», «в какой странице описан процесс релиза?», «есть
у нас что-то про rate limiting?».

Быстрый и точный поиск — критично важная инфраструктура документации.
Если поиск медленный или не находит очевидного — команда
отказывается от wiki и возвращается к «спросить в Slack». Задача
Nextdocs — чтобы поиск всегда работал.

Как открыть

Cmd/Ctrl+K из любого места приложения — самый быстрый способ.
Кнопка Search and Chat в правом сайдбаре редактора.
Любая ссылка с хэштегом #search=… в URL — сразу откроет панель с
заданным запросом (для шаринга поисков).

Панель открывается как модалка поверх приложения: по центру
сверху — строка ввода, ниже — список результатов. Фокус
автоматически на строке поиска, начинаете печатать сразу.

Как пишется запрос

Простые слова

Пишете любые слова — поиск находит страницы, где они встречаются.
Порядок и регистр не важны.

auth flow

Найдёт страницы, где упоминаются оба слова (не обязательно подряд).

Точная фраза

Кавычки — ищет точное совпадение.

"JWT rotation"

Вернёт только страницы, где эти слова стоят именно в таком
порядке.

Смешанный запрос

Совмещать можно: обязательная фраза плюс любые слова.

"JWT rotation" security

Сначала результаты с точной фразой «JWT rotation» — выше, потом те,
где дополнительно встречается security.

Фильтры по типу контента

Над списком результатов — ряд кнопок-фильтров:

Text — обычные абзацы, заголовки, списки.
Code — блоки кода. Если ищете имя функции / переменной —
часто полезнее фильтр только по code.
Table — содержимое таблиц.
Image — страницы с изображениями (по alt-тексту / подписям).
Canvas — диаграммы TLDraw, Excalidraw, Mermaid (по тексту
внутри них — меткам, подписям узлов, названиям фигур).
Tasks — пункты чек-листов.

Клик по фильтру показывает только соответствующий тип. Удобно,
когда в проекте и документация, и код, и много таблиц.

Как устроено ранжирование

Nextdocs использует гибрид BM25 (классический полнотекстовый ранк)
и семантический поиск (близость по смыслу). Влияние на
выдачу:

Совпадение в заголовке страницы поднимает её выше.
Совпадение в первых строках (вводный абзац) тоже даёт буст.
Близость слов друг к другу в тексте — лучше разбросанных.
Точные фразы в кавычках — жёстко обязательны.
Семантическая близость — работает даже если слова не совпали:
запрос refresh token найдёт страницу про access token rotation,
даже если там нет слова «refresh».

Что видно в результатах

Результаты сгруппированы по страницам:

Заголовок страницы и путь (проект / родительская страница).
Сворачиваемый блок с найденными фрагментами: 1-3 фрагмента на
страницу, с контекстом и подсветкой.
В code-блоках сохраняется подсветка синтаксиса.
В canvas-фрагментах подсвечивается текст внутри схем.
Иконка-стрелка «Go to» — открывает страницу и скроллит прямо к
найденному месту.

Scope поиска

Поиск всегда работает в рамках проектов, к которым у вас есть
доступ:

На странице проекта — по умолчанию только в этом проекте.
Переключатель «All projects» в верху панели расширяет scope на
все ваши проекты.
На экране /projects — по умолчанию сразу по всем.
В приватный проект, куда вас не звали, попасть через поиск
нельзя: такие результаты отсекаются на этапе индекса.

Если проект публичный — его страницы найдутся через внутренний
поиск для всех (включая незалогиненных), и через Google / Яндекс
(см. раздел про SEO в Projects).

Горячие клавиши в панели

Клавиша	Действие
`↑` / `↓`	Переключение между результатами
`Enter`	Открыть выделенный результат
`Cmd/Ctrl+Enter`	Открыть в новой вкладке
`Esc`	Закрыть поиск
`Tab`	Переключить фильтр contentType

Что попадает в индекс

Текст страниц (заголовки, абзацы, списки, цитаты).
Код-блоки с языком. Подсветка сохраняется в рендере.
Текст в таблицах.
Надписи внутри диаграмм (Mermaid source, labels в TLDraw /
Excalidraw).
Alt-текст и подписи изображений.
Название и метаданные страницы.

Не индексируется:

Сырые комментарии (есть отдельный поиск по комментариям — TBD).
Исходники репозиториев — они индексируются отдельно и
подключаются через AI-агент, а не полнотекстовый поиск (см.
AI Agent).

Задержка индексации

Когда вы что-то поменяли — индекс обновляется асинхронно:

Нормальное время — 1-3 минуты после сохранения.
Если попали в пик загрузки системы — до 5 минут.
Если результат не появляется через 10 минут — что-то сломалось,
напишите в поддержку.

Шаринг поисков

Если вы хотите поделиться конкретным запросом — скопируйте URL из
адресной строки, когда поиск открыт:

https://nextdocs.ai/#search=refresh%20token&project=42

Тот, кому вы её отправите (если у него есть доступ к указанным
проектам), увидит ровно те же результаты, что и вы.

Типовые сценарии

Ищете: «где у нас описание переменных окружения?»
env variables → результаты, в заголовках находится «Environment
variables configuration». Open.

Ищете: «какую базу мы используем для биллинга?»
billing database → семантический поиск подтягивает страницу
«Billing architecture», где упоминается PostgreSQL, даже если в
запросе слова «PostgreSQL» не было.

Ищете конкретную функцию в коде
handleUserRegistration + фильтр Code → все места в коде, где
функция определена / вызывается.

Ищете цитату, которую точно помните
"we decided to use redis pub/sub" → точная фраза. Если её нет
больше нигде в документации — вернётся одна страница.

Отличие от AI-агента

Полнотекстовый поиск отвечает на где: «найди мне страницы со
словами X». Быстро, предсказуемо, детерминированно, без LLM в
цепочке.

AI-агент отвечает на что: «объясни мне, как это устроено»
плюс умеет делать: создать страницу, обновить раздел,
переместить дерево. См. AI Agent.

Оба открываются по Cmd/Ctrl+K, переключаются одним кликом в
панели. На практике часто используют вместе: сначала быстрый
поиск, если его мало — переключение в agent-mode с уточнением.
Если нужно что-то изменить — сразу в agent.

Ограничения

Максимум 500 результатов на запрос (обычно хватает с запасом).
Поиск по не-русским/английским языкам — работает, но качество
морфологии ниже (не все языки имеют stemmer).
Не работает в офлайне (поиск делается запросом на бэкенд).
Поиск по архивным (удалённым 90+ дней назад) страницам —
невозможен.