link to "Guide to Using Toolchains" broken

[schoemme]

Bug description

Broken link: https://maven.apache.org/plugins/maven-toolchains-plugin/guides/mini/guide-using-toolchains.html returns 404

Maven site URL where bug exists

https://maven.apache.org/plugins/maven-toolchains-plugin/guides/mini/guide-using-toolchains.html

[slawekjaranowski]

How to you reach such links .... ?
What site link to it?

[schoemme]

From the Apache Maven Toolchains Plugin page, sidebar under "See Also"

[slawekjaranowski]

Site https://maven.apache.org/plugins/maven-toolchains-plugin/index.html

Is generated as plugin documentation from project: https://github.com/apache/maven-toolchains-plugin

There is a site definition: https://github.com/apache/maven-toolchains-plugin/blob/master/src/site/site.xml

Looks ok:

    <menu name="See Also">
      <item name="Guide to Using Toolchains" href="/guides/mini/guide-using-toolchains.html"/>
      <item name="Toolchains Descriptor" href="/ref/current/maven-core/toolchains.html"/>
    </menu>

Question why relative url was used instead of absolute ....

[slawekjaranowski]

generated site contains:

 <li class="nav-header">See Also</li>
    <li><a href="guides/mini/guide-using-toolchains.html">Guide to Using Toolchains</a></li>
    <li><a href="ref/current/maven-core/toolchains.html">Toolchains Descriptor</a></li>

acocrding to site descriptor should be:

 <li class="nav-header">See Also</li>
    <li><a href="/guides/mini/guide-using-toolchains.html">Guide to Using Toolchains</a></li>
    <li><a href="/ref/current/maven-core/toolchains.html">Toolchains Descriptor</a></li>

@michael-o @kwin do you know such problem?

[michael-o]

Checking...

[michael-o]

Found it:
org.apache.maven.doxia.site.inheritance.DefaultSiteModelInheritanceAssembler.relativizeLink(String, String) which calls org.apache.maven.doxia.site.inheritance.URIPathDescriptor.URIPathDescriptor(String, String). Read the Javadoc. It strips the slash and it considers the site URL as base, it does not consider the full URL to relativize. It does not even consider a scheme-releative path (e..g, //maven.apache.org). In my opinion, we need to take a look at https://url.spec.whatwg.org/#url-writing and do it like browsers do. For now, it can only be fixed with an absolute URL if it is outside of the base URL or a traversal would also do:

D:\Entwicklung\Projekte\maven-toolchains-plugin [master ≡ +1 ~1 -0 !]> git diff
diff --git a/src/site/site.xml b/src/site/site.xml
index 920fb02..c7c2efe 100644
--- a/src/site/site.xml
+++ b/src/site/site.xml
@@ -42,8 +42,8 @@ under the License.
       <item name="Download" href="download.html"/>
     </menu>
     <menu name="See Also">
-      <item name="Guide to Using Toolchains" href="/guides/mini/guide-using-toolchains.html"/>
-      <item name="Toolchains Descriptor" href="/ref/current/maven-core/toolchains.html"/>
+      <item name="Guide to Using Toolchains" href="../../guides/mini/guide-using-toolchains.html"/>
+      <item name="Toolchains Descriptor" href="../../ref/current/maven-core/toolchains.html"/>
     </menu>
   </body>
 </project>

[michael-o]

This issue needs to be moved to the plugin itself.

[Bukama]

This issue needs to be moved to the plugin itself.

Done :)

[muzzle2023]

For those impacted by the broken link, the current correct link as of May 18, 2026 is:
https://maven.apache.org/guides/mini/guide-using-toolchains.html

I found this page because thankfully this maven-compiler-plugin page had the correct link:
https://maven.apache.org/plugins/maven-compiler-plugin/examples/compile-using-different-jdk.html