Проектная документация всё чаще живёт рядом с кодом: в Markdown-файлах того же репозитория. Такой подход удобен команде: изменения видны в pull request, текст обновляется в контексте задачи, а инструменты разработки и ИИ-помощники работают с файлами без промежуточных выгрузок. Трудность появляется, когда документ должен прочитать клиент, менеджер или дизайнер, которым доступ к репозиторию не нужен и неудобен.

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

Почему доступ к Git плохо подходит внешнему читателю

GitHub и GitLab созданы прежде всего для разработки. В приватном репозитории лежат исходный код, история изменений, рабочие ветки, внутренние заметки и иногда конфигурация. Даже при аккуратно выданных правах сам разговор о доступе расширяет периметр и требует объяснить клиенту, где регистрироваться и как ориентироваться в интерфейсе.

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

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

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

В описанном подходе репозиторий подключается через приложение GitHub или GitLab, а команда выбирает папки с Markdown-документами. Портал становится их отображением: после коммита страница перерендеривается. Автор документа продолжает работать в привычном редакторе и не запускает отдельную публикацию ради каждой правки.

Такой механизм сохраняет полезные свойства документации в Git. Markdown остаётся рядом с кодом, а дифф в pull request показывает, что именно поменялось в описании продукта или интеграции. Это особенно ценно для команд, которые уже используют Cursor, Claude Code или другие инструменты, умеющие читать структуру файлов: им не требуется забирать знания из отдельного облачного редактора.

Внешняя страница при этом может выглядеть как нормальная документация. Для неё нужны как минимум поддержка GFM, подсветка кода, оглавление и внутренние перекрёстные ссылки. Если в материалах есть схемы, пригодится рендеринг Mermaid. Эти детали определяют, сможет ли читатель разобраться в документе без доступа к разработческому окружению.

Граница должна задаваться до публикации

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

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

Перед запуском полезно отдельно составить список того, что допустимо публиковать. Для документации по API это могут быть контракт, примеры запросов и порядок интеграции. Для продуктового проекта — пользовательские сценарии, согласованные макеты и правила приёмки. Внутренние обсуждения, технические гипотезы и служебные конфигурации должны остаться за пределами выбранных папок и правил индексации.

Когда готовые сервисы добавляют лишнюю работу

Готовые платформы документации решают часть задачи, но их условия стоит проверить до миграции. GitBook и Mintlify могут потребовать вести материалы в собственном редакторе. Notion часто возвращает команду к ручному копированию Markdown, а доступ к функциям интеграции зависит от типа аккаунта. GitHub Wiki и генераторы вроде Docusaurus сохраняют Markdown, но комментарии клиента всё равно могут быть связаны с аккаунтом GitHub.

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

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