Vercel Docs в Markdown: как это ускорит работу ИИ-агентов и CLI-инструментов

Vercel объявил о нововведении: страницы документации теперь поддерживают ответы в формате Markdown. Чтобы получить документацию в этом формате, достаточно отправить HTTP-запрос с заголовком Accept: text/markdown. Это изменение делает контент docs доступным для агентных и CLI-рабочих процессов, пайплайнов индексации и любых инструментов, ожидающих text/markdown. Раньше разработчикам приходилось парсить HTML, чтобы извлечь информацию, что замедляло работу автоматизированных систем. Теперь же можно напрямую получать чистый структурированный текст, который легко обрабатывается как человеком, так и машиной.

Как это работает и зачем нужно

Ранее документация Vercel была доступна только в HTML-формате, что усложняло её программное использование. Теперь, указав заголовок Accept: text/markdown, вы получаете чистый Markdown-код страницы — без лишней разметки, стилей и скриптов. Это особенно полезно для ИИ-агентов, которые могут напрямую обрабатывать Markdown, для скриптов командной строки, которые парсят документацию, и для систем индексации, которым нужен структурированный текст.

Каждый Markdown-ответ включает ссылку на sitemap.md в конце. Эта карта сайта позволяет как человеку, так и агенту программно обнаруживать другие страницы документации, переходя по ссылкам последовательно. Таким образом, можно автоматически обойти все разделы docs, не загружая HTML и не парся DOM-дерево. Это экономит время и ресурсы, особенно при массовом сборе документации.

Какие преимущества это даёт ИИ-агентам?

ИИ-агенты, такие как GitHub Copilot, Cursor или Claude, часто нуждаются в актуальной документации для генерации точных ответов. Раньше им приходилось извлекать текст из HTML, что могло приводить к ошибкам и излишней нагрузке. Теперь агент может просто запросить Markdown-версию страницы и сразу получить чистый контент. Это ускоряет обучение моделей и повышает качество их ответов. Например, агент, помогающий с деплоем на Vercel, может быстро найти нужную команду или параметр, не отвлекаясь на лишние элементы интерфейса.

Предыстория и контекст

Vercel — платформа для развёртывания фронтенд-проектов, известная своим фокусом на developer experience. Компания постоянно улучшает документацию: ранее она внедрила поиск на основе ИИ и интерактивные примеры. Однако с ростом популярности ИИ-агентов и CLI-инструментов возникла потребность в машинно-читаемом формате. HTML сложен для парсинга агентами, а Markdown — универсальный и лёгкий формат, который поддерживается почти всеми современными LLM и инструментами.

Этот шаг Vercel следует тренду: всё больше компаний (включая Stripe, GitHub, Notion) предлагают документацию в Markdown или JSON для улучшения интеграции с автоматизированными системами. Vercel идёт дальше, добавляя sitemap.md — механизм для программного обхода, что делает их docs действительно доступными для агентов без дополнительной настройки. Это особенно важно для экосистемы, где скорость и точность имеют решающее значение.

Как это использовать на практике

Чтобы получить Markdown-версию страницы, выполните простой curl-запрос:

curl -H "Accept: text/markdown" https://vercel.com/docs

В ответ придёт Markdown-содержимое главной страницы документации. Для получения sitemap.md достаточно запросить https://vercel.com/sitemap.md — он содержит ссылки на все страницы docs. Агент может последовательно переходить по этим ссылкам, каждый раз указывая заголовок Accept, и собрать полную документацию.

Ограничение: формат поддерживается только для страниц документации (/docs/). Другие разделы сайта (блог, changelog) пока не возвращают Markdown. Также стоит учитывать, что Markdown-версия может не включать интерактивные элементы (например, встроенные песочницы кода), но основной текстовый контент и примеры кода сохраняются. Для большинства сценариев этого более чем достаточно.

Технические подробности

С технической стороны Vercel, вероятно, использует middleware на Edge или Serverless Functions, которые проверяют заголовок Accept и рендерят страницу в Markdown. Это может быть реализовано через преобразование HTML в Markdown на лету или через хранение Markdown-версий в кеше. Поддержка sitemap.md предполагает генерацию статического файла при сборке документации.

Для разработчиков, которые хотят интегрировать эту возможность в свои инструменты, достаточно добавить поддержку заголовка Accept: text/markdown в HTTP-клиент. Библиотеки вроде axios, fetch, httpx позволяют легко это сделать. Для ИИ-агентов на базе LangChain или LlamaIndex можно создать инструмент, который загружает документацию через этот эндпоинт и передаёт агенту. Это открывает широкие возможности для автоматизации.

Какие инструменты выиграют больше всего?

CLI-инструменты, такие как curl или wget, теперь могут напрямую получать документацию в читаемом виде. Это упрощает написание скриптов, которые проверяют актуальность документации или извлекают конкретные разделы. Например, можно автоматически обновлять локальную базу знаний, просто запуская curl по sitemap. Для ИИ-агентов это означает более быструю и точную индексацию, что критично для реального времени.

Кого затронет и как

Нововведение в первую очередь полезно разработчикам, создающим ИИ-агентов для помощи в работе с Vercel. Например, агент, который помогает деплоить проекты, может самостоятельно изучить документацию по нужным темам. Также это упрощает жизнь командам, которые автоматизируют сбор документации для офлайн-использования или для корпоративных баз знаний.

Для бизнеса, использующего Vercel, это означает более быструю интеграцию новых сотрудников: они могут задавать вопросы ИИ-агенту, который обучен на Markdown-документации. Для самой Vercel это снижает нагрузку на поддержку, так как разработчики получают точные ответы из первоисточника. Российским разработчикам, работающим с Vercel (несмотря на возможные ограничения), это также пригодится: можно создать локального агента, который загружает документацию и отвечает на вопросы без постоянного обращения к сайту.

Что будет дальше

Vercel, вероятно, расширит поддержку Markdown на другие разделы сайта, такие как блог и changelog. Также возможно появление JSON-формата для структурированных данных. В будущем мы можем увидеть официальный API документации с возможностью фильтрации по версиям и продуктам. Этот шаг задаёт тренд: платформы, ориентированные на разработчиков, будут всё активнее внедрять машинно-читаемые форматы для интеграции с ИИ. Vercel показала пример, который, скорее всего, подхватят другие компании.

Итог

Новая возможность Vercel Docs — значимое улучшение для разработчиков, работающих с ИИ-агентами и автоматизацией. Markdown-формат и sitemap.md делают документацию программно доступной, упрощая создание умных инструментов. Следите за обновлениями: это только начало пути к полностью агентной документации.