Сразу дисклеймер: это рассказ про инструмент, который мы написали для себя и используем каждый день. Ссылку дам в конце, продавать не буду — расскажу про проблему и как её решали, потому что упираемся в неё, возможно, не только мы.
За последний год мы переписали почти всю проектную документацию в 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 дней, карты для регистрации не надо. Если у вас такой проблемы нет и не было — не минусуйте плиз и просто проходите мимо. Ну или делитесь мыслями по существу.
Загрузка...
