Документация из репозитория — на сайт за 5 минут

Документация лежит в репозитории. Markdown-файлы, схемы, примеры. Всё актуальное — рядом с кодом.

Проблема: читать её могут только те, у кого есть доступ к репозиторию. Аналитик хочет посмотреть API — нужен GitHub. Менеджер ищет описание фичи — просит разработчика скинуть файл.

Ещё проблема: репозиториев несколько. У каждой команды свой. Документация раскидана.

Результат

Разработчик обновляет код и документацию в GitHub. Push в master — документация на сайте. Коллеги читают через браузер, AI-ассистент отвечает на вопросы через MCP. Без доступа к репозиторию, без копирования файлов.

Как это работает

GitHub Action синхронизирует папку docs/ с сайтом. Push в main — документация обновилась.

on:
  push:
    branches: [main]
    paths: ['docs/**']

jobs:
  sync:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - run: |
          curl -L -o trip2g-sync.mjs \
            https://github.com/trip2g/obsidian-sync/releases/download/0.3.5/trip2g-sync.mjs
          node trip2g-sync.mjs \
            --folder ./docs \
            --api-url https://docs.yourcompany.com/graphql \
            --api-key ${{ secrets.DOCS_API_KEY }}

Пять минут на настройку. Дальше автоматически.

Доступ по подпискам

Документация не публичная. Только сотрудники компании. Или только определённые отделы.

trip2g управляет доступом через subgraphs. Один репозиторий синхронизирует с --meta subgraph=backend-team, другой — с --meta subgraph=product. Каждый видит своё.

Несколько репозиториев — один сайт

Backend-команда пушит в docs.company.com из своего репо. Frontend — из своего. DevOps — из своего.

Всё собирается в одном месте. Единый поиск, единая навигация. Wikilinks работают между документами разных команд.

MCP для AI

Документация доступна через MCP-сервер. Claude Code читает её напрямую — без копирования в контекст.

AI-агент видит актуальную документацию всех команд. Отвечает на вопросы, генерирует код по спецификациям, находит нужные разделы.

Любой дизайн

Markdown — это контент. Отображение — отдельно.

Кастомизация на любом уровне: HTML-шаблоны, CSS, JavaScript. Документация backend-команды выглядит как техническая wiki. Документация для клиентов — как лендинг с иллюстрациями. Один движок, разные темы.

Внутреннее → публичное

Внутренняя документация подробная: архитектурные решения, edge cases, код. Публичная — другая: проще, без деталей реализации.

AI читает внутреннюю документацию через MCP и генерирует публичную версию. Технические спецификации превращаются в понятные руководства. Обновили внутренний документ — запустили агента — публичная версия актуальна.

AI синхронизирует документацию

Главная проблема документации — она устаревает. Код изменился, а документация осталась прежней.

Решение: AI постоянно синхронизирует код и документацию. Разработчик меняет API — агент обновляет описание эндпоинтов. Добавил новый параметр — агент дописал в справочник.

Если AI сам пишет код — ещё проще. Агент знает, что изменилось, и сразу обновляет документацию. Внутреннюю — для разработчиков. Публичную — для пользователей. Обе версии остаются актуальными.

Схема: код и внутренняя документация в одном репозитории. AI следит за изменениями, генерирует публичную версию, отправляет PR. Человек проверяет и принимает.

Редакторский процесс

Документация — тот же контент. Нужен контроль качества.

Pull Request: автор предлагает изменения, редактор видит diff, комментирует построчно, принимает или отклоняет. Без подтверждения — правка не попадёт на сайт.

AI-агент пишет черновик документации по коду. Техлид проверяет через PR. История изменений сохраняется — видно, кто что менял и когда.

Подробнее о редакторском процессе в Git — git-for-writers.

Кому подходит

  • Компании с несколькими командами. Каждая ведёт документацию в своём репо, но читают все.
  • Закрытая документация. API, архитектура, внутренние процессы — не для публичного доступа.
  • AI-автоматизация. Агенты работают с документацией через MCP.

Как начать

  1. Добавьте workflow в репозиторий
  2. Создайте API-ключ на сайте документации
  3. Положите ключ в GitHub Secrets
  4. Push — документация на сайте

Несколько репозиториев? Повторите для каждого с разными --meta subgraph=.

CLI и Obsidian-плагин используют общее ядро синхронизации. Подробнее — в документации CLI.