Дата публикации: 03:36:30 ().

В современных системах документации важно обеспечить пользователям гибкие и точные способы поиска информации. Одним из таких механизмов является точное совпадение поиска (exact match search), которое позволяет искать фразы, заключённые в двойные кавычки, без учёта частичных совпадений или stemming‑алгоритмов. В этой статье мы рассмотрим реализацию этой функции в популярной теме mkdocs-material, опираясь на информацию из открытого issues #1772 на GitHub.

Что такое точный поиск через двойные кавычки?

Точный поиск подразумевает, что запрос, заключённый в двойные кавычки ("..."), будет обработан как единая фраза, и система вернёт только те документы, в которых эта фраза встречается полностью и в том же порядке. Например:

• "экспериментальные данные" найдёт только страницы, где именно эта фраза присутствует.
• Без кавычек тот же запрос мог бы вернуть страницы, содержащие слова экспериментальные и данные в любом порядке или даже отдельно.

Данный подход особенно полезен при работе с технической документацией, где термины могут иметь несколько значений, а необходимость избежать ложных срабатываний критична.

История обсуждения в репозитории mkdocs-material

Идея добавить поддержку точного поиска через двойные кавычки была предложена в issue #1772 (опубликовано 22 июня 2020 г.). Автор отметил, что:

1. В официальной документации mkdocs-material отсутствует упоминание о такой возможности.
2. На его взгляд, реализация не должна ломать существующий функционал для остальных пользователей.
3. На момент создания issue не существовало открытых или закрытых задач, напрямую связанных с этим предложением.

Дискуссия в issue показала, что сообщество заинтересовано в данном улучшении, поскольку многие пользователи сталкивались с необходимостью искать точные фразы в больших наборах markdown‑файлов.

Техническая реализация

Для добавления точного поиска через двойные кавычки в mkdocs-material потребуется внести изменения в два основных компонента:

• Индексатор поиска – отвечает за построение индекса из содержимого документов.
• Поисковый движок – обрабатывает пользовательский запрос и возвращает результаты.

Изменения в индексаторе

В текущей реализации mkdocs-material используется библиотека lunr.js для полнотекстового поиска. Чтобы поддерживать фразы в кавычках, необходимо:

1. При индексации сохранять не только отдельные токены, но и биграммы (или n‑граммы) для быстрого определения последовательностей слов.
2. Добавить метаполе, указывающее позицию каждого токена в документе, чтобы можно было проверять смежность при поиске фразы.

Изменения в поисковом движке

Когда пользователь вводит запрос вида "фраза", движок должен:

1. Снять внешние кавычки и разбить внутреннюю строку на отдельные токены.
2. Для каждого токена получить список документов, где он встречается.
3. Пересечь эти списки, оставив только документы, содержащие все токены.
4. Для каждого оставшегося документа проверить, что токены идут подряд и в том же порядке (с учётом позиций, сохранённых в индексе).
5. Вернуть только те документы, где условие выполнено.

Если кавычки отсутствуют, поиск продолжает работать в обычном режиме (OR‑логика с учётом рейтинга).

Преимущества и возможные ограничения

Преимущества

• Повышение точности поиска – пользователи получают релевантные результаты без лишнего шума.
• Совместимость с существующими запросами – обычный поиск без кавычек остаётся неизменным.
• Минимальное влияние на производительность благодаря использованию уже существующих структур lunr.js.

Ограничения

• Увеличение размера индекса из‑за хранения позиционных данных (обычно незначительно для средних проектов).
• Сложность обработки языков без чёткой delimitации слов (например, китайский, японский) – может потребоваться дополнительная токенизация.
• Не поддерживает поиск по фразе с учётом stemming или синонимов – строгое соответствие.

Как протестировать функцию

После внесения изменений можно выполнить следующие шаги:

1. Собрать проект с обновлённой версией mkdocs-material.
2. Запустить локальный сервер: mkdocs serve.
3. В строке поиска ввести запрос в двойных кавычках, например "Allow exact match search".
4. Убедиться, что результаты содержат только те страницы, где эта фраза встречается полностью и в том же порядке.
5. Сравнить с результатами обычного поиска без кавычек, чтобы убедиться, что они шире.

Реализация точного поиска через двойные кавычки в mkdocs-material – это логичное и востребованное улучшение, которое делает работу с документацией более эффективной и предсказуемой. Обсуждение в issue #1772 показало явный интерес сообщества, а технические детали, описанные выше, демонстрируют, что добавление этой функции возможно без существенного ущерба для производительности или обратной совместимости.

Мы надеемся, что данная статья поможет разработчикам и техническим писателям понять, как внедрить и использовать эту возможность в своих проектах на базе MkDocs Material.

---

Автор статьи: помощник по технической документации. Дата: .