Цикл "Docs-as-code на максималках":

  1. Фундамент: Архитектура и видение проекта

  2. Публикация: Пайплайн Markdown → Confluence

  3. Рабочее место: Obsidian как IDE для аналитика ← вы здесь

  4. Правила игры: Workflow и обратная совместимость

  5. AI-агент: На пути к вайбаналитингу

Движок публикации у нас уже есть. Но пока аналитик пишет спеки в сыром Markdown, удобства работы у него не прибавится. Попробуем исправить это: выберем и затюним редактор под наши нужды.

Почему не IDE

Из моего опыта чаще всего в компаниях docs-as-code предлагают вести в обычной IDE: JetBrains, VS Code и им подобных.

Мы тоже с этого начали. И быстро уткнулись: IDE заточена под разработку, а Markdown-плагины к ней в лучшем случае среднего качества. Можно писать в сырой разметке и помнить синтаксис, можно обвеситься плагинами, но отсутствие удобного GUI все равно остается большой проблемой. Аналитику после вылизанной Wiki это тяжело продать.

Поэтому мы пошли искать md-редактор, лучше подходящий для решения нашей задачи.

Базовый минимум для нас:

  • Это markdown – родной формат для нейронок, а в наше время это важно. Поэтому другие форматы не рассматривали

  • Это GUI – то чего не было в JetBrains, там ты по большей части работаешь с сырой разметкой и нужно помнить синтаксис

  • Это кроссплатформенный редактор

  • Это расширяемый и кастомизируемый редактор – чтобы была возможность допилить его под себя

  • Это бесплатное решение

На поиск ушел целый квартал. В итоге остановились на Obsidian.

Чем хорош Obsidian

Позиционируется Obsidian как редактор личных заметок, офлайн-аналог Notion. Но под капотом это очень мощный Markdown-редактор: по удобству сравнимый с Confluence, а по возможностям автоматизации и расширения бесконечно выигрывающий.

Чего уж тут говорить, даже эту статью я тоже пишу в Obsidian.

Что для нас оказалось решающим:

  • Скоростной, интуитивный GUI. Открытие страниц мгновенное, работать приятно. Такого софта с хорошим UX в принципе немного.

  • Кросс-платформенность. Obsidian написан на Electron, поэтому работает под Windows, macOS, Linux (а еще на планшетах и телефонах)

  • Система Vaults. Obsidian чуть ли не единственный md-редактор, который использует изолированные хранилища и умеет корректно работать с относительными ссылками между .md (остальные норовят использовать полный путь). Можно склонировать репозиторий и запустить его как независимую изолированную среду и ссылки будут одинаково правильно вести себя и в Obsidian, и после переноса в Confluence.

  • Расширяемость. Большой качественный маркетплейс готовых плагинов плюс открытый фреймворк для своих. По сути это Node.js в чистом виде, почти ничем не ограничен. Для сравнения, писать плагины под Confluence на их платформе Forge отдельная боль.

Мы встроили туда много всего необходимого: git клиент, swagger, редакторы plantUML и Mermaid, Draw.io, AI-агента, кучку расширений самого редактора, скрипты для автоматизации и проверки целостности перед выполнением push в репозиторий.

В общем мы взяли Obsidian и превратили его, по сути, в "IDE для аналитика" или в IAE - Integrated Analysis Environment (как бы пафосно это ни звучало)

Shared-конфигурация

С внедрением Obsidian мы автоматически получаем одну очень ценную фичу - общую конфигурацию.

Благодаря архитектуре Obsidian, все его настройки, плагины (вместе с их исходным кодом), шаблоны документов, конвенции по написанию спек лежат в отдельном каталоге, который является частью репозитория. Нам остается только вынести его в отдельный submodule.

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

Что мы встроили в Obsidian

К базовому обвесу Obsidian можно добавить сколько угодно плагинов и скриптов.

Вот что сделали мы:

  • shell-скрипт - который настраивает git-клиент, подтягивает submodules и разграничивает права доступа

  • Simple Git - Самописный плагин с четырьмя кнопками (pull / создать ветку / commit / push). 80% рутинных действий решаются в один клик: при создании ветки вводится только номер задачи, имя генерируется по шаблону; сообщение коммита предзаполняется и привязывается к ветке.

  • Obsidian Git - Для решения более сложных задач (мержи, откаты)

  • PlantUML - исходник диаграммы правится прямо в Obsidian и на лету рендерится в картинку.

  • Mermaid Tools - аналогично для Mermaid

  • Diagrams.net - встроенный мини-редактор диаграмм (сохраняются в SVG в static/).

  • Custom Frames - возможность работать со Swagger прямо в Obsidian

  • Find orphaned files and broken links - проверка целостности ссылок перед push в репозиторий.

  • Painter - цветовое выделение текста 

  • Text Snippets - возможность быстрой вставки отдельных элементов разметки

  • Claudian - обертка для работы с claude code (об этом подробно в последней части цикла)

  • Полуавтоматическая генерация описания задачи - собирает по шаблону все измененные аналитиком артефакты в одну страницу (которая позже будет прилинкована к тикету в Jira). Это самописный скрипт, учитывающий внутреннюю структуру репозитория.

Детали конфигурации

1. Скрипт-конфигуратор

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

  • graphviz - быстрая генерация диаграмм plantuml

  • claude code - для возможности использования AI-агентов

  • Node.js - запуск локальных mcp-серверов (как часть конфигурации claudian)

  • конфигурация git-клиента для автоматического pull для submodules (конфигурация, исходный код проекта). Примерно так:

cd "$(dirname "$0")/.."  
SUBMODULES=$(git config -f .gitmodules --get-regexp '^submodule\..*\.path$' | awk '{print $2}')   
git submodule update --init --recursive
git config submodule.recurse true  
git config status.submoduleSummary true  
git config diff.submodule log  
  
for SUBMODULE in $SUBMODULES; do
  git -C "$SUBMODULE" remote set-url --push origin DISABLE 2>/dev/null || true  
  HOOKS_DIR=$(git -C "$SUBMODULE" rev-parse --path-format=absolute --git-path hooks)  
  mkdir -p "$HOOKS_DIR"  
  cp scripts/git-hooks/source-code-reference-transaction "$HOOKS_DIR/reference-transaction"  
  chmod +x "$HOOKS_DIR/reference-transaction"  
done  

git config alias.refresh-code "submodule update --init --remote"  
git submodule sync --recursive  
git submodule update --init --remote  

При каждом git pull автоматически будут обновляться и нужные submodules. В Obsidian это будет происходить в 1 клик.

Вручную остается только настроить переменные PATH, если на клиентской машине нужные утилиты находятся по нестандартному адресу.

2. Статика и git-lfs

Git-lfs довольно распространенное расширение для git, которое позволяет не захламлять репозиторий тяжелыми бинарниками и хранить их во внешнем хранилище.
В связке с Obsidian можно сконфигурировать это так, чтобы конечный пользователь даже не знал о его существовании.

Шаг 1: В .gitattributes добавить следующую строку

**/static/* filter=lfs diff=lfs merge=lfs -text

Шаг 2: Настроить работу с вложениями в самом Obsidian

Настройка Obsidian для работы с вложениями
Настройка Obsidian для работы с вложениями

Итого каждый раз, когда к странице будет добавлено какое-либо вложение (изображение, pdf и прочее), оно автоматически разместится в папке static рядом с .md файлом и далее попадет в git-lfs.

3. Simple Git и НеSimple Git

Obsidian изначально был задуман как локальный редактор заметок и хорошей удобной интеграции с Git у него не было.

Стороннее расширение Obsidian Git функционально, но довольно тяжело в использовании (многие вещи делаются из консоли и нужно хорошо понимать с чем ты имеешь дело).
При этом подавляющее большинство повседневных задач аналитика примитивны - push, commit, pull, создание и переключение между ветками.

Чтобы делать это быстро, мы создали для себя отдельный плагин Simple Git, который позволяет делать эти операции в пару кликов.
В Obsidian добавилась легковесная панель, которая отвечает за эти операции.

Simple Git
Simple Git

4. Extended markdown

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

С переходом на markdown мы также приходим к пониманию того, что в Confluence есть куча удобных штук, которых в чистом Markdown нет: info-панели, сворачиваемые блоки, сложные таблицы, etc. При наивном переходе на docs-as-code все это теряется.

Решить это тоже возможно расширениями markdown-it. Мы смотрим, как элемент оборачивает Obsidian, и делаем так, чтобы он переехал в Confluence в том же виде. По сути мы добавили поддержку этого расширенного языка разметки в наш пайплайн и его перенос в Confluence.

Что поддержали:

  • Info-панели: на базе цитаты с заголовком-типом.

  • Include-страницы: включение содержимого одной страницы в другую (с кучей вариаций - как страницу целиком, так и отдельный абзац).

  • Expand: сворачиваемые панели

  • Расширенные таблицы: адаптивное изменение ширины столбцов и возможность объединения ячеек.

  • Раскраска текста: те же возможности, что и в Confluence.

Пример того, как это выглядит для Info-панелей:

Вид в Obsidian
Вид в Obsidian

Вид в Obsidian

Obsidian
Obsidian

Сырой Markdown

После рендеринга в Confluence
После рендеринга в Confluence

После рендеринга в Confluence

Мы пришли к тому, что все, что создано в Obsidian, практически 1-в-1 переносится в Confluence и выглядит так же.
При этом это все еще Markdown - откроете файл в любом редакторе, ничего не сломается.

5. PlantUML и Mermaid

В Obsidian очень легко встраивать текстовые диаграммы (блок кода с пометкой plantuml), которые рендерятся прямо на странице

Добавление PlantUML в Obsidian
Добавление PlantUML в Obsidian

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

6. Вариации ссылок

Ссылок и вариантов include стало так много, что синтаксис было не запомнить, поэтому мы добавили их в контекстное меню для удобства.

Контекстное меню
Контекстное меню

7. Скрипт для генерации постановки задачи

Информация, которая должна попасть в постановку задачи, хранится в специальном файле tasks/CRM-XXXX.md, драфт которого может генерироваться в полуавтоматическом режиме.

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

Генерация постановки задачи
Генерация постановки задачи

8. Templates

Одна из встроенных фич Obsidian.
Шаблоны страниц - это еще одна папка в репозитории, путь к которой достаточно просто указать в настройках

Настройка шаблонов
Настройка шаблонов

После этого их можно использовать в повседневной работе.

Использование шаблонов
Использование шаблонов

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

9. Swagger

С помощью Custom Frames можно добавлять web-инструменты прямо в Obsidian, мы например встроили в него Swagger Editor.
Просто для удобства можно иметь быстрый доступ к часто используемым инструментам.

Swagger
Swagger

Справедливости ради, это не нативно встроенное расширение, и редактировать файлы в 1 клик там не получится (нужно будет сделать два). Но все равно чуть удобнее, чем открывать браузер.

10. Прочее

На самом деле расширять можно бесконечно, выше лишь пример того, как можно достаточно сильно видоизменить стандартный Obsidian и решать им задачи работы с docs-as-code.

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

Что дальше

В следующей статье обсудим структуру спецификаций, модели веток и рабочий flow и заодно разберем, как мигрировать со старого Confluence, не ломая жизнь ни аналитикам, ни читателям.

Комментарии (0)