Как конвертировать любой веб-сайт в Markdown (API и учебник)
TL;DR
Преобразование веб-сайта в Markdown начинается с ограниченного набора URL и проверки точности.
Одностраничный сканирование преобразует известный URL; POST /api/v1/crawl обнаруживает связанные страницы, когда область охвата — это раздел сайта.
Сравните заголовки, ссылки, код и таблицы с отображаемым исходным кодом перед сохранением Markdown для RAG.
Большие результаты Markdown могут возвращаться как markdownRef; получите этот токен через конечную точку хранения.
Nstdata Crawl обрабатывает рендеринг JavaScript и маршрутизацию прокси в управляемых запросах; его документация перечисляет шесть категорий вывода: Markdown, HTML, сырые данные, PDF, скриншоты и ссылки.
Что такое рабочий процесс преобразования веб-сайта в Markdown?
Рабочий процесс URL в Markdown извлекает страницу, выбирает полезный контент и сохраняет заголовки, ссылки, списки и код в тексте, который люди и модели могут проверять. Конвертер, применяемый только к загруженному HTML, не может восстановить контент, который был загружен позже с помощью JavaScript. Начните с одного представительного URL и определите, что должно остаться после преобразования, прежде чем обрабатывать целый сайт.
Nstdata Crawl может превратить URL или ограниченный набор связанных страниц в материалы для агента ИИ, индекса RAG или конвейера данных. Используйте свои собственные правила в области и проверки приемлемости для конкретного результата: превратите известную публичную страницу в точный Markdown для поиска, RAG или агента. Полное руководство по сканированию сайта Nstdata объясняет вариант на уровне сайта.
Для более узкой задачи, рассмотренной здесь, обзор URL в Markdown от Nstdata дает полезный контекст для выбора первой представительной страницы.
Выберите одну разрешенную страницу, содержащую заголовок, список, встроенную ссылку и, при необходимости, таблицу или блок кода. Запишите заголовок и две фразы, которые должны появиться. Сохраните исходный URL с результатом, чтобы позже ответ мог ссылаться на него. Храните API-ключ как NSTDATA_API_TOKEN; никогда не размещайте его в приложении на стороне клиента или в скриншоте.
Документация по API Crawl использует https://api.nstdata.io, заголовок x-api-key и Content-Type: application/json. Подготовьте эти поля перед запуском метода:
Поле
Что предоставить
url
Один разрешенный HTTPS URL страницы или сайта
formats
Запрашиваемые выходные данные, такие как ["markdown"] или ["html","screenshot"]
onlyMainContent
true, только если выбор основного контента соответствует задаче
maxDepth, maxPages
Явные границы для задачи на уровне всего сайта
includeUrls, excludeUrls
Шаблоны URL, которые удерживают обнаружение в пределах области
timeout
Таймаут задачи в миллисекундах, когда по умолчанию это не подходит
Стандартный управляемый запрос не имеет отдельных полей для прокси-хоста, порта, имени пользователя, пароля или протокола. Проверьте текущую страницу цен на Crawl для ограничений и сборов учетной записи перед запуском крупной задачи.
Проверьте политику доступа и область цели. Протокол исключения для роботов определяет, как краулеры читают правила для роботов; он не предоставляет прав на использование контента. Держите учетные данные и личные данные вне примеров и диагностических журналов.
Nstdata Crawl извлекает и рендерит URL, применяет извлечение контента и возвращает Markdown с метаданными страницы. API также может возвращать HTML, ссылки, скриншоты и PDF, когда Markdown нуждается в исследовании. Встроенная маршрутизация прокси означает, что по умолчанию запросу нужны API-ключ и целевой URL, а не отдельные поля прокси-хоста, порта, имени пользователя или пароля. Работа на уровне сайта может обнаруживать связанные страницы, когда задача расширяется за пределы одного URL.
Для известного URL одностраничное сканирование извлекает один результат. Для раздела сайта POST /api/v1/crawl рекурсивно обнаруживает связанные страницы в пределах заданной глубины, количества страниц и правил URL. Документация перечисляет Markdown, HTML, сырые данные, PDF, скриншоты и ссылки как шесть категорий вывода; страница продукта также предлагает JSON, но схема JSON для конкретной области все еще требует явного сопоставления полей. Держите каждую принятую запись связанной с ее исходным URL и возвращенными метаданными.
Протестируйте страницу с активным JavaScript перед масштабированием. Отрендеренное состояние может зависеть от времени, региона, согласия или авторизованной сессии. Сравните возвращённый HTML или скриншот с ожидаемым состоянием страницы; если они отличаются, скорректируйте только задокументированные элементы рендеринга и элементы ожидания.
Как преобразовать веб-сайт в Markdown?
Начните с визуальной проверки одной страницы, используйте синхронный API для повторяемого преобразования URL или отправьте ограниченный обход сайта для связанной документации. Каждый путь имеет разный масштаб и форму результата.
Метод 1: Используйте Crawl Playground для визуальной проверки
Лучше всего подходит для первой представительной страницы или для неразработчика-ревьюера.
Шаг 1: Откройте тестирование страницы
Войдите в систему и откройте Dashboard → Crawl Playground. Выберите сканирование одной страницы и введите разрешённый URL. [Скриншот: поле URL Playground и режим одной страницы.]
Шаг 2: Выберите выходные данные
Выберите Markdown и включите опцию основного контента, когда тело статьи имеет большее значение, чем навигация. Если цель динамическая, используйте элементы рендеринга или ожидания, показанные в текущем интерфейсе. [Скриншот: элементы управления Markdown и контентом.]
Шаг 3: Проверьте точность
Запустите сканирование и сравните результат с живой страницей. Проверьте заголовок, открывающие и закрывающие разделы, блоки кода, таблицы и назначения ссылок. Короткий ответ все еще может быть неправильным, если он не содержит предупреждения или таблицы.
Метод 2: Вызовите API Crawl для одной страницы
Лучше всего подходит для приложения, которое получает известный URL во время выполнения.
Шаг 1: Подготовьте учетные данные
Сохраните ключ API Crawl в секретном хранилище на стороне сервера. Задокументированный заголовок — x-api-key; ключ не является паролем прокси.
Шаг 2: Отправьте URL
Используйте запрос быстрого старта ниже. Текущая документация имеет противоречивые метки для других синхронных и асинхронных маршрутов сканирования, поэтому сравните этот маршрут с запросом, сгенерированным вашим Playground перед размещением.
Установите NSTDATA_API_TOKEN в вашем терминале из вашего аккаунта Nstdata, затем выполните задокументированный запрос быстрого старта. Публичная документация неправильно помечает некоторые другие синхронные и асинхронные маршруты; сравните запрос, сгенерированный Playground вашего аккаунта, перед производственным использованием.
curl--output crawl-response.json --request POST "https://api.nstdata.io/api/v1/crawl/scrape/submit-sync"\--header"x-api-key: ${NSTDATA_API_TOKEN}"\--header"Content-Type: application/json"\--data'{"url":"https://example.com/","formats":["markdown"],"onlyMainContent":true}'
Ответ сохраняется в crawl-response.json. Проверьте вложенные поля data.success, data.status и data.data.metadata.statusCode перед использованием любого возвращённого контента.
Шаг 3: Примите результат
Проверьте вложенные значения success, status, data и metadata.statusCode. Принимайте Markdown только в том случае, если присутствуют ожидаемые заголовки и значимый текст тела; сохраните markdownRef и получите его через задокументированный маршрут хранения, когда API возвращает ссылку.
Метод 3: Преобразуйте ограниченный раздел сайта
Лучше всего, когда "веб-сайт" означает набор документации, а не один URL.
Шаг 1: Определите раздел
Выберите начальный URL и установите maxDepth, maxPages, а также включите/исключите шаблоны URL. Исключите пути поиска, учетных записей, корзину и сгенерированные запросом URL, если они не принадлежат вашему корпусу.
Шаг 2: Отправьте задание на сайте
Используйте задокументированный маршрут POST /api/v1/crawl с formats: ["markdown"], затем сохраните возвращённый ID обхода. Это маршрут для обнаружения сайтов; сканирование одной страницы не будет следовать за всем сайтом.
Для задания на сайте замените пример хоста и пути на ваше утвержденное поле, затем отправьте ограниченный запрос:
curl--output crawl-submit.json --request POST "https://api.nstdata.io/api/v1/crawl"\--header"x-api-key: ${NSTDATA_API_TOKEN}"\--header"Content-Type: application/json"\--data'{"url":"https://example.com/docs/","formats":["markdown"],"maxDepth":2,"maxPages":10,"includeUrls":["*example.com/docs/*"],"excludeUrls":["*example.com/admin/*"],"ignoreQuery":true}'
Скопируйте data.id из crawl-submit.json как ваш ID обхода.
Шаг 3: Просмотрите каждую страницу
Запрашивайте статус, получайте записи страниц, следуйте за пагинацией и отклоняйте неудачные или тонкие страницы. Удалите дубликаты нормализованных URL и сохраните оригинальный URL рядом с каждым документом Markdown.
С ID обхода, возвращённым в результате отправки, запросите как задание, так и его страницы:
Если ответ страниц содержит nextCursor, следуйте за ним, используя элементы управления пагинацией, показанные в вашем текущем ответе API или SDK; публичная страница не документирует параметр запроса курсора, поэтому не выдумывайте его.
Метод 4: Преобразуйте статический HTML локально с помощью Pandoc
Лучше всего подходит, когда у вас уже есть разрешённый статический HTML-файл и вам не нужно обнаружение сайта или рендеринг JavaScript.
Шаг 1: Сохраните статическую страницу
Скачайте авторизованную страницу как page.html, используя команду Сохранить страницу как вашего браузера или одобренный HTTP-клиент. Проверьте, что сохраненный файл содержит текст статьи; статическая загрузка может пропустить текст, загруженный с помощью JavaScript.
Откройте page.md и сравните заголовки, ссылки, таблицы и код с исходником. Этот локальный метод не имеет управляемого рендеринга, прокси-маршрутизации или рекурсивного обнаружения сайтов; используйте Crawl, когда необходимы эти возможности.
Как вы проверяете вывод?
Используемая запись содержит URL-адрес источника, заголовок, код состояния и Markdown, который сохраняет важную структуру. Markdown является текстовым представлением, а не доказательством семантической точности: сложные таблицы, диаграммы и виджеты на стороне клиента могут потребовать HTML или скриншот рядом с ним. Руководство по обработке Markdown Nstdata объясняет, как сохранить принадлежность при сохранении преобразованных страниц.
Запишите URL-адрес источника, время подачи, запрошенные форматы, не секретные опции, ID задачи, когда он присутствует, статус возвращенной страницы и причину, по которой каждая запись прошла или не прошла проверку. Проверьте содержимое, а также оболочку API. Если ответ содержит markdownRef, htmlRef, rawDataRef, screenshotRef или pdfRef, получите этот токен с помощью GET /api/v1/crawl/storage/read?st={ref}.
Синтаксис Markdown не является универсальной гарантией, что каждый рендерер обрабатывает таблицы и расширения идентично; протестируйте ваш парсер на стороне клиента с разделом спецификации CommonMark и любыми расширениями, которые вы используете.
При передаче извлеченного текста агенту, рассматривайте инструкции к странице как ненадежный исходный материал. Рекомендации OWASP по инъекции подсказок объясняют риск. Сохраняйте URL-адреса источников, чтобы результат ИИ мог быть проверен.
Почему может провалиться конвертация с сайта в Markdown?
Конвертация сайта в Markdown может провалиться, потому что основной текст страницы может загрузиться после начального документа или выбор основного контента может его исключать. Используйте таблицу симптомов, чтобы определить уровень сбоя перед изменением ограничений или повторной попыткой.
Симптом
Вероятная причина
Следующее действие
Пустой Markdown
Основной текст страницы может загрузиться после начального документа или выбор основного контента может его исключать.
Проверьте HTML или скриншот и настройте задокументированное ожидание.
Сломанные относительные ссылки
Конвертер или позже слой хранения могут не сохранить абсолютные адреса.
Разрешите и протестируйте исходные ссылки перед индексацией.
Возвращена только одна страница
Одностраничный конечный пункт не обнаруживает подстраницы.
Переключитесь на ограниченный обход сайта.
Документация Nstdata перечисляет ошибки на уровне задачи, такие как access_denied, timeout, parse_error и internal_error. Внешний HTTP 200 все равно может сопровождать неудачную задачу. Проверьте success, status, errorCode и errorMessage внутри ответа, если они есть. Повторяйте только временные ошибки на сайтах, к которым вы можете получить доступ.
Какой метод лучше всего подходит?
Выберите Playground для визуального одностраничного сравнения, синхронный API для известного URL или ограниченную работу с сайтом, когда необходимо следовать ссылкам. Используйте локальный Pandoc для статического HTML, который уже сохранен; сравните каждый принятый документ Markdown с его источником. Обзор обхода сайтов Nstdata предоставляет более подробную информацию о маршруте сайта.
Что делать после первой успешной попытки?
Сохраните одобренную конфигурацию и одну запись выхода на основе источника, затем повторите для небольшого набора различных шаблонов страниц. Расширяйте объем только после того, как эти записи пройдут те же проверки на приемку.
Q: Могу ли я конвертировать целый сайт за один запрос?
Ограниченный обход сайта может обнаружить и обработать несколько связанных страниц. Установите пределы страницы и глубины, затем проверьте возвращенные записи.
Q: Является ли Markdown всегда лучше, чем HTML для LLM?
Markdown обычно легче читать и делить на части, но HTML или скриншот безопаснее, когда важна структура таблицы или визуальный контекст.
Q: Нужен ли мне прокси-креденциал?
Стандартный управляемый запрос Crawl нуждается в ключе API Crawl, а не в отдельном прокси-хосте или пароле.
В: Требует ли конвертация веб-сайта в Markdown отдельной конфигурации прокси с Nstdata Crawl?
Стандартный управляемый запрос Crawl не требует отдельных полей Прокси-хоста, Порта, Имени пользователя, Пароля или Протокола. Подтвердите любой выбор необязательного пользовательского прокси и связанные с ним комиссии в вашем аккаунте.
В: Доказывает ли HTTP 200, что результат конвертации веб-сайта в Markdown является годным?
Нет. Проверьте результат вложенной задачи, статус страницы, ожидаемые поля и точность тела перед использованием в AI или рабочем процессе данных.
Этот учебник показывает, как обнаружить авторизованные URL-адреса из карт сайтов и превратить проверенный подмножество в ограниченное сканирование сайта. Он охватывает практические методы, проверки результатов и ограничения управляемого сканирования.
Kai Watanabe
Oct. 28th 2026
Начните Бесплатно Уже Сегодня
Сканируйте целые сайты одним API-запросом
Преобразуйте любой сайт в Markdown, HTML, JSON, ссылки, PDF и другие форматы без управления инфраструктурой сканирования.
