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

За последний год мы переписали почти всю проектную документацию в markdown и положили в тот же git, где лежит код. Причина простая: после перехода на Cursor и Claude Code так было удобнее работать. Модели нормально обрабатывают markdown и не лопатят десятистраничный google-док, диффы видно в PR, доки лежат рядом с кодом, который описывают. Всегда можно обратиться к инфе по проекту, внести обновления — короче пользоваться документом, а не хранить его для красоты.

И тут вылезла проблема, о которой лично мы заранее не подумали: документацию читает не только тот, кто её пишет. Её читают клиенты, менеджеры, дизайнеры, эйчары. А они в репозиторий не полезут никогда.

Дать клиенту доступ в GitHub/GitLab — так себе затея сразу по нескольким причинам: там лежит то, что ему видеть не надо, это лишний разговор про безопасность, да и сам интерфейс гитхаба человека не из айтишки отпугивает. Плюс требуется регистрация. В итоге мы делали то же, что, по-моему, делают все: копировали markdown в google docs, чтобы клиент мог прочитать и покомментировать, а потом при каждом изменении заново выгружали и сводили комментарии руками. Год так жили.

Что смотрели, прежде чем пилить своё:

GitBook и Mintlify хотят, чтобы ты писал в их редакторе. Ради шеринга пришлось бы бросить тот самый workflow, ради которого мы в git и переехали. Плюс ценник.

Notion — это снова копипаст markdown в очередной инструмент. А когда захотели прикрутить ИИ-агента к докам, выяснилось, что Notion MCP для гостевых аккаунтов просто не работает (висит открытый issue) — клиенту агента дать мы не можем.

GitHub Wiki / Docusaurus оставляют тебя в markdown, но клиенту для комментариев всё равно нужен гитхаб-аккаунт. 

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

Как устроено:

Подключаем репозиторий через GitHub/GitLab app, выбираем папки с markdown. Портал — зеркало репы: запушил коммит, страница перерендерилась. Никакого отдельного билда и деплоя для того, кто пишет код.

Рендер — обычный markdown + GFM, подсветка кода, mermaid, оглавление, перекрёстные ссылки. 

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

Комментарии — читатель комментирует конкретный абзац, треды по разделам, владельцу всё падает в один инбокс, можно отметить resolved. Без гитхаб-аккаунта со стороны комментатора.

И самое интересное — MCP. Поверх тех же доков поднят MCP-сервер, чтобы ИИ-агент (Claude Code, Cursor, Claude Desktop) отвечал по документации. Тут важно было не облажаться с правами: авторизация OAuth 2.1 + PKCE, каждое соединение привязано к реальному аккаунту, и запрос видит ровно то, что этот аккаунт видит в браузере, — не больше. .docignore в индекс MCP тоже не попадает. Сервер read-only: агент читает, перезаписать доки не может. Mintlify MCP работает только по публичным докам, Notion блокирует гостей — поэтому для приватной клиентской документации оба мимо.

Чего тут нет, и врать не буду:

Это не редактор. Принципиально read-only вьювер + комментарии + MCP. Хочешь править — правишь там, где писал.

Self-hosted пока нет, в планах. 

Если кто-то решал ту же боль иначе — расскажите в комментах, реально интересно, может, мы где-то переусложнили.

Ссылка: miradorly.com. Бесплатно 30 дней, карты для регистрации не надо. Если у вас такой проблемы нет и не было — не минусуйте плиз и просто проходите мимо. Ну или делитесь мыслями по существу.