Docsite Maven Plugin

A Maven plugin that generates static documentation sites

Usage

Include the following snippet in your pom.xml file before using the plugin:

<build>
    <plugins>
        <plugin>
            <groupId>io.github.luiinge</groupId>
            <artifactId>docsite-maven-plugin</artifactId>
            <version>1.5.2</version>
            <configuration>
                ...
            </configuration>
        </plugin>
    </plugins>
</build>

Below there is a list of available goals provided by this plugin:

Goal	Description
docsite:aggregate
docsite:generate

Goals

docsite:aggregate

Parameters

cssFile

A local CSS file that would be used instead of the default style, in case you want to use a totally different layout.

Type: java.io.File
Required: false
User property: docsite.cssFile
Since: 1.0

docsite

Defines the site structure. If omitted, a default site structure would be use instead.

<title></title>
<description></description>
<logo></logo>
<companyLogo></companyLogo>
<companyLink></companyLink>
<favicon></favicon>
<index></index>
<sections>
    <section>
        <name></name>
        <description></description>
        <icon></icon>
        <source></source>
        <type></type>
        <siteIndex></siteIndex>
        <template></template>
        <replaceEmojis></replaceEmojis>
        <subsections>
            <section>
                ...
            </section>
            ...
        </subsections>
    </section>
    ...
</sections>

`title`	Title of the site. Used in page headers and metadata.	Required
`description`	Brief description of the site. Used in page headers and metadata.
`logo`	File image or Font Awesome icon. Used in page headers.
`companyLogo`	File image. Used in page headers.
`companyLink`	URL link. Used in page headers.
`favicon`	File image. Used by browsers as the page icon.
`index`	Document file (Markdown, HTML or raw text) that would be the landing page.	Required
`sections`	Main sections of the page. Used in the header navigation menu.

Section properties:

`name`	Name of the section. Used in menus, breadcrumbs and metadata.	Required
`description`	Brief description of the section. Used in metadata.
`icon`	File image or Font Awesome icon. Used in menus.
`type`	Type of the section.	`generated` `embedded` `copy` `group` `link`
`source`	Document file used as the site contents. Not used when `type` is `group`
`siteIndex`	Main page of the embedded site. Required used when `type` is `embedded`
`template`	A Freemarker template file. Only used when `type` is `generated`
`replaceEmojis`	Set whether Github emoji markups would be replaced by images	`true` (default) `false`
`subsections`	Sub-sections of the section. Only used when `type` is `group`

Type: docsite.Docsite
Required: false
Since: 1.0

docsiteFile

A JSON file containing the object structure of the docsite (instead of including it in the pom)

Type: java.io.File
Required: false
User property: docsite.docsiteFile
Since: 1.2

forceDelete

Forces deletion of output folder.
A safety mechanism is implemented in order to prevent accidental deletion of directories, but setting this property to true will bypass such feature.

Type: boolean
Required: false
Default value: false
User property: docsite.forceDelete
Since: 1.0

languages

The provided language translations for the site. You can also define the country flag representing the language using the expression language:country, being country a ISO 3166-1 alpha-2 code.

First language would be the default.

Type: java.lang.String[]
Required: false
User property: docsite.languages
Since: 1.3

localizationFile

A JSON file containing the translations for section names and descriptions (given that they are provided with keys instead of literals).

The content of the file must abide by the following structure:


    {
        "language-a": {
            "key-a":"translation-a",
            "key-b":"translation-b",
            ...
        },
        "language-b": {
          ...
        },
        ...
    }

Type: java.io.File
Required: false
User property: docsite.localizationFile
Since: 1.3

localizations

The translations for section names and descriptions (given that they are provided with keys instead of literals).

The content must abide by the following structure: language-a value-a value-b ...

Type: docsite.Localization[]
Required: false
Since: 1.3

metadata

Set extra metadata that would be included in the head section.

<metadata>
  <keyA>valueA</keyA>
  <keyB>valueB</keyB>
  ...
</metadata>

Type: java.util.Map
Required: false
Since: 1.1

outputFolder

The folder where the documentation site would be generated.

Type: java.io.File
Required: true
Default value: ${project.build.directory}/docsite
User property: docsite.outputFolder
Since: 1.0

scripts

Set scripts that would be included in the head section

<scripts>
 <script>
    <src>https://remote-script.js</src>
    <async>true</async>
 </script>
 <script>
    <code>
      // JS code
      // ...
    </code>
 </script>
</scripts>

Type: docsite.Script[]
Required: false
Since: 1.1

themeColors

Set a custom color theme that would be applied to the site. Value formats accepted are defined by CSS colors.

<themeColors>
  <menuRegularBackgroundColor></menuRegularBackgroundColor>
  <menuBoldBackgroundColor></menuBoldBackgroundColor>
  <menuForegroundColor></menuForegroundColor>
  <menuDecorationColor></menuDecorationColor>
  <guiElementColor></guiElementColor>
</themeColors>

Type: docsite.ThemeColors
Required: false
Since: 1.0

useCDN

Set whether the site uses CDN (Content Delivery Network) for some resources

Type: boolean
Required: false
Default value: true
User property: docsite.useCDN

Mojo Details

aggregator	false
executionStrategy	once-per-session
goal	aggregate
implementation	docsite.mojo.AggregateMojo
inheritedByDefault	true
instantiationStrategy	per-lookup
language	java
phase	post-site
requiresDirectInvocation	false
requiresOnline	false
requiresProject	true
requiresReports	false
threadSafe	false

docsite:generate