Currently the docs for the most active subprojects aren’t in the website, since they are READMEs in the individual subprojects.
I did an experiment with the SCR subproject to get the same page in both the GitHub README and the (Antora) site. For Antora, the sources need to be in a particular folder structure, under modules/<module-name>/pages/, whereas for the README it should be in the root of the subproject. Unfortunately the best way to satisfy this, with an asciidoc include:: preprocessor instruction, is disabled by GitHub. In my experiment, the maven build copies scr/modules/scr/pages/scr.adoc (the page Antora works with) to src/README.adoc (visible on GitHub). The asciidoc (copied) README.adoc is visible at https://github.com/djencks/felix-dev/tree/adoc-test/scr (since there’s no README.md file GitHub shows README.adoc). The site with the page rendered by Antora is at https://felix-preview.s3-us-west-2.amazonaws.com/documentation/scr/scr.html — Some choices: - Antora source location. It might well make more sense to put the antora tree under src/doc/modules/scr/pages, or docs/modules/scr/pages, but I opted in this experiment to put the pages on the shortest possible path. - Copying method: I used the 3rd party copy-rename-maven-plugin which hasn’t been updated since 2014. This might be a risk. I think the antrun plugin can be configured to do the same. - Multiple pages. IIUC there can only be one README, but some subprojects have extensive documentation. I suggest that for such subprojects, we consider moving the documentation to the subproject and having a short non-copied README.adoc pointing to the website. Is migrating the docs for dead/retired subprojects a good idea? David Jencks
