Hi all, I've reworked the styling of the reference guide so it matches wicket.apache.org instead of the stock Asciidoctor theme. The pull request has before and after screenshots:
https://github.com/apache/wicket/pull/1845 What changes for readers: - Code is highlighted. Our pom configured CodeRay through a plugin parameter that asciidoctor-maven-plugin 2.x no longer knows, so the guide has had no syntax highlighting for a while. It now uses Rouge, and wicket:id attributes and wicket: tags in markup listings are marked so you can see where markup binds to Java. - Every listing gets a language label and a copy button. - The table of contents follows the section you're reading and only expands the current chapter, which helps on a single page this long. - A masthead links back to the site, the docs page, the Javadoc of this line and the other guide versions. - Text is set in a narrower column with the site's typefaces and colours, notes and warnings read as asides, and there is a dark mode. - The page no longer loads anything from third parties (Google Fonts and the Font Awesome CDN are gone). The PDF is unchanged. To build it locally: mvn -pl wicket-user-guide -Pguide generate-resources and open wicket-user-guide/target/generated-docs/single.html. There is one thing to sort out before it can go into a release. The fonts (Alegreya and JetBrains Mono, the same ones the site uses) are under the SIL OFL, which is Category B and not allowed in source releases. That turns out to be true of the wicket-examples fonts as well, which have been in our source releases for years. I've listed every font we use, with options and Category A alternatives, in: https://github.com/apache/wicket/issues/1846 I'd like your feedback on the design, especially from anyone reading the guide on a phone or in dark mode. Comments on how we should handle the fonts are welcome in the issue or on this thread. Martijn
