Hi, Thanks to Sandra and Martijn for the two examples, and to everyone for the feedback. Before we pick a design or a tool, I tried to collect the requirements that came up in this thread, so we can measure every proposal against the same list:
1. Content works without JavaScript; search or a theme switch may use it as an extra. 2. The site keeps being built with Maven, Doxia and the site plugin (or at least a JVM toolchain), as Elliotte and Manfred asked. But still open to alternatives that help contribute to site content. 3. No published URL or anchor breaks: moved pages get redirects, ideally checked in CI. 4. Plugin and component sites get the new look too, and keep their uniform structure (goal pages, parameters, reports). 5. An "edit this page" link on every page. 6. Mobile layout and dark mode. 7. No third-party requests (fonts, analytics), in line with the ASF privacy policy. Embedded in site (as now) is ok. 8. Search, and a way to move between versions of a plugin's documentation. 9. Sources stay close to the code they document. Items 3 and 4 are, in my view, the ones the current proposals do not cover yet. What is missing from this list, or should not be on it? I would like to keep the discussion open, and track the outcome in the maven-site repository so it stays visible to everyone. Regards, Sylwester On Thu, Oct 29, 2026 12:46 PM, "mfriedenhagen.gmx.de via users" < [email protected]> wrote: > Hi, > > I for one like Martijn's design. I disagree that only people already > convinced of Maven should be addressed. > > Personally I dislike documentation pages which do not tell people what the > software is good for and why I should use or try it. > > Besides the start page, the rest is easier to access for first-time users. > > Additional benefit: it is usable on mobile phones as well and the search > works quite well for those knowing what to look for. > > Mit freundlichen Grüßen > Mirko Friedenhagen > -- > > > Am 28.10.26 um 12:26 schrieb Elliotte Rusty Harold > > > First impression: this feels like a marketing page, not developer > > documentation. The target audience for the maven site are developers > > who want to use Maven. The purpose is not to sell Maven to an > > undecided audience. > > > > On Tue, Oct 27, 2026 at 10:56 PM Martijn Dashorst > > <[email protected]> wrote: > > > > > > On Tue, Oct 27, 2026 at 7:59 PM Manfred Moser <[email protected] > > > > > wrote: > > > > > > > Totally agree with Elliotte. We should us our own tooling or at a > > > > minimum stay with Java/JVM-based solution to keep things simpler. > > > > > > > > The docs source should also continue to sit with the same repos as > they > > > > are so we dont have to change a lot of infra and process. > > > > > > > > > > I agree, especially since all the plugins also use doxia (if I > understand > > > it correctly). > > > > > > I don't think using doxia is a detractor for good documentation, nor a > > > modern web > > > design. But it might need some tweaking to enable new features, but I > think > > > that is > > > for the better. > > > > > > I rebuilt my demo site using doxia, a new skin and a search index > update > > > all from > > > maven. This version of the example is built with Maven’s own tooling: > mvn > > > site, > > > maven-site-plugin and Doxia, from the same sources as maven.apache.org. > The > > > frame is a skin of its own (doxia/skin), the structure is the site > > > descriptor content/site.xml, > > > one menu three levels deep, and the landing pages, the news and the A–Z > > > index are > > > Markdown pages written from the same data by a small script. After the > > > pages are > > > rendered, two small classes run from the POM colour the code > (Highlight) > > > and write > > > the search index (SearchIndex). Not in this version: the date a page > last > > > changed; > > > moving pages to new addresses would add .htaccess redirects. The > version > > > built > > > with Jekyll has those. > > > > > > You can see the results here: > > > > > > https://dashorst.github.io/maven-site/mvn-site/ > > > > > > Let me know if you have any feedback. > > > > > > Kind regards, > > > > > > Martijn Dashorst > > > > > > > > -- > > Elliotte Rusty Harold > > [email protected] > > > > --------------------------------------------------------------------- > > To unsubscribe, e-mail: [email protected] > > For additional commands, e-mail: [email protected] > > > > > > > --------------------------------------------------------------------- > To unsubscribe, e-mail: [email protected] > For additional commands, e-mail: [email protected] > >
