cobhimself / docs-maven-skin

Minimalist HTML5 and Bootstrap based Maven Skin for using Maven Site as a documentation site.

Docs Maven Skin

A minimalist and responsive Bootstrap-based HTML5 skin for Maven Site, which will help to create documentation sites with Maven.

It is easy to use, just remember to check the project documentation to find out how to set it up, and also 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, takes advantage of this skin and shows how to set it up.

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 4
• Font Awesome icons
• highlight.js for syntax highlighting
• Prepared for Facebook's Open Graph and Twitter Cards

Demo

The project documentation makes use of the skin, it is always built with the latest release available. You can check the links just below this section.

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

As any Maven Skin it is handled through the Maven Plugin. Check the docs for more concrete information.

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

Reducing the Dependency Scope

Actually you won't need to add the skin as a dependency to your project, just to the Maven site plugin:

<build>
    <plugins>
        ...
        <plugin>
            <groupId>org.apache.maven.plugins</groupId>
            <artifactId>maven-site-plugin</artifactId>
            <dependencies>
                ...
                <dependency>
                    <!-- Docs Maven Skin -->
                    <groupId>com.bernardomg.maven.skins</groupId>
                    <artifactId>docs-maven-skin</artifactId>
                    <version>${site.skin.version}</version>
                </dependency>
                ...
            </dependencies>
            ...
        </plugin>
        ...
    </plugins>
</build>

Setting Up the Skin

Before creating the site register the skin into the site.xml file:

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

More detailed information can be found in the documentation.

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.