Include pom.xml based version number in github pages?

Question

I have a Java Maven based project on GitHub, where I maintain documentation on GitHub Pages.

In two places I refer to the version number of my maven project. Currently I manually update index.md and readme.md manually with the version number (multiple times on one page).

Is there a way that the version number can have a single source?

One of those:

• Small solution: define it on top of the pages.
• Medium solution: define it once for documentation (challenge: /doc for documentation runs different (?) from readme.md)
• Best solution: read it from pom.xml

Advice is appreciated

Answer 1

There is a way to use the filtering provided by the maven-resources-plugin, but it feels a little hacky to me.

Firstly, any documentation that you want the project version in needs to be placed in a separate place to the final documentation (e.g. a folder called doc-templates). In these files, replace the project version with @project.version@, which is the tag Maven recognises in its filtering step.

Then you can add a plugin configuration that treats the template documents as filtered resources and outputs them into the final documentation location; e.g.:

<plugin>
    <artifactId>maven-resources-plugin</artifactId>
    <executions>
        <execution>
            <id>copy</id>
            <phase>package</phase>
            <goals>
                <goal>copy-resources</goal>
            </goals>
            <configuration>
                <outputDirectory>${basedir}/docs</outputDirectory>
                <resources>
                    <resource>
                        <directory>doc-templates</directory>
                        <includes>
                            <include>file-with-version.md</include>
                        </includes>
                        <filtering>true</filtering>
                    </resource>
                </resources>
            </configuration>
        </execution>
    </executions>
</plugin>

Notice that it sets the output directory for this execution to ${basedir}/docs; ${basedir} resolves to the root directory of the project (where the pom.xml is) for me, so this configuration makes Maven output the resources into your documentation directory.

The advantage of using Maven resource filtering is that you can also include other variables (even system variables!) in the documentation automatically.

You will need to remember to run mvn package before you commit your documentation as any build pipeline that runs maven will also update the documentation but would not commit it (unless you made it do it).

UPDATE: I just realised that if you make the above execution run on <phase>compile</phase> it will update the documentation every time you compile; which means you're less likely to forget to update it before pushing. YMMV.

Answer 2

The problem is that those files are accessed in two different contexts: README.md is only really read on GitHub itself, or in a copy of your repo. The index.md file is converted to a index.html file and viewed on your webpage, after Jekyll processes it.

Small solution: define it on top of the pages.

Again, the problem is that README.md isn't processed into HTML, so adding it to the front matter won't magically add it to the content.

Medium solution: define it once for documentation (challenge: /doc for documentation runs different (?) from readme.md)

You still have the problem of README.md not being processed. It's just basic text.

Best solution: read it from pom.xml

You can't do this from GitHub pages, unless you make pom.xml a post within your Jekyll site. This is almost definitely not what you want to do.

You might be able to find a Maven Jekyll plugin that creates the webpage content for you. If so, then you can probably inject variables from pom.xml to Jekyll. You'd then give up GitHub pages invoking Jekyll for you automatically.

But honestly, it sounds like you're overthinking it a bit. If I were you, I would just keep using the simple workflow of changing it manually. You could use frontmatter in index.md to only have to specify it in one place.