Hi I would say that markdown has a big issue, it means just titles, links and lists, rest is not portable and always a mess when you switch of markdown renderer/platform whereas asciidoc tends to align (even native java renderer tried to align more on asciidoctor so way less surprises for the parsing). So yes it is more complete so can look more complex but at the end when you check the syntax is not more complex than markdown for the same subset (actually easier since it is stable) and it just gives you more if you need (definition lists instead of lists with bold words for ex which breaks the semantic value of the source).
On the multi version support I think we fantasize it, we don't need it since we only maintain a few branches, what we need is the root page to link to the main versions we want to support and ultimately I think we might want a different theme for the versions we do support (thinking to v3 v4 in particular). Don't get me wrong, I do like antora and it is what I used to build https://talend.github.io/component-runtime/ years ago, but I don't see it matching maven context where we want a simpler doc. I'm also not sure why we do need doxia and all that site stack, it has pretty low value and is trivially replaced by a set of tasks generating partial .adoc included in "content". This is what we do use for Yupiik Minisite for example ( https://www.yupiik.io/tools-maven-plugin/mojo/minisite.html - and there the mojo/* pages are generated from plugin.xml for ex with plain Runnable running before site generation). So ultimately we need something trivial: * a template (handlebars, mustache, jsp if you want to plain java world or whatever will work) * a nice theme (this thread) * some generators (plain runnable, main or whatever can take arguments - can even be mojo) from raw reports to .adoc/.md * a renderer joining the model (.adoc/.md) to .html/.pdf potentially (there adoc beats md trivially) * a client side search (can be like in minisite using embedding or a plain js lib while embedded) And more on "us" a clear organization so that the root site can use one of the preaction to fetch the versions to handle/reference (can be using a marker in branches like antora or manual since we don't change that too often). Mixed with git submodules we have a trivial to work on solution locally. Tip: a global menu with the version drop down if desired is trivial since versions can be fetched from a "/versions.json" so theme just renders the dropdown don't oversee it, technically it is not a killer thing. Hope it gives some tech view of what a maven based site can be and why we maybe just overkilled what we designed. Le ven. 30 oct. 2026 à 08:41, Gerd Aschemann <[email protected]> a écrit : > 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 <+49%20173%203264070> -- [email protected] -- > http://www.aschemann.net > >
