Docs Maven Skin

A minimalist and responsive Bootstrap-based HTML5 skin for Maven Site, which will help to use it as a documentation site.

It is easy to use, just remember to check the documentation to find out how to set it up, and to find out how the skin looks in an actual Maven Site. New projects may as well make use of the Library Maven Archetype which, among other features, makes use of this skin and shows how it is configured.

The skin has been adapted from the static template Docs Bootstrap Template, which will be the visual reference to be followed by this project.

Maven support: the skin only supports the Maven Site Plugin 3.6 onwards, due to changes to the way the velocity tools are loaded.

Features

Minimalist and reactive look
HTML5
Bootstrap 3
Font Awesome icons
highlight.js for syntax highlighting
Prepared for Facebook's Open Graph and Twitter Cards

Demo

To check the Docs Maven Skin at work take a look at the documentation, linked below this section, which is a Maven Site making use of this skin.

Documentation

Documentation is always generated for the latest release, kept in the 'master' branch:

The latest release documentation page.

Documentation is also generated from the latest snapshot, taken from the 'develop' branch:

The the latest snapshot documentation page.

The documentation site sources come along the source code (as it is a Maven site), so it is always possible to generate them using the following Maven command:

$ mvn verify site

The verify phase is required, as otherwise some of the reports won't be created.

Acknowledgement

The project started as a fork of the Reflow Maven Skin, but it quickly became its own thing. Still, it owes much to that project.

Usage

The project is coded in Velocity Template Language, using Maven to manage the project.

It also requires Maven to be used, being set up as a Maven Skin for the Maven Site of any other Maven-based project.

Prerequisites

As a Maven Skin, the project requirements are very specific:

Maven
Maven Site plugin (>=3.6)
Maven Site enabled

Installing

The recommended way to install the project is by setting up your preferred dependencies manager. To get the configuration information for this check the Bintray repository, or the Maven Central Repository.

If for some reason manual installation is necessary, just use the following Maven command:

$ mvn install

Setting up the skin

To use the Skin when generating a Maven Site just add the following to the site.xml file:

<skin>
    <groupId>com.bernardomg.maven</groupId>
    <artifactId>docs-maven-skin</artifactId>
    <version>[current version]</version>
</skin>

More detailed information can be found in the docs.

Running tests

Several integration tests are included in the project, verifying various configurations. These can be run by using the usual Maven command:

$ mvn verify

They are run by using the Maven Invoker Plugin, and the configurations are included in the 'src/it' folder.

Pay attention that the results from generating these tests are copied to the generated Maven Site by the Maven Resources Plugin.

If using Eclipse the tests may not run, due to an incompatibility with the invoker. It is recommender running the tests through command line.

Collaborate

Any kind of help with the project will be well received, and there are two main ways to give such help:

Reporting errors and asking for extensions through the issues management
or forking the repository and extending the project

Issues management

Issues are managed at the GitHub project issues tracker, where any Github user may report bugs or ask for new features.

Getting the code

If you wish to fork or modify the code, visit the GitHub project page, where the latest versions are always kept. Check the 'master' branch for the latest release, and the 'develop' for the current, and stable, development version.

License

The project has been released under the MIT License.

Jeff-Walker / docs-maven-skin