Разработка сайта документации на Nextra (Next.js + MDX)

Nextra: почему сайт документации разъезжается при росте продукта

Документация растёт вместе с продуктом, а самописный сайт на статике — нет. Сначала появляется раздел с описанием API, потом гайды под каждую версию, потом десятки страниц, которые кто-то ведёт вручную. Через несколько релизов структура документации перестаёт совпадать с реальностью: часть страниц описывает устаревшее поведение, часть ссылается на разделы, которые уже перенесли или переименовали. Nextra закрывает именно этот класс поломок, потому что документация здесь — это файлы в репозитории, а не отдельная вёрстка, которую нужно синхронизировать руками.

Первым ломается версионирование документации. Когда поддержка старых версий ведётся копированием папок, правка в актуальной ветке не доезжает до предыдущей, и пользователь на старой версии читает неверный формат запроса. В Nextra версии — это отдельные наборы контента с общим шаблоном, поэтому новая страница появляется в нужной ветке, а не расползается по копиям. Рассинхрон версий перестаёт быть задачей «не забыть поправить в трёх местах».

Второй источник боли — ручные правки в вёрстке. Как только автор текста лезет в разметку, чтобы поправить блок или добавить таблицу, ломается навигация, а вместе с ней и поиск по документации. Когда страницы пишутся в MDX, а каркас, меню и оглавление собираются из структуры файлов, текст и представление разделены: редактор правит содержание, шаблон остаётся нетронутым.

Третья поломка — битые ссылки при переносе разделов. Переименовали страницу, и десятки внутренних ссылок ведут в никуда; поиск по документации при этом индексирует уже несуществующие адреса. Если структура документации выводится из файловой системы, а ссылки проверяются на сборке, разъезд ловится до публикации, а не по жалобам читателей. Разбираем, как это закрывается на практике.

Что даёт Nextra: режимы сборки, навигация и поиск

Nextra собирает документацию из MDX-файлов: контент и разметка лежат в одном файле, а на выходе получается статический сайт с готовой навигацией и поиском. Сборка инкрементальная — правка одного раздела пересобирает только затронутые страницы, поэтому типичный цикл «поправил текст → посмотрел локально» укладывается в секунды, а не в минуты, как при полной пересборке.

Режимы сборки и MDX-контент

Статическая генерация отдаёт готовые страницы, которые раздаются с CDN без серверного рендеринга на каждый запрос. MDX позволяет вставлять в текст документации живые компоненты — таблицы параметров, переключатели версий, встроенные примеры. Автор раздела правит один файл и не трогает вёрстку: структура страницы, оглавление и хлебные крошки строятся из дерева файлов автоматически.

Навигация и локальный поиск

Навигация по разделам задаётся порядком файлов и метаданными — новая страница появляется в меню без ручной правки шаблонов. Локальный поиск индексирует контент на этапе сборки, поэтому работает без внешнего сервиса и не отправляет запросы наружу. Доля битых внутренних ссылок падает: сборка падает с ошибкой на несуществующий якорь, а не отдаёт 404 в продакшене.

Темизация документации

Тема и оформление выносятся в конфигурацию: цвета, шрифты, логотип, тёмный режим. Компоненты переиспользуются между разделами, поэтому визуальная правка делается в одном месте, а не в каждой странице.

Nextra закрывает типовой сценарий: контент-команда правит MDX, сборка проверяет ссылки и структуру, поиск и навигация обновляются сами.

Как мы внедряем сайт документации: от аудита до передачи

Внедрение сайта документации начинается с аудита того, что уже есть: разрозненные файлы в репозитории, страницы в вики, инструкции в переписке. На этом этапе мы собираем полную карту материалов, отмечаем дубли и устаревшие фрагменты, фиксируем, кто из команды заказчика отвечает за каждую тему. Без этого схема разделов получится умозрительной и развалится на первой же сотне страниц.

Дальше выстраиваем структуру и настраиваем сборку так, чтобы контент правился в markdown, а не в вёрстке. Nextra берёт на себя маршрутизацию и навигацию по файловой структуре, поэтому добавление раздела сводится к созданию папки и файла — без правок кода.

1. Аудит текущей документации. Инвентаризация источников, разметка дублей, оценка объёма и качества контента.
2. Схема разделов и версий. Дерево навигации, правила именования, ветки для разных версий продукта, единый глоссарий терминов.
3. Настройка сборки и поиска. Статическая генерация, локальный полнотекстовый поиск, подсветка кода, проверка сборки на каждом изменении.
4. Проверка ссылок. Автоматический прогон внутренних и внешних ссылок, отчёт по битым адресам до публикации.
5. Наполнение на реальном контенте. Переносим не образцы, а рабочие материалы — так сразу видно, где структура не выдерживает.
6. Ревью с командой заказчика. Проходим по разделам вместе с теми, кто будет писать документацию дальше.
7. Передача проекта. Доступы, регламент правок, инструкция по добавлению страниц и релизу.

Проверка ссылок и сборки встроена в конвейер публикации: страница с нерабочей ссылкой или сломанной разметкой просто не попадёт на сайт. Это снимает класс ошибок, которые обычно всплывают уже у пользователей и подрывают доверие к документации.

На выходе команда заказчика получает репозиторий с настроенной сборкой, схему разделов и версий, регламент правок и понятный порядок выпуска обновлений. Опишите вашу задачу — вернёмся с оценкой и планом внедрения.

Чем отличается генератор документации от ручной вёрстки разделов?

Ручная вёрстка разделов держится ровно до того момента, пока документация не начинает расти. Пока страниц десяток, инженер копирует разметку, правит текст и вручную проставляет ссылки между разделами. Как только появляется вторая версия продукта и ветка для устаревших релизов, каждая правка превращается в обход всех копий: где-то забыли поправить навигацию, где-то осталась ссылка на удалённый раздел, где-то разошлась структура заголовков. Ошибки находятся не на ревью, а в поддержке — когда клиент присылает скриншот с битой ссылкой.

Генератор документации переворачивает схему: контент хранится как структурированные файлы с текстом и разметкой, а навигация, оглавление, перелинковка и сборка страниц строятся из этой структуры автоматически. Nextra работает поверх Next.js и принимает разделы в виде MDX — обычный markdown с возможностью вставлять компоненты. Добавили файл в каталог — он сам появился в боковом меню, попал в поиск и получил корректные ссылки. Никто не правит вёрстку руками, поэтому расхождений между разделами не возникает физически.

Масштабирование разделов перестаёт быть отдельным проектом. Версии выносятся в параллельные каталоги, и переключатель между ними — часть шаблона, а не набор продублированных страниц. Общий блок про авторизацию или лимиты описывается один раз и подключается в нужные места: правка в одном файле отражается везде, где он использован. Поддержка документации сводится к правке текста — инженер не трогает разметку и не думает о том, как это отобразится на соседней странице.

Цена перехода — разовая: нужно описать структуру каталогов, договориться о шаблоне страницы и перенести существующий контент. Дальше каждая новая версия и каждый новый раздел добавляются предсказуемо, а сборка проверяет ссылки и структуру до публикации, а не после жалобы читателя.

Кейс: документация продукта с еженедельными релизами

Продукт выпускал обновления раз в неделю, а документация отставала: раздел описывал поведение двухнедельной давности, и поддержка тонула в однотипных обращениях. Правки шли через разработчика — контент-редактор готовил текст, инженер вручную вставлял его в вёрстку и ждал ближайшего релиза. На разбор «где в документации написано про этот параметр» уходило до десяти минут, а битые ссылки после переименования страниц находили только по жалобам пользователей.

Перевели документацию на Nextra — генератор статических сайтов на Next.js, где разделы пишутся в MDX и лежат рядом с кодом в том же репозитории. Редактор теперь коммитит страницу сам, сборка проверяет ссылки и структуру на этапе сборки, а не в продакшене. Публикация раздела сократилась с двух дней до получаса, число битых ссылок упало с нескольких десятков до нуля — сборка просто не пропускает страницу с несуществующим адресом.

Отдельно решили поиск: индексируем контент на этапе сборки, поэтому подсказки появляются мгновенно и не зависят от внешнего сервиса. Доля правок, требующих разработчика, снизилась примерно до пятой части — остальное редакторы закрывают сами. Время до нужного ответа сократилось с десяти минут до минуты: пользователь ищет по ключевому слову и попадает в конкретный раздел, а не листает дерево.

Nextra выбрали за то, что документация живёт в том же репозитории и релизном цикле, что и продукт: правка уходит в прод вместе с версией, а не отдельным потоком. Поддержка разделов стала регламентной — устаревшие страницы помечаются при сборке, и мы видим, что требует обновления до релиза, а не после.

Что изменилось по метрикам: время публикации раздела — с двух дней до получаса, битые ссылки — с десятков до нуля, доля правок через разработчика — до пятой части, поиск ответа — с десяти минут до минуты. Релизный цикл перестал быть узким местом для документации.

Сомнения перед стартом: совместимость, миграция, откат, доступы

Переход на новый движок документации почти никогда не бывает «с нуля»: у команды уже есть накопленные страницы, вложенные разделы, картинки и внешние ссылки, на которые кто-то опирается. Поэтому первый технический вопрос — не «как выглядит шаблон», а что произойдёт с существующим контентом. На Nextra миграция идёт постранично: структура каталогов в репозитории повторяет дерево навигации, а страницы переносятся в формате MDX — обычный markdown остаётся валидным, а интерактивные блоки добавляются точечно там, где они действительно нужны.

Старые адреса сохраняются через правила перенаправления, поэтому внешние ссылки и поисковая выдача не рвутся.

Что если потребуется откат? Контент и конфигурация живут в репозитории, а не в админке, поэтому любое изменение — это коммит. Откат к предыдущему состоянию занимает минуты: возвращаем нужную ревизию, сборка перезапускается, сайт снова отдаёт прежнюю версию. Никаких «слепков базы», которые нужно отдельно восстанавливать.

Как устроены доступы? Репозиторий передаётся заказчику с настроенными правами: отдельные роли на чтение, на правки контента и на изменение конфигурации сборки. Мы не остаёмся единственной стороной с полным доступом — команда заказчика может вносить правки самостоятельно, а мы подключаемся по согласованным правам.

На руки заказчик получает:

• конфигурацию проекта: настройки сборки, навигации, поиска и правил перенаправления;
• схему разделов документации с описанием, где и как добавлять новые страницы;
• правила публикации: как правка попадает на сайт и кто её подтверждает;
• настроенные права доступа к репозиторию для ролей команды;
• регламент отката изменений с пошаговой инструкцией;
• документацию по поддержке: типовые задачи, частые ошибки сборки, точки расширения.

Опишите задачу — вернёмся с оценкой и планом: разберём текущую документацию, предложим схему разделов и порядок переноса без простоя.

Сроки этапов внедрения сайта документации

Сроки зависят не от объёма текста, а от того, сколько времени уходит на согласование структуры и на подключение к существующим источникам контента. Поэтому план разбит так, чтобы каждый этап заканчивался проверяемым результатом: после него видно, движемся мы дальше или что-то нужно уточнить.

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

Параллельно можно запускать этапы: пока согласуется структура, инженеры уже готовят сборку и тему. Это сокращает общий срок, но не влияет на качество — проверка и передача идут строго после наполнения, иначе документация уедет в продакшн с битыми ссылками.

Опишите задачу — вернёмся с оценкой и планом под ваш объём документации и текущий стек.