Gramax: ваш Markdown в порядке с визуальным редактором и Git под капотом

Знакомо ощущение, когда нужно одновременно:

• Писать красивую документацию в Markdown
• Держать все версии под контролем через Git
• Дать доступ нетехническим коллегам без уроков по синтаксису?

Именно эту головоломку элегантно решает Gramax – open-source редактор, который я недавно обнаружил на GitHub. Давайте разберёмся, почему он заслуживает места в вашем workflow.

Что скрывается за меткой «docs-as-code»

Gramax позиционируется как инструмент для подхода «документация как код», но что это значит на практике? По сути, это:

• Все файлы хранятся локально в человекочитаемом Markdown
• Полноценная Git-интеграция из коробки
• Визуальный редактор для тех, кто не хочет помнить синтаксис

При этом система не замыкается в себе – файлы можно редактировать в любом текстовом редакторе, а изменения синхронизировать через привычные Git-команды.

Кому пригодится?

• Техническим писателям, уставшим от Confluence
• Разработчикам, ведущим проектную документацию
• Командам, где нужно совместно работать над guides
• Всем, кто хочет перенести базу знаний из Notion на открытую платформу

Три кита Gramax

1. WYSIWYG-редактор для Markdown

Здесь реализовано то, чего так не хватает в обычных .md-редакторах:

• Реальная визуальная работа с таблицами
• Вставка видео и сложных элементов в пару кликов
• Поддержка диаграмм (Mermaid, Excalidraw)
• Swagger-описания API прямо в документе

При этом «под капотом» – чистый Markdown, который можно править хоть в Vim.

2. Git-first философия

Gramax не просто «умеет работать с Git» – он построен вокруг версионности:

# Стандартный workflow
$ gramax-cli build --source ./content --destination ./output

• Встроенные инструменты для разрешения конфликтов
• Поддержка GitHub/GitLab/Bitbucket
• История изменений без необходимости лезть в консоль

3. Публикация без головной боли

Готовую документацию можно:

• Развернуть как статический сайт
• Запустить через Docker-контейнер
• Хостить на своём сервере

Технологический стек

Для интересующихся, что крутится внутри:

• Frontend: TypeScript + ProseMirror
• Desktop: Tauri (альтернатива Electron)
• Бэкенд: Rust для критичных по производительности задач

Особенно радует выбор Tauri – это даёт нативное быстродействие при скромном потреблении ресурсов.

Из практики: как мы внедряли Gramax

В наём проекте переводили документацию с Confluence на docs-as-code подход. Проблемы, с которыми столкнулись:

1. Технические писатели не хотели учить Git
2. Разработчикам не хватало визуального редактирования
3. Нужно было сохранить историю изменений

Gramax закрыл все три вопроса:

• Писатели работают в удобном интерфейсе
• Devops автоматизирует сборку через CI/CD
• Все изменения прозрачны в репозитории

Миграция из Notion заняла 2 дня вместо планируемой недели.

Когда Gramax – не лучший выбор

Честно о ограничениях:

• Пока нет мобильной версии
• Меньше готовых тем, чем у GitBook
• Русская локализация в процессе

Но для команд, где важны контроль версий и открытость данных, плюсы перевешивают.

Как попробовать?

Начать можно прямо сейчас:

1. Онлайн-версия: app.gram.ax
2. Десктопные приложения: gram.ax
3. Исходники: GitHub репозиторий

Для тех, кто устал от закрытых платформ и хочет настоящей свободы в работе с документацией, Gramax – свежий глоток воздуха. Лично я уже перенёс в него все свои проектные заметки и не пожалел.