Проблема, которую все игнорируют
Вы решили построить RAG-систему для внутренней документации. Взяли LangChain, подняли векторную базу, настроили эмбеддинги. Осталось только загрузить данные из Confluence — и тут начинается ад.
Экспорт из Confluence — это zip-архив с кучей XML, HTML, JSON и бинарных вложений. Разбирать это руками — всё равно что перекладывать библиотеку книг по одной странице. А если у вас 5000 страниц? Месяц работы. Полгода.
Средний разработчик тратит 40 часов на написание парсера для Confluence. И ещё 20 — на его отладку. И ещё 10 — на обработку исключений, которые вылезают на реальных данных.
Что делает confluence2md
Открытый инструмент, который берёт этот самый экспорт Confluence (формат ZIP) и превращает его в чистый Markdown. Весь процесс выглядит так:
- Распаковывает архив
- Парсит XML с метаданными
- Конвертирует HTML-контент через pandoc
- Сохраняет иерархию пространств и страниц
- Генерирует структурированные Markdown-файлы
Инструмент написан на Python, работает из командной строки. Никаких GUI, никаких веб-интерфейсов — только конвейерная обработка.
Чем он лучше самописных решений
Я видел десятки самописных парсеров Confluence. Все они страдают одинаковыми болезнями:
- Ломаются на вложенных таблицах
- Теряют изображения
- Не обрабатывают макросы (типа JIRA-виджетов)
- Падают на битых символах в старых экспортах
Confluence2md проходит через pandoc — проверенный конвертер документов. Это не самописный парсер HTML регулярками (да, я видел и такое), а использование профессионального инструмента.
Ещё один момент: batch-обработка. Можно скормить инструменту десятки архивов — он обработает их последовательно. Для корпоративных развёртываний, где Confluence-инстансов несколько, это экономит часы.
Как это работает в RAG-пайплайне
Представьте, что вы строите поисковик, который обновляется сам. Confluence2md становится первым звеном в цепочке:
- Еженедельный экспорт из Confluence (автоматически)
- Запуск confluence2md для конвертации
- Чанкинг Markdown-файлов
- Генерация эмбеддингов
- Загрузка в векторную базу
Весь процесс можно автоматизировать через cron или CI/CD. Никакого ручного вмешательства.
Если вы используете Kreuzberg для обработки документов, confluence2md станет идеальным препроцессором. Сначала конвертируем Confluence в Markdown, затем применяем Kreuzberg для продвинутой очистки и чанкинга.
Важный нюанс: confluence2md не занимается чанкингом. Он только конвертирует. Для разбивки на чанки понадобится отдельный инструмент — например, LangChain или собственная реализация.
Альтернативы, которые не работают
Попробуйте поискать "Confluence to Markdown" — найдёте кучу плагинов для самого Confluence. Они работают по одной странице. Для 5000 страниц нужно 5000 кликов. Не вариант.
Есть онлайн-конвертеры, которые просят загрузить HTML-файл. Но в экспорте Confluence HTML-файлов сотни, и они связаны между собой. Онлайн-инструменты с этим не справляются.
Некоторые пытаются использовать BeautifulSoup напрямую. Это работает, пока не наткнёшься на:
- MIME-вложения (файлы в Base64 прямо в HTML)
- Динамические макросы
- Стили Confluence, которые ломают разметку
- Ссылки на другие страницы через pageId вместо human-readable URL
Confluence2md решает эти проблемы через промежуточную конвертацию в чистый HTML перед подачей в pandoc.
Интеграция с существующими пайплайнами
Допустим, у вас уже есть Skill Seekers для создания RAG-навыков. Confluence2md становится источником данных. Экспорт из Confluence → Markdown → Skill Seekers → готовая RAG-система.
Или вы работаете с Context7 MCP для Claude. Markdown из confluence2md идеально подходит для семантического поиска — чистый текст без лишней разметки.
Даже если вы строите гибридный поиск с BM25 и FAISS, confluence2md даст вам текстовый корпус для индексации. BM25 работает с чистым текстом — чем чище, тем лучше результаты.
Ограничения, которые стоит знать
Инструмент не идеален. Вот что он НЕ делает:
- Не обновляет данные в реальном времени (только batch-обработка экспортов)
- Не работает с живым Confluence API (только с экспортами)
- Не сохраняет сложные макросы (типа диаграмм или интерактивных виджетов)
- Требует установленного pandoc в системе
Последний пункт — главная боль. Pandoc — тяжёлая зависимость. На сервере CI/CD это может добавить лишний гигабайт к образу Docker. Но альтернативы нет — именно pandoc даёт качественную конвертацию.
Кому подойдёт этот инструмент
Если вы:
- Строите RAG для внутренней документации
- Имеете доступ к экспортам Confluence (админ или через API)
- Работаете с большими объёмами данных (сотни или тысячи страниц)
- Хотите автоматизировать подготовку данных
То confluence2md сэкономит вам недели работы.
Если же у вас 10 страниц в Confluence — возможно, проще скопировать их вручную. Но кто хранит в Confluence 10 страниц? Правильно, никто.
Что дальше
Инструмент решает конкретную проблему — и делает это хорошо. Но это только начало цепочки обработки данных для RAG.
После конвертации в Markdown вам понадобится:
- Чанкинг с учётом структуры документов
- Очистка от шаблонного текста ("Последнее изменение:...")
- Извлечение метаданных (автор, дата, теги)
- Построение графа связей между документами
Для этих задач посмотрите Ragex для семантического поиска или специализированные библиотеки обработки документов.
Главное — не застрять на этапе "как вытащить данные из Confluence". Confluence2md решает эту проблему раз и навсегда. Остальное — уже интереснее.
P.S. Если вы до сих пор копируете Confluence-страницы вручную — остановитесь. Потратьте час на настройку confluence2md, и забудьте об этой рутине. Ваше время стоит дороже.
