I am personally a big fan of Antora (it has its pros and cons which could trigger a discussion on its own).
That said, I would recommend to abstain from considering it as a tool in our context for the following reasons Though Asciidoc is a (yet powerful) extension of Markdown and much better “standardized”, I recall discussions (in different communities and commercial projects) where people found it as a hurdle to even attempt to write documentation. And we perhaps want to keep the barrier low wrt formatting etc. Any markdown language (as opposed to markup, like HTML/SGML) should be easily readable in source. I must confess, a AsciiiDoc file, when containing some of the additional features of AD over MD is harder to read when you are not used to it. Antora is very opinionated wrt the documentation structure in each project (for the writer, not for the reader, there it can generate great documentation sites) It is entirely JavaScript However, regarding its benefits (e.g., multi version handling) we could adopt some of its concepts to our own (Java/Maven) documentation tech stack. I’d be happy to contribute here. > On 30. Oct 2026, at 03:22, David Jencks <[email protected]> wrote: > > You might consider Antora (https://antora.org/) > It works from Asciidoc rather than markdown, so that’s probably a deal > breaker. However it’s really good at dealing with multiple versions of > documentation (per component), makes it easy to move pages leaving redirects > behind, and has (a plugin for, I think) built in local search. The Apache > Camel documentation is built using Antora (with a customized UI). A fairly > uncustomized page is https://camel.apache.org/camel-k/2.11.x/ > > David Jencks > >> On Oct 29, 2026, at 11:55 AM, Sylwester Lachiewicz <[email protected]> >> wrote: >> >> 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] >>> >>> > -- Gerd Aschemann --- Veröffentlichen heißt Verändern (Carmen Thomas) +49/173/3264070 -- [email protected] -- http://www.aschemann.net
