Maven

Chain plugins

Mojo can be chained from the command like - without pom declaration.

This is the case of the git report one and PDF one for example:

mvn \
    io.yupiik.maven:yupiik-tools-maven-plugin:$version:git-report \
    io.yupiik.maven:yupiik-tools-maven-plugin:$version:pdf \
    -Dyupiik.workDir=work \
    -Dyupiik.git-report.dotGit=/path/to/project/.git \
    -Dyupiik.git-report.target=log.adoc
    -Dyupiik.pdf.source=log.adoc \
    -Dyupiik.pdf.target=.

PDF and latex formula

You can enable latex formula support in PDF adding the related dependency:

<plugin>
  <groupId>io.yupiik.maven</groupId>
  <artifactId>yupiik-tools-maven-plugin</artifactId>
  <configuration>
    <!-- ... -->
  </configuration>
  <dependencies>
    <dependency>
      <groupId>org.scilab.forge</groupId>
      <artifactId>jlatexmath</artifactId>
      <version>1.0.7</version>
    </dependency>
  </dependencies>
</plugin>

Then usage is as follow:

[jlatexmath]
--
x = a + b
--

This formula (jmath:_[a + b]) is cool.

Pom-less PDF rendering

You can render an asciidoctor file without a pom nor pom declaration:

mvn \
  io.yupiik.maven:yupiik-tools-maven-plugin:$version:pdf \
  -Dyupiik.pdf.source=content.adoc \
  -Dyupiik.pdf.target=.

Minisite

minisite can push the minisite to a remote target (often git backed pages).

TIP	as all plugins it requires Java 11 but if you want to use it with Java 8 you can use `minisite-core` module with `exec-maven-plugin` since version 1.1.1.

Here is the related documentation.

The configuration supports a git entry if you want to upload to a Git branch the generated website (like gh-pages):

Name Type Description

branch String Git branch to update (default to `refs/heads/gh-pages`).

username String Username if serverId is not set.

password String Password if serverId is not set.

serverId String ServerID to use to get username/password from settings.xml - default to `project.scm.url`. If not set it fallbacks on the git url host. If using a git url which is a SSH one, you can set passphrase and privateKey location in the server.

url String Git url.

ignore boolean Should the execution be skipped - enables to set a maven variable.

prefix String Prefix prepended to file in the git repo (ex: `public/`).

noJekyll boolean Will force a `.nojekyll` file presence if `true`.

envBase64SshKey String Environment variable the private key will be read as base64 encoded from - useful on CI. note that `<value>_PH` environment variable must contain the associated passphrase.

Name	Type	Description
branch	`String`	Git branch to update (default to `refs/heads/gh-pages`).
username	`String`	Username if serverId is not set.
password	`String`	Password if serverId is not set.
serverId	`String`	ServerID to use to get username/password from settings.xml - default to `project.scm.url`. If not set it fallbacks on the git url host. If using a git url which is a SSH one, you can set passphrase and privateKey location in the server.
url	`String`	Git url.
ignore	`boolean`	Should the execution be skipped - enables to set a maven variable.
prefix	`String`	Prefix prepended to file in the git repo (ex: `public/`).
noJekyll	`boolean`	Will force a `.nojekyll` file presence if `true`.
envBase64SshKey	`String`	Environment variable the private key will be read as base64 encoded from - useful on CI. note that `<value>_PH` environment variable must contain the associated passphrase.

The configuration also supports an experimental Atlassian Confluence export support. It only works using the default template and require a configuration similar to git or ftp exports:

<profile> <!--  mvn clean package -Pconfluence  -->
  <id>confluence</id>
  <build>
    <plugins>
      <plugin>
        <groupId>io.yupiik.maven</groupId>
        <artifactId>yupiik-tools-maven-plugin</artifactId>
        <executions>
          <execution>
            <id>confluence</id>
            <phase>prepare-package</phase>
            <goals>
              <goal>minisite</goal>
            </goals>
            <configuration>
              <confluence>
                <ignore>false</ignore>
                <url>https://base.atlassian.net/wiki/</url> <!-- for cloud, for an on premise instance the /wiki/ is not always needed -->
                <authorization>Basic base64_value_of(your mail:your token)></authorization>
                <space>YOURSPACE</space>
                <skipIndex>false</skipIndex> <!-- if true, will skip all index.html files -->
              </confluence>
            </configuration>
          </execution>
        </executions>
      </plugin>
    </plugins>
  </build>
</profile>

IMPORTANT

the nested support of this exporter is very experimental, and we recommend you to keep only one level of .adoc files using it.

Confluence Limitations

Assets are not uploaded so ensure to configure Asciidoctor to embed all assets in HTML,
It only works with the default theme since we extract metadata from there to enable to update the space,
To look nice, you can need to tune the Confluence space CSS to import admonitions, codeblocks, ... styling (can require some admin permissions).

Blog

Blog is supported if pages contain at least one block metadata. Here is the list of available attributes you can use:

:minisite-blog-published-date: yyyy-MM-dd: when the page will be rendered (if not set it is always rendered).
:minisite-blog-categories: c1,c2: comma separated list of categories of this post
:minisite-blog-authors: My, Myself: comma separated list of author names
:minisite-blog-summary: Some short description.: the summary of this post used on post list pages.

Blog page example:

= My Post
:minisite-blog-published-date: 2021-02-16T16:00
:minisite-blog-categories: others,simple
:minisite-blog-authors: Romain Manni-Bucau
:minisite-blog-summary: Second post.

Bla bla

Pre-Action

Pre actions enables to generate some content from the project. It is typically used to generate configuration from code or things like that. It uses the documentation module classpath. Actions must implement Runnable and can have some (public) constructor parameters (we use parameter names to match so ensure to enable -parameters in maven compiler plugin):

configuration (Map<String, String>): the action configuration, it enables to reuse it if needed or write generic actions
sourceBase (Path): the base directory you can generate .adoc into (generally where you sources are, tip: use generated folder to be able to exclude it in .gitignore if desired)
outputBase (Path): the base directory you can generate direct html assets

Maven Plugin

Using type=maven-plugin (recommended) or type=io.yupiik.maven.service.action.builtin.MojoDocumentationGeneration you can get a plugin.xml file parsed to generate:

One file per goal with some usage, the goal description and parameters (named <goal>.adoc)
One file listing all goals (named <goal-prefix>-maven-plugin.adoc)

The configuration of this action is:

pluginXml: file path or resource to find the plugin.xml file.
toBase: where to generate the adoc.
description: a global plugin description for the "listing" page (default is empty and page will just list goals).

Copy

Using type=copy (recommended) or type=io.yupiik.maven.service.action.builtin.CopyFile will copy a file from a source to a destination: It is typically useful for assets (openapi.json for example).

from: source file.
to: destination.

JSON-Schema

Using type=jsonschema (recommended) or type=io.yupiik.maven.service.action.builtin.JsonSchemaGenerator will generate a JSON-Schema from a class:

class: the class to generate the schema from.
to: destination of the schema.
type: JSON for a raw JSON-Schema (default) or ADOC for a textual, asciidoctor output.
setClassAsTitle: true to force object title to be the class name.
useReflectionForDefaults: true to force reflection to try to extract defaults of attributes.
pretty when type=JSON, should the JSON be prettified or not (default=true).
levelPrefix when type=ADOC, a title prefix (== for example), = by default.
title and description enable to set class title/description for its json schema. It is required for type=ADOC.
annotationOnlyProvidesTheDescription enable to never take the title from an annotation (@Description(value) case).

NOTE	the model classes can use a custom `@Description(title,description)` annotation (note that `@Doc` is also supported and `value` method can be used instead of `description`). See `JsonDocExtractor` for more details.

JSON-Schema to asciidoc

Using type=jsonschema2adoc (recommended) or type=io.yupiik.maven.service.action.builtin.JsonSchema2AdocGenerator will generate an asciidoctor document from a JSON-Schema file (intended to be used with fusion mainly):

schema: location of the schema (JSON).
root: key under schemas map of the root schema to generate a doc for.
levelPrefix: prefix to set for title (default =).
output: where to generate the .adoc.

OpenMetrics renderer

Using type=openmetrics2adoc (recommended) or type=io.yupiik.tools.minisite.action.builtin.OpenMetricsToAsciidoc will generate an asciidoctor form from an OpenMetrics export.

source: path of the openmetrics dump.
to: destination of the asciidoc generated from source.
levelPrefix: a prefix set before the part title (== by default for a second level title).
legend: should tables have a legend (name of the metric), default to true.
header: prefix the whole rendering (enables to set a title and some options if needed).

Yupiik Batch simple-configuration renderer

Using type=simple-configuration (recommended) or type=io.yupiik.tools.minisite.action.builtin.SimpleConfigurationGenerator will generate an asciidoctor from a configuration class passed in class <configuration> option.

class: root configuration fully qualified name.
output: where to generate the .adoc to.

Download and Unzip

Using type=download-unzip (recommended) or type=io.yupiik.tools.minisite.action.builtin.DownloadAndUnzip enables to download a zip from a HTTP url then extract it totally or partially to a particular folder. This can be used to download a git repository using Github/Gitlab/Gitea API for example.

url: the zip URL.
subpath: the subpath to copy in target. It filters the zip entries names by prefix.
headers: in properties format, a set of headers to set.
target: where to copy the selected files.
workdir: temporary folder (to download the zip), temporary if not set.

Replace string in file

Using type=replace-in-file (recommended) or type=io.yupiik.tools.minisite.action.builtin.ReplaceInFile will rewrite a text file replacing a string by another one.

source: file to rewrite.
token: text to replace.
replacement: text replacing token.

TIP	using `regex{xxx}` as `token` will use a java regex to do the replacement.

Example

<plugin>
  <groupId>io.yupiik.maven</groupId>
  <artifactId>yupiik-tools-maven-plugin</artifactId>
  <executions>
    <execution>
      <id>build-and-deploy-doc</id>
      <phase>package</phase>
      <goals>
        <goal>minisite</goal>
      </goals>
      <configuration>
        <siteBase>https://yupiik.github.io/${project.artifactId}</siteBase>
        <logoText>My Product</logoText>
        <indexSubTitle>The top product.</indexSubTitle>
        <ftp>
          <serverId>http://mini.yupiik.net</serverId> <!-- default is siteBase -->
          <url>ftp://ftpupload.net/htdocs</url>
        </ftp>
      </configuration>
    </execution>
  </executions>
</plugin>

Page attributes

Some specific attributes enables to customize the generation. Here is their list:

minisite-skip=[true|false] enables to skip a .adoc rendering even if not in _partials directory.
minisite-path=<string> enables to force the relative path of the file, for example a file name foo-bar.adoc with the attribute minisite-path set to foo/bar.html will output a foo/bar.html file instead of foo-bar.html. Note however it does not rewrite the links to ensure to use link:.....html[] instead of ref to link this page then.
minisite-highlightjs-skip enables to not setup highlight.js for the page (useful with swagger-ui for example).
minisite-nav-prev-label/minisite-nav-next-label enables to add a bottom page "previous"/"next" link to another page, this attribute defines its label.
minisite-nav-prev-link/minisite-nav-next-link enables to add a bottom page "previous"/"next" link to another page, this attribute defines its link (label is required), if label is defined but not the link, the link is the label lowercased with iphens instead of spaces and html extension.
minisite-breadcrumb enables to define a page breadcrumb (navigation tree) at the top of the content. Syntax is the following: :minisite-breadcrumb: Home[#] > Another Page[link-to-another-page.html] > This page. If there is a [xxx], then xxx is considered as a link.

TIP	for a good documentation it is highly recommended to use nav and breadcrumb features.

Index generation

To include a page in the index it must contain minisite-index attribute. Its value is the order of the entry in the index tiles.

TIP	ensure to not use `1`, `2`, `3`, ... but rather `100`, `200`, ... to easily insert an item later.

minisite-index-title attribute enables to override link text.
minisite-index-icon attribute enables to override font awesome icon (without fa- prefix).
minisite-index-description attribute enables to override the text in the index tile for the page entry.

Escaping

When you write some documentation in a language close to the minisite interpolation one (mustache for ex), it can be hard to use. To ease that, you can surround your snippet with and , included text will not support interpolations.

Synchronize Releases Example

<plugin>
  <groupId>io.yupiik.maven</groupId>
  <artifactId>yupiik-tools-maven-plugin</artifactId>
  <executions>
    <execution>
      <id>default-cli</id>
      <phase>none</phase>
      <goals>
        <goal>synchronize-github-releases</goal>
      </goals>
      <configuration>
        <!-- defaults so optional -->
        <githubServerId>github.com</githubServerId>
        <nexusServerId />
        <mavenRepositoryBaseUrl>https://repo.maven.apache.org/maven2/</mavenRepositoryBaseUrl>
        <!-- required configuration -->
        <githubRepository>yupiik/tools-maven-plugin</githubRepository>
        <artifacts>
          <artifact>
            <groupId>io.yupiik.maven</groupId>
            <artifactId>yupiik-tools-maven-plugin</artifactId>
            <artifacts>
              <artifact>
                <type>jar</type>
                <classifier />
              </artifact>
              <artifact>
                <type>pom</type>
                <classifier />
              </artifact>
              <artifact>
                <type>jar</type>
                <classifier>sources</classifier>
              </artifact>
              <artifact>
                <type>jar</type>
                <classifier>javadoc</classifier>
              </artifact>
            </artifacts>
          </artifact>
        </artifacts>
      </configuration>
    </execution>
  </executions>
</plugin>

Then run mvn yupiik-tools:synchronize-github-releases.

Bash CLI skeleton

script-cli-skeleton enables to generates a skeleton layout to write a CLI in bash (helper commands for your project).

TIP	can be used on a pomless project: `mvn io.yupiik.maven:yupiik-tools-maven-plugin:<version>:script-cli-skeleton -Dyupiik.script-cli-skeleton.directory=/path/to/script-project` (version >= 1.0.26).

Usage

To add a command:

Create an index.sh containing the command script in commands folder
(optional) create a commands/<your command name>/_cli/help.txt file containing the help description.

Maven Asciidoctor Macro

The project adds asciidoc macros to get back some maven build information. Note that it must be executed in the right lifecycle phase if using some project metadata (plugin does not require any resolution to be usable standalone).

maven_dependencies

Enables to list the project dependencies.

Usage

[maven_dependencies,scope=compile]
--
--

Scope can be:

- compile - runtime - compile+runtime - runtime+system - test - provided_only - compile_only - test_only - system_only - runtime_only

The optional attribute groupId is also supported and take a list (comma separated) of groupId to include.

Simple Dependencies

simple-dependencies is a trivial and simple alternative to maven-dependency-plugin:list mojo which outputs the data in JSON.

It is convenient with minisite mojo to format with a custom action the dependencies according to a custom need.

Yupiik OSS extension

This extension sets up the equivalent of a parent pom but enables to inherit or not from another parent and to benefit from upgrades for free.

It is configured in the root project through maven properties:

<properties>
  <!-- REQUIRED: enable the extension -->
  <yupiik.oss.enabled>true</yupiik.oss.enabled>
  <!-- OPTIONAL: defaults -->
  <yupiik.oss.java.version>11</yupiik.oss.enabled>
  <yupiik.oss.encoding>UTF-8</yupiik.oss.enabled>
  <yupiik.oss.javadoc.doclint>none</yupiik.oss.enabled>
  <yupiik.oss..sign.skip>none</yupiik.oss.enabled>
</properties>

Just enabling this extension will upgrade a few plugin, enforce the encoding and java version, enforce license check and much more.

See io.yupiik.maven.extension.YupiikOSSExtension.afterProjectsRead for details.

Example

<project xmlns="http://maven.apache.org/POM/4.0.0"
         xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
         xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd">
  <modelVersion>4.0.0</modelVersion>

  <!-- ... -->

  <properties>
    <yupiik.oss.enabled>true</yupiik.oss.enabled>
  </properties>

  <build>
    <extensions>
      <extension>
        <groupId>io.yupiik.maven</groupId>
        <artifactId>yupiik-tools-maven-plugin</artifactId>
        <version>${yupiik-tools.version}</version>
      </extension>
    </extensions>
  </build>

  <profiles>
    <profile>
      <id>release</id>
    </profile>
  </profiles>
</project>

Inline pom contributor extension

It enables to put in each module a YupiikContributor.java file which will be compiled and executed in afterProjectRead(MavenSession) callback.

Example:

import org.apache.maven.AbstractMavenLifecycleParticipant;
import org.apache.maven.execution.MavenSession;
import org.codehaus.plexus.component.annotations.Component;

@Component(role = AbstractMavenLifecycleParticipant.class, hint = "my-module-customizer")
public class YupiikContributor extends AbstractMavenLifecycleParticipant {
    @Override
    public void afterProjectsRead(final MavenSession session) {
        System.out.println(">>>> hello: " + session);
    }
}

This enables to programmatically handle the pom (mainly intended for plugins since dependencies are not synchronized in maven poms when contributed this way).

To enable it, enable the related extension:

<build>
  <extensions>
    <extension>
      <groupId>io.yupiik.maven</groupId>
      <artifactId>yupiik-tools-maven-plugin</artifactId>
      <version>${yupiik-tools-maven-plugin.version}</version>
    </extension>
  </extensions>
</build>

TIP	see `io.yupiik.maven.extension.YupiikOSSExtension` for a more complex participant example.

Crypt mojos

Crypt mojos are intended to encrypt/decrypt (using AES/CBC/PKCS5Padding algorithm - like maven default encryption ) values. It supports either inline values or properties files.

TIP	it is a neat way to handle secrets in a bundlebee placeholder properties file on CI/CD if you don't have a vault or equivalent mecanism for GitOps.

Value based mojo

yupiik-tools:crypt-value will enable to encrypt a value (symmetrically, decrypt-value will decrypt a value).

Configuration is:

value: the value to crypt (decrypt),
useStdout: should the value be printed using Maven logger or simply stdout,
masterPassword: the master password for the ciphering.

Properties based mojo

yupiik-tools:crypt-value will enable to encrypt a value (symmetrically, decrypt-value will decrypt a value).

Configuration is:

input: path to the properties file to crypt (decrypt) values for (keys are never encrypted),
output: path to the properties file which will contain encrypted (decrypted) data,
masterPassword: the master password for the ciphering,
includedKeys: a list of values (direct key), start:<some prefix> prefixes or regex:<pattern> regex to filter the values to encrypt (decrypt) based on their keys,
excludedKeys: a list of values (direct key), start:<some prefix> prefixes or regex:<pattern> regex to filter the values to NOT encrypt (decrypt) based on their keys.

IMPORTANT

output always sorts the keys and will ignore comments. An already encoded value will not be re-encoded. This last point enables to set input=output to encrypt in place a file.

Menu

Maven Plugin

Chain plugins

PDF and latex formula

Pom-less PDF rendering

Minisite

Confluence Limitations

Blog

Pre-Action

Maven Plugin

Copy

JSON-Schema

JSON-Schema to asciidoc

OpenMetrics renderer

Yupiik Batch simple-configuration renderer

Download and Unzip

Replace string in file

Example

Page attributes

Index generation

Escaping

Synchronize Releases Example

Bash CLI skeleton

Usage

Maven Asciidoctor Macro

maven_dependencies

Usage

Simple Dependencies

Yupiik OSS extension

Example

Inline pom contributor extension

Crypt mojos

Value based mojo

Properties based mojo

Navigation