Re: [DISCUSS] Centralising version-independent component documentation

Why not just serving the last SNAPSHOT built of the site by default and just link the last release version documentation more prominently?
Konrad

> On 19. Aug 2026, at 08:59, Sylwester Lachiewicz <[email protected]> wrote:
> 
> Hi Everyone,
> 
> Component documentation is currently only published to
> https://maven.apache.org/ when a component releases. This makes
> documentation fixes for rarely released components, or updates to already
> released components, effectively complicated.
> 
> I would like to propose moving the source of version-independent narrative
> documentation into maven-site.git, where a commit would republish the
> changes immediately.
> 
> To understand the scope, I measured the current estate: there are 1,068
> hand-written site pages across our repositories. While 521 are Velocity
> pages, 396 of those use nothing beyond component identity, version, and
> escapes. This means 88% of the pages are portable if maven-site can supply
> a component's current version to a page. We already half-do this today:
> Update.java maintains the version columns of the plugins and shared index
> pages, though it currently gets its numbers by scraping the component's own
> published page. This would need to be re-based on an authoritative source
> first. The site checkers in maven-dist-tool share this same dependency.
> 
> Importantly, published URLs would not break under this approach:
> 
>  - Where a component's generated output is a small, stable set of
> directories, maven-site can own the path and symlink only those back,
> leaving the URL untouched.
>  - Where this is not possible, a redirect in our existing .htaccess file
> can be used. For example, the maven-checkstyle-plugin redirects have
> successfully survived many releases.
>  - Archived, versioned sites would remain unaffected either way.
> 
> I have written up the full details, measurements, and open questions here:
> https://github.com/apache/maven-site/issues/1647
> 
> I am particularly interested in refreshing this discussion now, as I have
> recently moved many pages from APT to Markdown, which should make future
> contributions and refactoring much easier.
> 
> Regards,
> Sylwester