Manual Site Deployment to GitHub
Unfortunately the Mojo Codehaus organization has closed their doors. In consequence all projects had to move to a new home. The Mojo Codehaus Maven plugins had to move as well so after the transition of the code etc. onto Github and the newly created The MojoHaus organization we need to get all the sites back online which contains the documentation of the plugins.
During the transition the Subversion repositories have been migrated to Git repositories.
So now the questions how to get back the old documentation and which approach should be followed to make further deployment of the site to GitHub pages as simple as possible.
The original approach to deploy maven sites was to use a WebDAV access to the Codehaus infrastructure which unfortunately was a little bit slow. So now we are on Github and can improve those things.
But the first thing is to get back the documentation sites of all the migrated plugins so the users have a chance to read the documentation.
So the following things have to be done:
- How to regenerate all the plugin sites of the migrated plugins?
- How to make site deployment as simple as possible for plugin maintainers?
Unfortunately the first step has to be made manually. So first we need to make a clone of the plugin we want to regenerate the site.
1 2 3 4 5 6 7 8
You can look which releases have been created:
1 2 3 4 5 6 7
So to get the latest version of the documentation online we have to checkout
the state of the latest release which is in this case
So next is to generate the site documentation by the appropriate call.
This will result in the appropriate documentation in
target/site. So now it is
best to create the appropriate
gh-pages branch for taking the content of the site.
Afterwards you have to clean up the folders and remove everything except the
target folder and copy the content of the generated site. But do not forget
to add a
.gitignore file to prevent adding the
1 2 3
and finally you have to commit and push the site to GitHub.
After a few seconds the content should be available and for MojoHaus you can access now the documentation for the plugin.
Automatic Site Deployment to GitHub
So let us take a look onto the second step and see how to improve the site deployment
for further development at MojoHaus
The first thing you need to do is to add an approriate
1 2 3 4 5 6
Apart from the above you have to use the maven-site-plugin in version 3.4 Furthermore you have to add the following supplemental configuration for maven-site-plugin:
1 2 3 4 5 6 7 8 9 10 11
This is needed to calculate the correct root location if you do
mvn site:stage. A symptom
of missing the above configuration is having a folder
which contains the generated site instead of
So now we would like to transfer the site content to GitHub via the maven-scm-publish-plugin.
Getting this to we need to add the configuration for maven-scm-publish-plugin like the following.
In this case we define
scmBranch to point to
gh-pages which is the default branch where GitHub
serves content from. This might be changed if you are on the organization level where the
branch is used for that.
1 2 3 4 5 6 7 8 9 10 11 12 13 14
So now it is easy to deploy the site to GitHub simply by using the following:
If you have a multi-module project you have to separate the steps a little bit like this:
To simplify your work you could add a little script which contains the above two steps and finally you can call the script.
Ah not to miss things here. The configuration of the distributionManagement must be done in every single plugin but the configuration for maven-site-plugin and maven-publish-scm-plugin could be moved into a parent pom (like mojo parent) to simplify configuration of plugins.