Allow templates directory to be specified for Maven Site plugin

[mojavelinux]

Allow the templates directory to be specified in the configuration of the Maven Site plugin.

ORIGINAL DESCRIPTION: Select a standard directory where Asciidoctor templates are stored and enable the templates option when calling the convert method if this directory exists and contains files. This avoids the need to have to define the templates directory explicitly and allows templates to be used with the Maven Site plugin.

[mojavelinux]

I propose the following two locations:

• src/docs/asciidoc/_templates
• src/site/asciidoc/_templates

I'm open to other ideas.

[LightGuard]

Is there a standard config directory for maven projects?

On Friday, November 27, 2015, Dan Allen notifications@github.com wrote:

I propose the following two locations:

• src/docs/asciidoc/_templates
• src/site/asciidoc/_templates

I'm open to other ideas.

—
Reply to this email directly or view it on GitHub
#179 (comment)
.

Sent from Gmail Mobile

[AlexanderZobkov]

I would propose to store Asciidoc templates in the following directories:

• ${basedir}/src/main/asciidoc/templates
• ${basedir}/src/site/asciidoc/templates

IMHO the "underscore" symbol looks extraneously for maven world, typical maven projects and typical directories layouts used by developers.
Regarding "src/docs", this is not in alligment with default directory for "sourceDirectory" configuration option:

• defaults to ${basedir}/src/main/asciidoc

[LightGuard]

src/main/asciidoc makes more sense for templates or extensions.

On Saturday, November 28, 2015, Alexander notifications@github.com wrote:

I would propose to store Asciidoc templates in the following directories:

• ${basedir}/src/main/asciidoc/templates
• ${basedir}/src/site/asciidoc/templates

IMHO the "underscore" symbol looks extraneously for maven world, typical
maven projects and typical directories layouts used by developers.
Regarding "src/docs", this is not in alligment with default directory for
"sourceDirectory" configuration option:

• defaults to ${basedir}/src/main/asciidoc

—
Reply to this email directly or view it on GitHub
#179 (comment)
.

Sent from Gmail Mobile

[mojavelinux]

defaults to ${basedir}/src/main/asciidoc

You are correct, that is our current default. I would like to establish a new convention (like the Gradle plugin has done) of src/docs/asciidoc, but that's a separate discussion.

IMHO the "underscore" symbol looks extraneously for maven world

True. I had suggested it because the plugin will ignore directories that start with an underscore, but the templates directory shouldn't have any AsciiDoc files in it, so I guess the underscore isn't necessary anyway.

[mdlinville]

I don't know which is more correct, src/main/site or src/site. I am moving my project to use src/site, because everything besides the site and docs is in a Maven submodule anyway. The Asciidoctor site does not seem to work now when the docs are in src/main/site/asciidoc but it does seem to work when the docs are in src/site/asciidoc. So maybe that should be taken into account.

[mojavelinux]

@mstanleyjones That's correct, the convention for Maven Sites is src/site. I can't remember if there's a way to change that, but given it's such a strong convention, it's probably safe to follow it.

[mojavelinux]

Let's just use:

• ${basedir}/src/site/asciidoc/templates

I suppose we could do something more fancy like:

• ${basedir}/src/main/resources/META-INF/asciidoc/templates

to align with the Maven Site skins, but that just feels excessive.

On a side note, the Maven Site plugin has a configuration block (as do all plugins). There has to be a way to look this up from the Parser class. Does anyone know of a resource that explains how to use DI in the plexus container?

[mojavelinux]

Since I figured out how to read the site plugin's configuration and pass that information to Asciidoctor, I've decided to abandon the original idea (for now) and require the path to be specified using the templateDir option.

<plugin>
    <groupId>org.apache.maven.plugins</groupId>
    <artifactId>maven-site-plugin</artifactId>
    <version>3.3</version> <!-- 3.4 works here too -->
    <configuration>
        <asciidoc>
            <templateDir>src/site/asciidoc/templates</templateDir>
        </asciidoc>
    </configuration>
    <dependencies>
        <dependency>
            <groupId>org.asciidoctor</groupId>
            <artifactId>asciidoctor-maven-plugin</artifactId>
            <version>1.5.3</version>
        </dependency>
    </dependencies>
</plugin>

If the path specified in the templateDir option is not absolute, it will be resolved relative to the project basedir.

[mojavelinux]

I think what I might do is just defer this issue to 1.5.4 since it is still a good idea...it just isn't a blocker anymore.

[mojavelinux]

The more I think about it, the more it just feels like too much magic. I think it's worth being explicit, now that we can do it.