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] >> >>
