Not sure if it’s just me who’s been digging around this issue for a while, maybe it’s common knowledge to the maven community, but I found this very frustrated dealing with this and researching it on the net, so having finally found the solution to this I thought I’d post it here. If nothing else, it would make it easier for me to find the answer to this issue every time I come across it in the future 🙂

So my main “beef” with maven site plugin (aka DOXIA) in this case was when using bookmarks in the page in the link — which as you know, involves the usage of the hash symbol (#) — e.g. http://liviutudor.com/javadoc/some/package/ClassName.html#methodName(Parameter,Parameter). It turns out that running the xml file through mvn site I get this link: http://liviutudor.com/javadoc/some/package/ClassName.html#methodNameParameter,Parameter — needless to say that’s a broken link and would only end up confusing the user!

So, I came across this again recently putting together some how-to notes for Apache Commons Functor — as you will notice, the page uses links to JavaDoc for some methods. Shortly after committing the change and having the site generated and deployed, Simone Tripodi and I spotted that some of the links were broken and we identified the issue to be down to the links containing bookmarks. A quick discussion with the Doxia team (checkout this bug) revealed this is a known bug in Doxia and it will be fixed, but unfortunately only in the next major release as it’s got some big implications. However, they did point us to this other bug which basically suggests that we use absolute URL’s when we use bookmarks rather than relative URL’s — which was initially the case.

So, rather than using :

<a href="apidocs/org/apache/commons/functor/aggregator/AbstractListBackedAggregator.html#createList()">createList()</a>

we had to change the xml to include the full url:

<a href="http://commons.apache.org/functor/apidocs/org/apache/commons/functor/aggregator/AbstractListBackedAggregator.html#createList()">createList()</a>

And this seems to have fixed the problem. There is the annoying problem that the links generated this way would have the icon which denotes an external link attached to them (even though they point to the same site!) but I think in most cases that’s a smaller issue to deal with than having broken links in examples/how-tos.

So there you have it — when dealing with bookmarks in mvn site, make sure you use an absolute url to avoid any url mangling! Remember this well, because otherwise it seems like a b..ch trying to google for … hash sign 🙂