Re: [DISCUSS] Centralising version-independent component documentation

How does one distinguish version dependent and version-independent
documentation? How does one know which files go in which repo?

On Wed, Aug 19, 2026 at 2:59 AM 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



-- 
Elliotte Rusty Harold
[email protected]