Re: [DISCUSS] Centralising version-independent component documentation

For internal library documentation at work my team uses a setup with dedicated branches for documentation publication for each published major version (e.g. docs-latest-1.x, docs-latest-2.x, docs-latest-3.x). This setup allows us to make documentation changes that get published when we make a release (during the release of a 2.x version the docs-latest-2.x branch gets updated), which should not go live before the next version is released, but it also allows cherry-picking documentation changes that are applicable to already released software from a development branch to a docs-latest-* branch for immediate publication. In my opinion this is the ideal setup.

Nils

> Op 19 aug 2026, om 08:59 heeft Sylwester Lachiewicz <[email protected]> het volgende geschreven:
> 
> 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