Наконец-то я "раздобыл" немного свободного времени, а значит пришла пора продолжить серию туториалов по XWiki. После публикации одной из моих статей MaxK82 спросил у меня, можно ли как-то в XWiki подключить документацию из git репозитория, так чтобы наладить её версионирование. К сожалению эта статья не ответит на его вопрос, но возможно укажет направление, в котором стоит "копать".Поэтому сегодня мы с вами: напишем простенький, зато свой макрос в XWiki; клонируем прямо в XWiki репозиторий с GitLab; отобразим Readme.md из репозитория внутри страницы XWiki. Cразу дам дисклеймер - я техпис, а не программист. Поэтому не стоит ожидать в стать хороших примеров кода и удачных решений. Это скорее материал для других технических писателей или может быть docops, которым  выпадет честь работать с XWiki. Уделим пару минут очевидному: Для туториала нам понадобится аккаунт в Gitlab (не важно коммерческий или на вашем сервере). Нужно будет получить access token к аккаунту. Нужен будет репозиторий, я использую "Learn GitLab" (не помню откуда он у меня взялся). Но вам подойдет любой репозиторий в котором есть Readme.md (или другой markdown файл). Логика будет похожей. В своей статье я использовал docker версию XWiki 13.10.5 со Standart Flavor, но работать будет и в XWiki 12.X.  Нам понадобится установить расширение GitAPI. Ну и самое главное, нам нужно будет установить расширение поддержки синтаксиса Markdown. . Вообще у Xwiki есть разные варианты интеграции с git, например импорт с GitHub wiki или вот просто подключение к GitHub через его API. Возможно Вам удастся найти готовые примеры и решения. Сразу скажу, что в этот раз мы сделаем очень топорный макрос, его прообраз  мне был нужен для того чтобы коллегам не пришлось добавлять домен с XWiki в настройки CORS нашего GitLab. Прошу вас рассматривайте этот туториал скорее как демонстрацию, а не как четкое руководство к действию, потому что клонировать целый репозиторий на сервер XWiki ради 1 markdown файла может быть не лучшей идеей.  Пару слов о том, что такое макрос.  Макрос в Xwiki - это набор инструкций, который может быть включен в контент страницы. Если вы использовали Conflunce, то вам это знакомо. Создать свой макрос в XWiki очень просто, для этого надо следовать инструкции. Для начала создадим новую страницу, можно прямо в корне. Название страницы не критично, контент можно не размещать. Но если вы возьметесь за дело всерьез, то я бы рекомендовал размещать макросы в каком-то одном месте (например, внутри страницы "Macros"). Далее перейдите в редактор объектов. Можно просто нажать латинскую клавишу "O" на странице после её создания (если чудо не произошло, посмотрите как включить продвинутый режим редактора в одной из прошлых статей). Страница станет макросом, как только мы добавим ей объект WikiMacroClass Это по сути и есть сам макрос, но прежде, чем перейти к его детальному описанию, добавим еще несколько объектов с переменными для макросаWikiMacroParameterClass на страницу. Создайте 6 объектов с переменными, они позволят нам управлять макросом из пользовательского интерфейса. Первый разберем подробнее, а остальные я дам скриншотами ниже. Мы задаем путь к репозиторию в git.  Название параметра  (GIT_URL), то как будет называться поле в UI пользователя. Описание параметра - текст подсказки к параметру (ссылки работать не будут). Обязательность параметра - если да, то макрос не создаться без ввода значения. В первом случае параметр обязательный. Значение по умолчанию, если задать, то поле будет предзаполненно. Тип параметра - формат переменной, я так понимаю основные типы JAVA работают нормально, в данном случае String. Если честно, я уже точно не помню, как это работает, поэтому оставим так. Скриншоты с другими параметрами я спрячу под спойлер, чтобы не раздувать статью.  Если боитесь, что что-то забыли можно проверить себя на скриншоте UI макроса в редакторе страницы. Так же страничку можно забрать из GitHub (вы можете её импортировать через панель администратора в разделе "Контент"). Вернемся к Макросу. ID макроса - то как он будет называться в режиме редактора исходного кода. Название макроса - то как будет отображаться в UI пользователя. Описание - подсказка для пользователя. Категория - категория для фильтров по типам макросов. Можно ли вставить  в линию - если нет, то нужен будет отступ в редакторе исходного кода. Видимость макроса - в каких границах можно использовать (у нас в рамках текущей вики). Можно ли вставить контент в макрос - в нашем случае нет. Тип контента - выберите Wiki. Осталось загрузить непосредственно код макроса. На всякий случай сохраните ваш труд и вздохните с облегчением. Перейдем непосредственно к коду.  В целом я не на 100% понимаю этот код, так как часть решений заимствовал. Но постараюсь объяснить что смогу. Импортируем зависимости. Функция для авторизации в GitLab,  замените UХХХХ на имя пользователя, а glXX-XXX на access token.  Эта функция, как я понимаю непосредственно клонирует репозиторий. Сохраняем и обрабатываем параметры с URL из параметров макроса. Если включен параметр "Удалять папку", то мы ее удаляем. ../xwiki/data/git/ - я уже плохо помню, но скорее всего это относительный путь, куда Xwiki  по умолчанию складывает репозитории. Получаем данные из репозитория и сохраняем их в переменную. Отправляем содержимое переменной в общий контекст, чтобы забрать из макроса на Velocity. По идее это не обязательно, так как должен был сработать обмен переменными между языками, но у меня что-то пошло не так. На этом кусок Groovy кода заканчивается.  И начинается небольшой кусочек кода на Velocity. Код на Velocity нам нужен потому, что из него можно вызывать другие макросы XWiki,  в данном случае макрос Content, который позволит нам отобразить наш текст в выбранном формате. Обратите внимание, как вставляется переменная макроса (OUTFORMAT) в Velocity. Кстати переменные макроса было не обязательно писать с больших букв, это моя прихоть. Ну вот и всё. Остается сохранить и проставить настройки как на скриншоте. Создадим еще страницу и разместим на ней наш свеженький макрос. Сохраняем результат и проверяем. Обратите внимание, что все относительные пути в ссылках и у картинок, сломаются. Лучше использовать абсолютные. Ну вот и всё. Я понимаю, что пример получился не самым лучшим, потому что я уже сам подзабыл как работает часть кода и полей, но он демонстрирует разные приемы работы с XWiki и надеюсь, что будет кому-то полезен в условиях недостатка документации на русском языке. P.S. Изначально вместо этой статьи я хотел написать материал о моём субъективном опыте одновременного использования XWiki и Confluence в качестве базы знаний для команды разработки. Однако, в итоге решил, что человечество к такому пока еще не готово. Но если вы все же хотите почитать материал на тему Confluence vs Xwiki напишите об этом в комментариях.  Технический писатель / системный аналитик