В рамках продолжения работ по плагину FreeMarker для MyBatis нужно было сделать сайт проекта, по аналогии с тем, как это сделано у mybatis-velocity. С сайтами такого рода я сталкивался неоднократно, но до этого не задумывался о том, как такие сайты делаются. Поэтому пришлось «реверсить» метод создания сайта. Посмотрев на верстку и погуглив, я обнаружил, что это – результат выполнения команды mvn site. Однако на исходниках mybatis-velocity эта команда почему-то выдавала другой результат: сайт был похож, но стили были старые, отсутствовал логотип, и не было целой группы разделов «Project Reports». Допустив, что часть конфигурации находится в родительском pom.xml и берётся откуда-то из другого места, я стал шаманить с конфигами, пытаясь добиться, чтобы mvn site выдавал точно такой сайт, который был выложен на github-pages. Через некоторое время мне это удалось, и я сделал всё по аналогии для своего проекта. И заодно решил написать гайд по тому, как это сделать.

Итак, в мавне есть встроенный механизм для генерации шаблонных сайтов проектов. В сгенерированном сайте автоматом будет инфа о полученном артефакте, о том, какие зависимости у него есть, как прописать артефакт к себе в pom.xml, список участников проекта, и ещё много разных отчётов. По умолчанию список генерируемых отчётов весьма велик, его можно уменьшить, а можно добавить ещё 🙂 Для того, чтобы вся балалайка завертелась, нужно запилить site.xml. В нём прописываются настройки меню, внешнего вида сайта. Можно выбрать плагин для стилей – по умолчанию будет старенький стиль, fluido на бутстрапе выглядит поприкольнее. В папке xdocs уже пишется сам контент. Формат простой и интуитивно понятный – я за полчаса по аналогии забацал свою страничку «Getting started». Одно тонкое место – чтобы избежать лишних пробелов до и после кодовой разметки, нужно чтобы не было пробелов между тегами <source/> и собственно исходным кодом. Ну и очень желательно уметь использовать <![CDATA[]]>.

Далее, дополнительные плагины. Очень рекомендую встроить javadocs. Это, думаю, самое полезное. Для того, чтобы отчёт сгенерился вместе с остальными, достаточно добавить его в <repoting/>. У меня был какой-то баг при генерации джавадоков, почему-то не компилировались классы из test. Пришлось заигнорить goal javadoc-test.

После того, как мавно сделает вам сайт, вы можете его просто залить на GitHub Pages – либо в отдельный репозиторий, либо в этот же проект веткой gh-pages.

В остальном проще не расписывать подробно, что к чему, а просто дать ссылку на пример того, как это настроено в моём случае: https://github.com/elw00d/mybatis-freemarker. Можно просто копировать конфиги и изменять по своему усмотрению.