Confluence в Markdown: как выгрузить вики компании

Корпоративная вики в Confluence удобна для совместного чтения, но канон для разработки и ассистентов всё чаще нужен в Markdown: файлы в Git, сборка сайта, понятный дифф. Выгрузка ломается на макросах, правах пространств и «жирных» страницах с десятками вложений. Рабочий путь: сохранить страницу как HTML (или получить HTML-экспорт), убрать оболочку продукта и получить .md с заголовками и списками. На Тулси для сохранённой страницы — HTML → Markdown; для смешанных исходников — конвертер в Markdown. Как жить в docs после переноса: документация в Markdown. Сравнение сред: Markdown vs Word vs Google Docs. Разбор самого HTML-шага: HTML в Markdown. Ниже: подготовка пространства, выгрузка, чистка и проверка оглавления.

Зачем выносить вики из Confluence в Markdown

Confluence хорош как портал: поиск, комментарии, права на пространство. Репозиторий хорош как канон релиза: инструкция к версии продукта лежит рядом с кодом и меняется тем же процессом review.

Ассистенты и поисковые индексы проще кормить набором .md, чем деревом макросов. Выгрузка снижает риск, что единственная копия знаний живёт только за корпоративным логином.

Типичный триггер: команда уходит с облака Atlassian, режет лицензии или собирает внутренний портал документации на MkDocs. Нужен перенос смысла страниц, не пиксель-в-пиксель макросов.

Когда Confluence оставляют витриной

Иногда .md в Git — источник, а Confluence публикует собранный HTML или держит только «человеческую» витрину. Тогда выгрузка нужна один раз или редко, как снимок.

Если правки продолжают жить только в Confluence, Git быстро устареет. Договоритесь, где канон. Роли форматов: Markdown vs Word vs Google Docs.

Что не переносится «как было»

Макросы задач, диаграммы, виджеты Jira, сложные панели и кнопки станут текстом, картинкой или пустым местом. Цвета и темы пространства исчезнут. Это нормально для Markdown.

Таблицы иногда разъезжаются. Вложения нужно скачать отдельно и разложить в assets/. Права доступа в .md не копируются: доступ теперь даёт репозиторий и портал сборки.

Как выгрузить страницы практически

Выберите пространство или ветку оглавления. Начните с пилотного раздела из десяти–двадцати страниц, не со всего портала. Так отладите имена файлов и чистку HTML.

Сохраните страницу из браузера как HTML (полный или «только HTML» — сравните на пилоте) либо используйте доступный вам экспорт пространства. Цель — файл, где видно заголовки статьи, а не только оболочка Confluence.

Загрузите .html в HTML → Markdown. Скачайте .md. Если исходник уже в другом формате, откройте конвертер в Markdown. Пошаговые нюансы HTML-пути: HTML в Markdown.

Имена файлов и дерево глав

Переименуйте файлы латиницей, коротко, стабильно: install.md, auth-api.md. Пробелы и кириллица в путях мешают сборщикам и ссылкам. Сохраните карту «старый URL Confluence → новый путь», чтобы поправить закладки команды.

Вложенность пространств отразите папками в docs/. Одно пространство — один каталог, если так понятнее владельцам. Практика раскладки: документация в Markdown.

Вложения, рисунки, PDF внутри вики

Скачайте картинки и PDF с страниц пилота. Положите в docs/assets/. В Markdown поставьте относительные ссылки. Проверьте, что корпоративный CDN и «preview» Confluence не остались единственным источником файла.

Тяжёлые бинарники не обязательно тащить в Git: иногда достаточно полки файлового хранилища и ссылки из главы. Главное — не оставить битую картинку «на внутреннем URL», который без логина не откроется.

Чистка после конвертации

Удалите остатки навигации, «хлебных крошек», комментариев и скриптов, если они попали в HTML. В .md должны остаться заголовок, абзацы, списки, таблицы смысла, ссылки на другие главы.

Выровняйте уровни: один h1 на файл, дальше h2/h3. Макросы «info» и «warning» превратите в цитаты или явные абзацы «важно:». Не оставляйте пустые блоки от панелей.

Пройдите внутренние ссылки. Замените URL Confluence на относительные пути .md. Внешние ссылки оставьте, если они публичные.

Таблицы и код

Таблицы сверьте на число колонок. Кривые сетки проще поправить в редакторе, чем жить с разъехавшейся разметкой. Блоки кода оберните ограждениями и укажите язык, если он известен.

Если таблица — выгрузка из Jira или огромный реестр, держите CSV рядом, а в главе оставьте краткое описание. Markdown не обязан хранить тысячу строк учёта.

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

Соберите превью документации. Попросите владельца раздела прочитать одну главу целиком. Сверьте оглавление с исходным деревом Confluence. Только после этого масштабируйте выгрузку.

Секреты, токены и персональные данные вырежьте до публикации репозитория. Вики иногда хранит больше, чем «публичная инструкция».

Порядок миграции для команды

Назначьте владельца пространства и дедлайн пилота. Зафиксируйте канон: Git или Confluence. Опишите, кто имеет право менять главы после переноса.

Переносите пакеты по разделам. После каждого пакета — сборка и короткая приёмка. Не копируйте всё одним архивом в корень docs/ без карты ссылок.

Сообщите команде новые пути и как предлагать правки (pull request, а не «поправьте в старой вики»). Иначе правки продолжат оседать в Confluence.

Смежные материалы

HTML-страница в заметку: HTML в Markdown и инструмент HTML → Markdown. Смешанные файлы: конвертер в Markdown. Ведение docs: документация в Markdown. Выбор среды: Markdown vs Word vs Google Docs.

Выгрузка Confluence — частный случай перевода корпоративной вики в файловый канон. Держите одну правду и ясные ссылки между главами.

Частые вопросы

С чего начать выгрузку большой вики?

С пилотного раздела и карты «старая страница → новый файл». Так вы отладите HTML-чистку и имена. Массовый перенос без пилота размножает битые ссылки. Инструмент для страницы: HTML → Markdown.

Чем HTML-путь лучше «скопировать в Word и потом в MD»?

Лишний круг через Word добавляет стили и ломает заголовки. HTML ближе к структуре страницы вики. Если уже есть DOC — можно через конвертер в Markdown, но для Confluence логичнее HTML. Разбор: HTML в Markdown.

Перенесутся ли макросы Jira и диаграммы?

Как интерактив — нет. Останется текст, снимок или пустое место. Диаграммы экспортируйте в PNG и вложите вручную. Ссылки на задачи Jira оставьте URL, если они нужны читателю. Не ждите полного клона макросов в Markdown.

Как быть с правами доступа пространств?

В Git права задаёт репозиторий и группы компании. Секретные разделы не кладите в публичный docs без ревизии. Иногда секретные главы остаются в закрытой вики, а в Markdown уходит только продуктовая документация. Решите это до массового экспорта.

Нужен ли Confluence после миграции?

Только если вы сознательно оставляете витрину. Канон должен быть один. Иначе снова появятся две версии главы. Как выбирать среду: Markdown vs Word vs Google Docs.

Что делать с оглавлением пространства?

Соберите SUMMARY или конфиг MkDocs из списка файлов. Не надейтесь, что автоматический HTML сохранит меню Confluence идеально. Сверка с деревом пространства — ручной шаг владельца. Образец раскладки: документация в Markdown.

Можно ли автоматизировать сотни страниц скриптом?

Да, но чистку шаблона и ссылок всё равно закладывайте. Скрипт ускоряет скачивание и конвертацию. Приёмку глав не отменяйте. На Тулси удобно прогонять отдельные проблемные HTML через HTML → Markdown.

Почему в .md осталась навигация Confluence?

В сохранённый HTML попала оболочка сайта. Обрежьте страницу до тела статьи или повторите сохранение в режиме без лишней обвязки. Затем снова конвертируйте. Если мусор остаётся, вычистите блок вручную в .md один раз и запомните правило для остальных.

Куда деть вложения больше лимита репозитория?

Вынесите на файловое хранилище или LFS по правилам команды. В главе оставьте ссылку и краткое описание. В Git держите то, что нужно для сборки документации онлайн. Тяжёлые дистрибутивы вики тащить не обязательно.

Где конвертировать выгрузку прямо сейчас?

Сохранённый .html — в HTML → Markdown. Другие форматы — в конвертер в Markdown. Дальше читайте HTML в Markdown и документация в Markdown. Сравнение сред: Markdown vs Word vs Google Docs.

Снимите пилотный раздел Confluence в HTML, получите .md через HTML → Markdown или конвертер в Markdown и сверстайте оглавление в docs/. Ориентиры: HTML в Markdown, документация в Markdown, Markdown vs Word vs Google Docs.