Include pom.xml based version number in github pages?

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

Solution

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.