Maven site generation using advanced Markdown?

Question

We are using Markdown in our Maven generated site. Works like a charm. AFAIK the plugin uses Flexmark under the hood, which supports the Admonition extensions.

We would like to use them too, the infoboxes are quite helpful for documentation. Our site configuration in the pom.xml looks like this:

<plugin>
    <groupId>org.apache.maven.plugins</groupId>
    <artifactId>maven-site-plugin</artifactId>
    <version>3.8.2</version>
</plugin>

How could we configure it to recognise the additional markdown?

score 2 · Accepted Answer · answered Jan 08 '22 at 04:37

This question is a little old but I have been trying to figure this out for using the Gitlab extension for math equations and the short answer is I don't think you can do it out of the box.

The maven-site-plugin uses the doxia-module-markdown module for markdown which uses Flexmark internally but it is pre-configured with the extensions that it uses for this.

Here's a link to the code and the exact snippet from

// Initialize the Flexmark parser and renderer, once and for all
static
{
    MutableDataSet flexmarkOptions = new MutableDataSet();

    // Enable the extensions that we used to have in Pegdown
    flexmarkOptions.set( com.vladsch.flexmark.parser.Parser.EXTENSIONS, Arrays.asList(
            EscapedCharacterExtension.create(),
            AbbreviationExtension.create(),
            AutolinkExtension.create(),
            DefinitionExtension.create(),
            TypographicExtension.create(),
            TablesExtension.create(),
            WikiLinkExtension.create(),
            StrikethroughExtension.create()
    ) );

// ...
}

I think that you could possibly fork this project, add the extensions you need, and add it as a dependency to the maven-site-plugin and it might work like this:

<plugin>
    <groupId>org.apache.maven.plugins</groupId>
    <artifactId>maven-site-plugin</artifactId>
    <version>3.8.2</version>
    <dependencies>
        <dependency>
            <groupId>${my-forked-groupId}</groupId>
            <artifactId>${my-forked-artifactId}</artifactId>
            <version>${my-forked-version}</version>
        </dependency>
    </dependencies>
</plugin>

This in my opinion is less than ideal and I will probably be exploring other (non-maven) options to get the result I'm looking for but will probably still try this out in the next day or so and if I get it working I'll send a link to the code in case anybody else can benefit from it.

So I did try out what I mentioned above, forked the repository and added the Gitlab extension to flexmakrOptions, and then updated the dependencies to the maven-site-plugin. This actually worked pretty well. — Sam F, Jan 12 '22 at 01:58

Maven site generation using advanced Markdown?

1 Answers1