Re: [DISCUSS] Folding the Doxia site into maven-site

Hi,
I would prefer to actually move the doxia site (https://github.com/apache/maven-doxia-site) to https://github.com/apache/maven-doxia instead.
IMHO that site documentation should be isolated, so that working on it doesn’t require you to clone the whole Maven website.
I opened https://github.com/apache/maven-doxia-site/issues/51 for that quite some time ago.
Konrad


> On 19. Aug 2026, at 10:17, Sylwester Lachiewicz <[email protected]> wrote:
> 
> Hi everyone,
> 
> I would like to propose folding the maven-doxia-site repository into
> maven-site so the entire site is built from a single source tree.
> Currently, maven-doxia-site is a separate repository, Jenkins job, and SVN
> publication tree for the 21 pages located at /doxia/ on
> https://maven.apache.org/
> 
> This move will not change any /doxia/ URLs. The full plan is outlined in
> https://github.com/apache/maven-site/issues/1645, and the content move is
> complete and passing tests in https://github.com/apache/maven-site/pull/1646.
> The infrastructure changes are tracked under INFRA-28277, which is
> deliberately on hold until the PR is merged and deployed.
> 
> Before merging, I would like to get your opinions on two specific points:
> 
> 1.  Navigation
>    A site build has exactly one site.xml, meaning the Doxia pages cannot
> keep their own banner, breadcrumb, and menus. Instead, they will adopt the
> main Maven navigation. This is the only user-visible change.
>    The current PR nests the Doxia menus inside the Documentation menu,
> next to Maven Tools. Alternatively, we could leave the Doxia pages with
> plain main-site navigation and remove their specific menus entirely.
> 
> 2.  Git history
>    The maven-doxia-site repository has 217 commits dating back to December
> 2012. We can either:
>    a) Graft the history onto maven-site using git-filter-repo and a merge
> with --allow-unrelated-histories so git blame and git log --follow continue
> to work. This requires temporarily enabling the merge button or a direct
> push to GitBox due to our .asf.yaml restrictions.
>    b) Do a plain copy, as the PR currently does, and archive
> maven-doxia-site as read-only.
> 
> Deciding this upfront is ideal, as retrofitting the history later is much
> more complex. Note that either option only covers the Git era; anything
> prior to the 2012 CMS migration will remain in SVN.
> 
> For context, building both trees and diffing them shows that only the
> necessary root-level items change. Additionally, resolving local links in
> the built Doxia pages actually fixes 14 broken links that currently point
> to the main site.
> 
> If there are no objections, I plan to merge the PR in a week and update
> INFRA-28277 once the deployment is complete.
> 
> Thanks,
> Sylwester