We have xdoc documentation for our Java library. It links to Javadoc and shows code examples on how to use the library.
Some of our links to the Javadoc use special characters like parenthesis for methods. Javadoc is generated from standard javadoc plugin, so we have no control over the links it makes.
Example XDoc with link: https://github.com/checkstyle/checkstyle/blob/dcadc13fc0bcdbf15b9b3c4faadd1eb26bf1d486/src/xdocs/writingchecks.xml#L289 Code:
<a href="apidocs/com/puppycrawl/tools/checkstyle/api/AbstractCheck.html#visitToken(com.puppycrawl.tools.checkstyle.api.DetailAST)">
<code>visitToken()</code>
Actual link points to https://checkstyle.org/apidocs/com/puppycrawl/tools/checkstyle/api/AbstractCheck.html#visitToken(com.puppycrawl.tools.checkstyle.api.DetailAST) .
As can be seen, the XDOC and link match. However, when running mvn clean site and generating the HTML it instead generates the following HTML:
<a href="apidocs/com/puppycrawl/tools/checkstyle/api/AbstractCheck.html#visitTokencom.puppycrawl.tools.checkstyle.api.DetailAST">
<code>visitToken()</code>
A similar live version can be found at https://checkstyle.org/writingchecks.html with the invalid URL.
It removes the parenthesis and creates an invalid link which does not take you to the location expected. We tried using % encoding in the link, but it removes the % and still does not work.
How do we fix this so it creates a valid link?