Интеграции: GitHub, Confluence, ZIP, PDF

Зачем это нужно

Документация редко пишется «с нуля». Обычно уже есть код в
репозитории, уже есть README, уже есть спецификации в Confluence,
где-то лежит PDF с техническим требованиями, а в почте —
markdown-папка. Чтобы не заставлять людей переписывать всё вручную,
Nextdocs умеет импортировать из этих источников и потом
автоматически подтягивать обновления.

Четыре варианта импорта:

• GitHub — постоянная двусторонняя связь: Nextdocs клонирует
  репу, AI-агент генерирует документацию по коду, при изменении
  кода (merge в main) документация актуализируется.

• ZIP — одноразовый импорт любого репозитория как архива.
  Подходит для приватных кодовых баз, не на GitHub.

• Confluence — одноразовый импорт из HTML-экспорта Confluence.

• PDF — одноразовый импорт PDF-файлов (спеков, технических
  требований, руководств) на уровне страницы.

GitHub

Установка GitHub App

1. На экране /repositories нажмите Install GitHub App.

2. Вас перекидывает на GitHub, вы выбираете организацию и
   репозитории, к которым Nextdocs будет иметь доступ. Можно дать
   read-only.

3. Возвращаетесь в Nextdocs — в списке появляются репы.

App требует права:

• Read-only на содержимое репозиториев (clone, pull).

• Read-only на события (нужны webhooks для знания о push'ах).

Запись в репу App не делает — никаких коммитов, никаких PR'ов от
имени Nextdocs. Односторонний поток: код → документация.

Создание проекта из репы

На экране /projects → Create New Project → From GitHub:

1. Выберите репозиторий из уже установленных.

2. (Опционально) Выберите ветку, от которой генерить — по
   умолчанию main / master.

3. Дайте проекту имя.

4. Создать — проект появляется сразу, со статусом «Generating».

5. В фоне:

   • Клонирование репы в storage Nextdocs.

   • AI-агент проходит по файлам, генерирует markdown-документацию.

   • Страницы дерева заполняются. Вы видите, как они появляются в
     реальном времени.

6. По завершении статус проекта меняется на «Ready», вы можете
   читать и править.

Синхронизация после push в main

Когда в отслеживаемый репозиторий что-то замёрджили (push в default
branch):

• GitHub шлёт webhook в Nextdocs.

• Nextdocs обновляет клон.

• Агент смотрит, какие файлы изменились, и обновляет
  соответствующие страницы документации. Ваши ручные правки,
  сделанные через Nextdocs, сохраняются, если они не касаются
  изменившихся частей. Если задевают — создаётся отдельная запись в
  истории «agent_update», которую можно ревьюить / откатывать.

Привязка нескольких репозиториев к одному проекту

Через экран /repositories можно Attach to project — связать
уже склонированную репу с существующим проектом. Тогда AI-чат /
поиск в этом проекте будут видеть и код всех привязанных реп
одновременно.

Сценарий: монорепозиторий команды с 5 микросервисами → 1 проект в
Nextdocs + 5 репозиториев привязаны → единое место для поиска по
всему коду.

Detach / удаление

• Detach repository from project — связка разрывается, репа
  остаётся в Nextdocs. Страницы, сгенерированные по ней, не
  удаляются — они становятся обычными «ручными» страницами. Агент
  больше не обновляет их автоматически.

• Delete repository — удаляется клон в storage. Если репа была
  привязана к проектам — сначала она у них удалится автоматически.

ZIP

Когда использовать

• Приватный GitLab / Bitbucket / собственный git-сервер.

• Нет возможности устанавливать GitHub App.

• Разовый импорт, обновлять не планируется.

Как импортировать

На /projects → Create New Project → From ZIP:

1. Загружаете .zip-архив со всем репозиторием (исключите
   .git/, node_modules/, сборки — только исходники).

2. Даёте название, описание.

3. Nextdocs распаковывает, проходит агентом, генерирует документацию.

4. Итог — обычный проект, в котором нет привязки к внешней репе.
   Обновления через новые zip-загрузки: отдельная кнопка «Re-upload
   archive» в меню проекта.

Максимальный размер архива — 100 МБ.

Confluence

Когда использовать

• У вас есть документация в Confluence, вы переезжаете в Nextdocs.

• Хотите «заморозить» старый wiki как архив внутри Nextdocs.

Как импортировать

1. В Confluence: Space settings → Export space → формат HTML.

2. Скачайте полученный архив (может быть несколько мегабайт).

3. В Nextdocs: /projects → Create New Project → From
   Confluence export.

4. Укажите название проекта, загрузите архив.

5. Nextdocs:

   • Парсит HTML-страницы, конвертирует в internal markdown.

   • Восстанавливает иерархию страниц (как в исходном space).

   • Картинки и файлы, на которые есть ссылки — вытаскиваются из
     zip'а и загружаются в storage.

   • Макросы Confluence, которые не имеют аналога — превращаются в
     текстовые плейсхолдеры вида [Confluence macro: jira-issue],
     видные в тексте, чтобы вы могли вручную их допилить.

Что теряется

• Confluence-специфичные макросы: Jira, Calendars, Analytics —
  становятся плейсхолдерами.

• Вложения: если файл был приложен к странице как attachment,
  он подгрузится в storage; если это была встроенная Confluence-
  галерея — станет списком ссылок.

• Комментарии — не переносятся, потому что они относятся к
  Confluence-юзерам, которых нет в Nextdocs.

• Watchers / permissions — настройки прав надо пересоздать
  заново (см. Permissions).

Что остаётся

• Полная иерархия страниц.

• Весь текст, заголовки, списки, таблицы.

• Встроенные картинки.

• Ссылки между страницами (внутри импортированного space'а они
  конвертируются в ссылки Nextdocs).

PDF

Когда использовать

• У вас есть ТЗ в PDF от заказчика или подрядчика.

• Приказ / регламент / руководство прислали в виде PDF.

• Старая документация, которую просили в «официальном» формате, и
  сейчас надо поднять её в живую wiki.

• Статьи и whitepaper'ы, по которым вы пишете свои conclusions.

Как импортировать

Два варианта:

1. Импорт в страницу (рекомендуется для документов, которые вы
планируете редактировать / обсуждать / комментировать).

1. Откройте или создайте пустую страницу в проекте.

2. Слеш-меню → Import PDF.

3. Выберите файл (до 50 МБ).

4. Nextdocs парсит PDF:

   • Извлекает текст с сохранением порядка.

   • Распознаёт заголовки по размеру шрифта (крупный → H1, средний
     → H2 и т.д.).

   • Распознаёт списки (маркированные / нумерованные).

   • Таблицы — если PDF содержит "честные" таблицы (не картинки),
     становятся Nextdocs-таблицами.

   • Изображения вытаскиваются и загружаются в storage.

5. Через несколько секунд страница заполняется распарсенным
   содержимым. Вы её редактируете как любую другую.

2. Импорт как проект (для большого документа в 100+ страниц,
который хочется разбить по разделам).

1. /projects → Create New Project → From PDF.

2. Загружаете файл.

3. Nextdocs разбивает PDF на главы / разделы (по заголовкам 1-го
   уровня) и создаёт структуру проекта:

   • Корневая страница — оглавление.

   • Дочерние страницы — главы документа.

   • Каждая глава — обычная редактируемая страница.

Что хорошо переносится

• Текстовые PDF (сгенерированные Word / LaTeX / Pandoc) —
  отлично. Текст, заголовки, списки, базовые таблицы,
  изображения.

• Многоколоночные PDF (научные статьи) — парсер понимает
  порядок колонок.

• PDF с закладками (bookmarks) — используются для построения
  иерархии при импорте «как проект».

Что переносится хуже

• Скан / OCR PDF (где текст — это изображение). Nextdocs
  делает OCR, но качество зависит от оригинала: чистый скан 300
  dpi распознаётся хорошо, фотография мятого листа — плохо.

• Сложное layout'ом (инфографика, рекламные брошюры) —
  текст выдёргивается, но визуальная целостность теряется.

• Формулы (LaTeX-ные математические выражения) — вставляются
  как текстовое приближение. Для сохранения оригинала — скриншоты.

• Комментарии и аннотации PDF — игнорируются (только основной
  текст).

Поиск и AI-чат после импорта

После импорта страница становится полноценной — поиск и AI-чат
находят её содержимое. Это значит, что после импорта PDF вы
можете:

• Задать вопрос «что написано про X в этом документе?».

• Найти через Cmd/Ctrl+K конкретную цитату.

• Комментировать куски текста, упоминать коллег.

То, что недостижимо в оригинальном PDF-вьювере — в Nextdocs
работает сразу.

Ограничения

• Максимум 50 МБ на файл.

• Максимум 500 страниц (выше — только импорт частями).

• Формы и checkbox'ы внутри PDF — не распознаются (только
  текст).

• Защищённые паролем PDF — нужно сначала снять защиту вне
  Nextdocs.

• Полное сохранение layout'а — невозможно (PDF делается для
  печати, наш редактор для reflow-текста).

Статусы проектов

У проекта есть визуальный статус-chip на карточке:

• Generating / Importing — идёт процесс. Редактировать можно, но
  с осторожностью — агент может перезаписать страницы.

• Ready — импорт / генерация завершены.

• Error — что-то упало. В деталях проекта вы увидите, что именно:
  «Не удалось склонировать» / «Превышен размер архива» / «Файл X
  не парсится как HTML». Обычно надо исправить input и повторить.

• Updating — идёт обновление от push'а. Быстро, секунд 10-30.

Ограничения

• GitHub App: только organization + user-level. Enterprise Server
  on-premise — через отдельный договор.

• Поддерживаемые кодовые языки для генерации документации: Go,
  Python, TypeScript / JavaScript, Java, Rust, C#, C/C++. Другие
  парсятся как «текстовые», качество документации будет хуже.

• Confluence-экспорт — только HTML-формат. PDF и XML не
  поддерживаются.

• Webhooks работают только для default branch репы. Если у вас
  документация живёт на dev, придётся либо переключить default,
  либо обновлять вручную.

Типовые сценарии

«У нас уже 200 репо, из каждой хотим wiki». Подключите GitHub
App на всю организацию, создавайте проекты пачками по одной репе,
или соберите несколько реп в один «зонтичный» проект.

«Есть архив старой Confluence-базы на 500 страниц». Импорт через
ZIP — один раз. Получите живой архив. Устаревшее — помечайте
тэгом / переносите в «Archive»-раздел.

«Хотим документацию, которая обновляется с кодом автоматически».
GitHub App + from-repo project + включённая авто-синхронизация (по
умолчанию включена). Тимлид ревьюит «agent_update» события в
истории, откатывает если что-то совсем мимо.