Как спарсить документацию без headless-браузера: три рабочих способа

В форумах по скрапингу каждые несколько дней появляется один и тот же вопрос: «Собираю тексты документации для AI-инструмента, но страницы рендерятся через JavaScript. Как проще всего получить контент?»

Совет обычно один: открыть DevTools, зайти в Network, найти XHR. По сути это правильно. Но для сайтов документации — почти всегда лишняя работа.

Документация — не обычные веб-приложения. Её делают в основном статические генераторы, а те оставляют контент в предсказуемых местах. Три маршрута закрывают почти все случаи, и ни один не требует браузера.

Маршрут 1: JSON уже есть в HTML

Сайты на Next.js (а это заметная часть корпоративных девпорталов) кладут весь payload страницы в тег __NEXT_DATA__. Он находится прямо в исходном HTML-ответе — JavaScript исполнять не нужно.

Docusaurus, второй по популярности генератор, работает иначе: полный текст статьи попадает в статический HTML. Обычный GET-запрос плюс выборка узла main или article дают весь контент. То, что вы видите в браузере как «JavaScript-рендеринг» — это гидратация для навигации и поиска. Проза уже была в ответе сервера с самого начала.

Быстрая проверка занимает тридцать секунд. Возьмите предложение, которое видно на странице, и выполните:

curl -s <url> | grep -c "предложение со страницы"

Если результат 1 или больше — контент в HTML, и дело закрыто. Одна эта проверка решает большинство «JavaScript-rendered» случаев. Люди часто судят по вкладке Elements в DevTools, а она показывает уже гидратированный DOM, а не то, что реально отправил сервер.

Маршрут 2: маркдаун лежит в публичном репозитории

Документация опенсорсных проектов — это markdown в том же репозитории, обычно в папке docs/. Скрейпить отрендеренные страницы означает качать их по одной, парсить и вычищать навигацию, которая не нужна. Клонирование даёт чистый исходник одним запросом.

Для экономии трафика используется sparse checkout:

git clone --depth 1 --filter=blob:none --sparse https://github.com/org/project
cd project && git sparse-checkout set docs

Получаете оригинальный маркдаун: заголовки на месте, код в блоках, никаких боковых меню, баннеров с куками и ограничений на количество запросов. Для RAG-пайплайна это строго лучший вход, чем распарсенный HTML: один запрос вместо нескольких сотен.

Отдельно про лицензию. Документацию часто лицензируют отдельно от кода, и «репозиторий публичный» не равно «можно распространять». Проверьте лицензию до того, как начнёте встраивать текст куда-либо.

Маршрут 3: сайт публикует текстовый эндпоинт

Всё больше хостингов документации отдают plain-text версии. Пара запросов — и можно не изобретать паука.

• /llms.txt — новая, но быстро распространяющаяся конвенция: сайт публикует курируемую текстовую карту себя для LLM. Несколько запросов, и часто это всё, что нужно.
• /sitemap.xml — не текст, но полный список URL без обхода сайта. Так вы не пропустите страницы, до которых не добрались бы переходами по ссылкам.
• ReadTheDocs и похожие платформы обычно дают скачать готовые HTML или PDF/ePub сборки из меню версий. Один артефакт — весь контент.

Как выбрать маршрут за минуту

Когда браузер действительно нужен

Есть случаи, где без него не обойтись. Не применяйте маршруты выше, если:

• документация за авторизацией, а сессия устанавливается клиентским JavaScript;
• контент собирается из нескольких API-вызовов в рантайме и не лежит в одном payload — это бывает в интерактивных API-эксплорерах, но редко в обычной прозе;
• сайт перед выдачей контента гоняет через JS-челлендж, и это его основная защита.

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

Что на самом деле стоит денег

Дело не в принципиальности. Headless-браузер меняет форму проекта. Вместо скрипта, который запускается где угодно, вы получаете пайплайн с бинарником браузера, потолком по памяти, затратами на запуск каждой страницы и новым классом флаки-ошибок, которые воспроизводятся только иногда.

На нескольких сотнях страниц документации маршруты 1 и 2 обычно завершаются раньше, чем браузерный запуск успевает доехать до первой страницы. Сначала проверьте, не лежит ли контент в открытом виде. В большинстве случаев — лежит.