I was more or less assuming that before reorganizing the website content, organizing it was required. Otherwise, you could just drop all current content and start over, which admittedly might be faster and more satisfactory.
The asciidoctor-maven-plugin is only usable if you want a site with only one version. All of the sites you note below indeed only have one version. Although primitive, what David Blevins came up with in tomee-site-generator at least allows multiple versions. For me, two hard requirements would be: - generate the entire site in one action. I think this is needed to track what is supposed to be there and avoid orphaned content like we have now. - support multiple components and versions with easy navigation between them. At a minimum, I think there can be general version less information and version specific information. Separating content into perhaps a User Guide and a Reference Guide would be even better. Here are some Antora generated sites: Customized UI: https://camel.apache.org/manual/latest/getting-started.html / https://github.com/apache/camel/tree/master/docs https://isis.apache.org/guides/ugfun/ugfun.html (using rather non-standard navigation; I find this confusing) /https://github.com/apache/isis/tree/master/antora (I think this is far too complicated, but it’s one approach to organizing a gigantic disorganized set of documentation) https://docs.couchbase.com/server/6.5/introduction/intro.html / https://github.com/couchbase/docs-site https://www.uyuni-project.org/uyuni-docs/uyuni/index.html / https://github.com/uyuni-project/uyuni-docs Unmodified UI https://books.japila.pl/apache-spark-internals/apache-spark-internals/latest/index.html / https://github.com/japila-books/apache-spark-internals There’s a list of more sites here: https://gitlab.com/antora/antora.org/issues/20 Some of these sites, for reasons I don’t understand, avoid making it clear that there are multiple components and versions. In the default UI, and several of these sites, at the lower left there’s a component selector allowing you to choose which component/version you want to look at. This is also visible in my preview site. I’m not aware of any other comparable system that provides built in this level of organization. David Jencks > On Feb 19, 2020, at 5:24 AM, gilbertoca <[email protected]> wrote: > > David Blevins-2 wrote >> There's an entire facet of this discussion we probably should be talking >> about which is how to deal with our heaps of content in various states of >> health; how did it get unhealthy, how do we deal with it, how do we >> prevent it, how do we encourage more contribution to main docs. >> >> I think any tool in the hands of someone willing to lead an effort to >> improve our main docs is a good tool. >> >> -David > > We could follow (again) apache friends and others [1] condensing all > relevant content in something like a User Guide or Reference Guide - that > would help the Maintenance and contribution. This organization can reduce > the tooling and it easy integrate(asciidoctor-maven-plugin?) in build > system[2]. > > [1] > https://netbeans.apache.org/kb/docs/java/index.html > https://ci.apache.org/projects/wicket/guide/8.x/single.html > https://beanvalidation.org/2.0/spec/ > https://docs.jboss.org/cdi/spec/2.0/cdi-spec.html > https://shiro.apache.org/reference.html > > [2] https://asciidoctor.org/docs/asciidoctor-maven-plugin/ > > Regards, > > Gilberto > > > > -- > Sent from: http://tomee-openejb.979440.n4.nabble.com/TomEE-Dev-f982480.html
