You are viewing a plain text version of this content. The canonical link for it is here.
Posted to issues@maven.apache.org by "slachiewicz (via GitHub)" <gi...@apache.org> on 2026/08/19 06:08:16 UTC
[I] Move the Doxia site into maven-site [maven-site]
slachiewicz opened a new issue, #1645:
URL: https://github.com/apache/maven-site/issues/1645
`maven-doxia-site` is a separate repository, a separate Jenkins job and a separate svn
publication tree, for 21 pages that live at `/doxia/` on maven.apache.org. Folding it into
`maven-site` removes one repo, one job and one svnwcsub mount, and no URL has to change.
This issue is the plan and the tracking point. It is not a decision — three things at the
bottom need dev@ input first.
## How the site is published today
Both repos have the same shape: a single-module site build, a Jenkins job on the
`svn-websites` agent running `mvn site-deploy`, `maven-site-plugin` with `skipDeploy`, and
`maven-scm-publish-plugin` doing the svn commit. `maven-site` publishes to
`maven/website/content/`, `maven-doxia-site` to `maven/doxia/website/content/`.
The webserver working copy at `/www/maven.apache.org/content` is assembled by `svnwcsub`
from four checkouts, as documented in
[`developers/website/index.md`](https://maven.apache.org/developers/website/index.html):
| path | svn source |
|---|---|
| `/` | `maven/website/content/` |
| `/components` | `maven/website/components/` |
| `/doxia` | `maven/doxia/website/content/` |
| `/doxia/components` | `maven/doxia/website/components/` |
Released component documentation is never in git — release managers `svnmucc` it into the
`components/` trees, and the site build recreates symlinks into them from the
`components.links` files via `maven-antrun-plugin`. That task already globs
`**/components.links`, so it picks up nested ones without a change.
That `/doxia` mount is what makes this a two-party change: a `maven-site` PR **and** an
INFRA ticket, in that order.
## Content move
```
maven-doxia-site/content/markdown/** -> maven-site/content/markdown/doxia/**
maven-doxia-site/content/resources/** -> maven-site/content/resources/doxia/**
```
Directory structure is preserved verbatim, so every relative link inside the Doxia pages
(`../macros/index.html`, `../doxia/doxia-modules/...`, `../doxia-archives/...`) keeps
resolving, and root-absolute links (`/xsd/...`, `/plugin-developers/...`) are unaffected.
`components.links` targets are relative, so the symlinks still land on `/doxia/components/...`.
`pom.xml`, `Jenkinsfile`, `.asf.yaml`, `README.md`, `LICENSE` and `NOTICE` are not moved.
Two lines in `maven-site/pom.xml`:
- `<doxiaVersion>2.1.0</doxiaVersion>` — `index.md.vm` and `developers/modules.md.vm` use it,
and render broken without it.
- `content/resources/doxia/images/architecture.odg` in the rat excludes.
`**/.htaccess`, `**/*.links` and `**/*.svg` are already covered.
## What breaks, and the fix for each
Four things, found by comparing the two builds.
**1. The site descriptor is singular.** A site build has exactly one `site.xml`. Doxia's own
`bannerRight` logo, its `Doxia` breadcrumb and its five menus (About / Modules /
Documentation / Developer Docs / reports) go away; the pages get the main Maven navigation.
There is no per-directory descriptor, so the only option is folding the Doxia menus into
`maven-site/content/site.xml` the way `/plugins/` and `/shared/` are handled. This is the one
user-visible regression.
**2. Five MPIR pages stop being generated:** `/doxia/team.html`,
`/doxia/mailing-lists.html`, `/doxia/ci-management.html`, `/doxia/issue-management.html`,
`/doxia/project-info.html`. Add `Redirect Permanent` for each to the relocated
`/doxia/.htaccess`. All five root equivalents currently return 200, so they are valid
targets — though for `issue-management.html` and `project-info.html`, which describe Maven as
a whole rather than Doxia, pointing at `/doxia/` may serve readers better.
`/doxia/scm.html` is *not* affected: Doxia has a hand-written `scm.md` that already wins over
the MPIR report, so it survives the move unchanged.
**3. Skin assets under `/doxia/images/` and `/doxia/css/` move to the site root.** The skin
writes its icons, fonts, `js/`, `img/` and CSS into each *site root*; after the move that root
is `/`, not `/doxia/`. Two consumers:
- `references/index.md` uses `../images/icon_*_sml.gif` about twelve times — switch to
`/images/icon_*_sml.gif`. Root `/images/` already has all of them, so this can land as its
own commit before the move.
- `/doxia/.htaccess` serves the archived release sites with
`^/doxia/.*-archives/images/(.*)$ -> /doxia/images/$1` and
`^/doxia/.*-archives/css/(.*)$ -> /doxia/css/$1`. Retarget both to `/images/$1` and
`/css/$1`. Root `/css/` is a superset of what `/doxia/css/` holds today.
**4. `site.css`.** Doxia's 40-line stylesheet turns out to be a strict subset of maven-site's
67-line one — identical `externalLink`, `body ul` and `#downloadbox` rules, and maven-site
adds `.bordered` and `.grey`. So the pages pick up `/css/site.css` with no visual change and
the Doxia copy can be dropped along with the redirect retarget above.
Nothing else moves: the root `.htaccess` already applies to `/doxia/` today, the Doxia rules
are all `^/doxia/`-anchored so they work from any directory, and `doap_Doxia.rdf` keeps its
URL, so no comdev change is needed.
## Cut-over order
This sequence never leaves the site broken:
1. Merge the `maven-site` PR. Jenkins deploys and creates `doxia/` inside
`maven/website/content/`. Nothing user-visible happens — the `/doxia` mount still shadows it.
2. INFRA removes the `/doxia` mount from `svnwcsub.conf` and **keeps** `/doxia/components`.
Component releases keep deploying to `maven/doxia/website/components/` exactly as before.
3. Verify `/doxia` now serves the maven-site build.
4. Only then decommission.
Rollback at any point before step 4 is re-adding the mount.
One thing to settle with INFRA before step 1: today `/doxia/components` nests inside `/doxia`,
which is itself a working copy, and `/components` nests inside an *unversioned* path of the
root working copy. After the change `/doxia/components` would nest inside a `doxia/` directory
that *is* versioned in the outer working copy. That is the one thing that could force a
different layout.
<details>
<summary>Draft INFRA ticket, to file at step 2</summary>
**Summary:** Remove the `/doxia` svnwcsub mount for maven.apache.org
The Apache Maven project has consolidated the Doxia website source into
`apache/maven-site`. `/doxia/**` is now generated by the maven-site build and committed to
`https://svn.apache.org/repos/asf/maven/website/content/doxia/`.
Please remove this entry from `svnwcsub.conf` in `infrastructure-puppet`
(`modules/svnwcsub/files/svnwcsub.conf`):
- `/www/maven.apache.org/content/doxia` <- `https://svn.apache.org/repos/asf/maven/doxia/website/content/`
Please **keep** this one — released Doxia component documentation is still published there
by release managers and is not part of the git-managed site:
- `/www/maven.apache.org/content/doxia/components` <- `https://svn.apache.org/repos/asf/maven/doxia/website/components/`
Question before you apply it: `/doxia/components` will then be nested inside a `doxia/`
directory that is versioned in the outer `/www/maven.apache.org/content` working copy,
rather than inside a working copy of its own. The existing `/components` mount nests inside
an unversioned path, which is not quite the same case. If svnwcsub cannot handle that, let
us know and we will restructure on our side instead.
Follow-up in the same or a separate ticket: archive `apache/maven-doxia-site` read-only.
</details>
## Decommission, after step 3 verifies
- [ ] disable the `Maven/maven-box/maven-doxia-site` Jenkins job
- [ ] archive `apache/maven-doxia-site`
- [ ] freeze or remove `maven/doxia/website/content/` in svn
- [ ] `developers/website/index.md` — the four-mount table and the two `maven-doxia-site`
`components.links` links
- [ ] `developers/website/deploy-maven-website.md` — its "How Doxia website publication works"
section is already obsolete CMS-era text
- [ ] check `deploy-component-reference-documentation.md` and
`component-reference-documentation-helper.md` for Doxia wording
- [ ] fold anything missing from Doxia's `.asf.yaml` (labels, autolinks) into maven-site's
## Verification
Build both and diff:
```
diff -r maven-doxia-site/target/site maven-site/target/site/doxia
```
The diff is noisy by design, because everything the skin and the reports write into a *site
root* stops being written into `/doxia/`. Expected, and nothing else:
- the five MPIR pages, plus `avatars/` from the team report
- `css/apache-maven-fluido-*.min.css`, `css/print.css`, `css/site.css`
- `fonts/`, `img/`, `js/`
- `images/` reduced to Doxia's own files
- navigation, banner and breadcrumb differences from (1)
All of those are served from the site root instead, which is what the retargeted redirects
point at. Anything outside this list is a bug.
## Can the git history come along?
Yes. `maven-doxia-site` is 217 commits, 2012-12-10 to today — small and clean enough to graft:
```
git clone https://github.com/apache/maven-doxia-site.git doxia-history
cd doxia-history
git filter-repo \
--path content/markdown/ \
--path content/resources/ \
--path-rename content/markdown/:content/markdown/doxia/ \
--path-rename content/resources/:content/resources/doxia/
cd ../maven-site
git remote add doxia ../doxia-history
git fetch doxia
git merge --allow-unrelated-histories doxia/master
```
The two `--path` filters keep only the directories that move, which also drops
`content/site.xml` — it would otherwise collide with maven-site's own descriptor, and its
content is folded in by hand anyway. `git blame` and `git log --follow` then work across the
boundary.
Two caveats. The git repo only goes back to the 2012 CMS migration; everything before that is
in svn at `maven/doxia/site/trunk` and stays there either way. And maven-site's `.asf.yaml`
sets `merge: false` with a required `Verify and build Maven Site` check, so a merge commit
cannot land through the PR button as configured — it needs the merge button enabled
temporarily, or a direct push to gitbox.
The cheaper alternative is a plain copy plus archiving `maven-doxia-site` read-only, leaving
the history browsable at a stable GitHub URL. Worth deciding up front: retrofitting the graft
after a plain copy is considerably messier.
## Needs a decision
1. Fold the Doxia menus into the main `site.xml`, or accept plain main-site navigation?
2. Graft the history, or plain copy and archive?
3. Confirm with INFRA that the nested `/doxia/components` mount stays valid.
*This issue was created with AI assistance.*
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: issues-unsubscribe@maven.apache.org.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
Re: [I] Move the Doxia site into maven-site [maven-site]
Posted by "slachiewicz (via GitHub)" <gi...@apache.org>.
slachiewicz commented on issue #1645:
URL: https://github.com/apache/maven-site/issues/1645#issuecomment-5338364423
The mechanical part of this is up as #1646: the content move, the pom properties, the redirects and the icon paths, plus a first cut at folding the Doxia menus into `site.xml` for question 1. It is safe to merge before the INFRA ticket — the `/doxia` mount still shadows the new output until INFRA removes it.
Questions 2 and 3 are untouched and still need dev@.
*This comment was created with AI assistance.*
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: issues-unsubscribe@maven.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
Re: [I] Move the Doxia site into maven-site [maven-site]
Posted by "slachiewicz (via GitHub)" <gi...@apache.org>.
slachiewicz commented on issue #1645:
URL: https://github.com/apache/maven-site/issues/1645#issuecomment-5393546947
Yes sure, I'll fix it
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: issues-unsubscribe@maven.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
Re: [I] Move the Doxia site into maven-site [maven-site]
Posted by "slachiewicz (via GitHub)" <gi...@apache.org>.
slachiewicz commented on issue #1645:
URL: https://github.com/apache/maven-site/issues/1645#issuecomment-5394027803
Upstream filed: the rendering bug is in doxia itself — apache/maven-doxia#1086, fix in apache/maven-doxia#1087. The converter has a related but different defect (it silently drops `<object>` during xdoc→markdown): apache/maven-doxia-converter#159.
*This comment was created with AI assistance.*
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: issues-unsubscribe@maven.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
Re: [I] Move the Doxia site into maven-site [maven-site]
Posted by "hboutemy (via GitHub)" <gi...@apache.org>.
hboutemy commented on issue #1645:
URL: https://github.com/apache/maven-site/issues/1645#issuecomment-5380628432
it's far from completed:
- https://issues.apache.org/jira/browse/INFRA-28277 is not yet finished
- all the "Decommission, after step 3 verifies"
did you read what you wrote? just doing the initial copy is the easy part
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: issues-unsubscribe@maven.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
Re: [I] Move the Doxia site into maven-site [maven-site]
Posted by "slachiewicz (via GitHub)" <gi...@apache.org>.
slachiewicz commented on issue #1645:
URL: https://github.com/apache/maven-site/issues/1645#issuecomment-5339233522
INFRA ticket filed as [INFRA-28277](https://issues.apache.org/jira/browse/INFRA-28277) (component SvnPubSub), which covers question 3.
It is deliberately written as a question plus a hold rather than a removal request: it asks whether svnwcsub is happy with `/doxia/components` nested inside a `doxia/` directory that is versioned in the outer working copy, and asks INFRA to wait for a comment from us before touching the mount. So it is safe that it is open while #1646 is still unmerged — the mount only goes away after that PR merges and the Jenkins job has deployed.
It also carries a follow-up line asking for `apache/maven-doxia-site` to be archived read-only once the move is done.
Questions 1 and 2 still need dev@.
*This comment was created with AI assistance.*
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: issues-unsubscribe@maven.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
Re: [I] Move the Doxia site into maven-site [maven-site]
Posted by "hboutemy (via GitHub)" <gi...@apache.org>.
hboutemy commented on issue #1645:
URL: https://github.com/apache/maven-site/issues/1645#issuecomment-5394638268
> Once these cleanups land, having everything in one Markdown tree should make the docs far easier to manage and refactor than the xdoc/apt mix ever was.
you over-expect from Markdown: tables with multi-lines content is the biggest limitation
but sure, dropping APT and using Markdown as much as possible helps getting more classical knowledge that will help us get more contribution
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: issues-unsubscribe@maven.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
Re: [I] Move the Doxia site into maven-site [maven-site]
Posted by "hboutemy (via GitHub)" <gi...@apache.org>.
hboutemy closed issue #1645: Move the Doxia site into maven-site
URL: https://github.com/apache/maven-site/issues/1645
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: issues-unsubscribe@maven.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
Re: [I] Move the Doxia site into maven-site [maven-site]
Posted by "slachiewicz (via GitHub)" <gi...@apache.org>.
slachiewicz closed issue #1645: Move the Doxia site into maven-site
URL: https://github.com/apache/maven-site/issues/1645
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: issues-unsubscribe@maven.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
Re: [I] Move the Doxia site into maven-site [maven-site]
Posted by "hboutemy (via GitHub)" <gi...@apache.org>.
hboutemy commented on issue #1645:
URL: https://github.com/apache/maven-site/issues/1645#issuecomment-5391899839
I just discovered that brutal Markdown migration broke svg integration https://maven.apache.org/scm.html
@slachiewicz can you please fix? I don't have time to fix everything that has been broken
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: issues-unsubscribe@maven.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
Re: [I] Move the Doxia site into maven-site [maven-site]
Posted by "hboutemy (via GitHub)" <gi...@apache.org>.
hboutemy commented on issue #1645:
URL: https://github.com/apache/maven-site/issues/1645#issuecomment-5397715545
ok, now maven-doxia-site.git is readonly, and INFRA did the cleanup necessary for https://maven.apache.org/doxia/index.html
now we can close done
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: issues-unsubscribe@maven.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
Re: [I] Move the Doxia site into maven-site [maven-site]
Posted by "hboutemy (via GitHub)" <gi...@apache.org>.
hboutemy commented on issue #1645:
URL: https://github.com/apache/maven-site/issues/1645#issuecomment-5393609547
I just found a workaround in #1652
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: issues-unsubscribe@maven.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
Re: [I] Move the Doxia site into maven-site [maven-site]
Posted by "slachiewicz (via GitHub)" <gi...@apache.org>.
slachiewicz commented on issue #1645:
URL: https://github.com/apache/maven-site/issues/1645#issuecomment-5393758116
Yes — we knew the conversion wouldn't be entirely straightforward, and this is the kind of breakage only the rendered page shows. What I found after building everything locally:
- #1652 fixes more than the diagrams. The Markdown parser turns each self-closing `<object/>` into an *unclosed* `<object>` and emits all seven `</object>` at the end of the body — so everything after the first diagram was hidden as object fallback content. With your change the whole page comes back.
- While verifying it I found a second leftover from the xdoc conversion: raw `<head>` blocks are not honored by the Markdown parser — title/author leak as stray text at the top of the body and the pages fall back to the bare "Maven" browser title. This affects `scm.md` plus four more pages (`articles`, `repository/index`, `guides/mini/guide-naming-conventions`, `developers/mojo-api-specification`). #1653 moves that metadata to YAML front matter; it doesn't overlap with #1652, so the two merge in either order.
- I swept the rest of the site: `scm.html` was the only page with the self-closing pattern, every other SVG is embedded via plain image syntax, and all referenced SVG files resolve.
I'm also taking the root cause upstream to doxia-converter (issue + fix) so future conversions emit explicitly closed tags instead of this trap.
Once these cleanups land, having everything in one Markdown tree should make the docs far easier to manage and refactor than the xdoc/apt mix ever was.
*This comment was created with AI assistance.*
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: issues-unsubscribe@maven.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
Re: [I] Move the Doxia site into maven-site [maven-site]
Posted by "hboutemy (via GitHub)" <gi...@apache.org>.
hboutemy commented on issue #1645:
URL: https://github.com/apache/maven-site/issues/1645#issuecomment-5381220267
https://issues.apache.org/jira/browse/INFRA-28298
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: issues-unsubscribe@maven.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
Re: [I] Move the Doxia site into maven-site [maven-site]
Posted by "hboutemy (via GitHub)" <gi...@apache.org>.
hboutemy commented on issue #1645:
URL: https://github.com/apache/maven-site/issues/1645#issuecomment-5340818720
looks like a good idea: we even can move `/doxia/components` to `/maven/components/doxia` in a further step
menu from Doxia site.xml will have to be added to Maven's site as a Doxia sub-menu IMHO
the only aspect we're loosing is the breadcrumb in doxia-site = "Apache > Maven > Doxia > Introduction" in https://maven.apache.org/doxia/index.html will become "Apache > Maven > Introduction"
notice: detecting breadcrumbs from menu hierarchy is a feature I want us to add to Maven Site Plugin one day, this will be the right time to work together on this, that will add the breadcrumb back in the future (TBD)
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: issues-unsubscribe@maven.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org