dashorst opened a new issue, #1931:
URL: https://github.com/apache/wicket/issues/1931

   The reference guide on `master` now follows the design of wicket.apache.org 
(#1844). The guide of the 10.x line, on `wicket-10.x`, still uses the 2017 copy 
of the default Asciidoctor stylesheet, and it has the same highlighting bug 
master had: `wicket-user-guide/pom.xml` passes 
`<sourceHighlighter>coderay</sourceHighlighter>`, which 
asciidoctor-maven-plugin 2.x does not know and silently ignores, so every 
listing renders as plain text. The page also loads Font Awesome from cdnjs for 
the admonition icons. Readers of the guide for 10.x get none of the 
improvements, and the guides look different depending on which version you open 
from the site's version list.
   
   ## What to bring over
   
   Two commits on `master`, cherry-picked in this order:
   
   1. 745ae018ec, *Style the reference guide like wicket.apache.org* (#1845):
      - Rouge highlighting through the `source-highlighter` attribute;
      - a docinfo masthead linking to the site, the Javadoc of the line and the 
other versions;
      - a table of contents that follows the section being read;
      - a language label and a copy button for each listing;
      - admonitions restyled as asides;
      - a dark mode;
      - no external requests;
      - the accessibility fixes from the review (skip link, landmarks, 
`aria-current`, named copy buttons);
      - the version line in the title, masthead and Javadoc link taken from the 
project version via build-helper's `parse-version`.
   2. e5999f0896, *Take the reference guide's fonts from webjars at build time* 
(#1896). The Alegreya and JetBrains Mono fonts are SIL OFL (Category B), so 
they must not be in the source tree. This commit fetches them from the 
fontsource webjars in the `guide` profile. **Never cherry-pick the first commit 
without this one:** on its own it puts OFL fonts in the 10.x source release.
   
   Cherry-pick with `-x` so the origin stays traceable.
   
   ## Expected conflicts
   
   I tried both cherry-picks on `wicket-10.x`. The first conflicts only in 
`single.adoc`, on the title line: 10.x has `= Wicket 10.x Reference Guide` and 
`:icons: font`, where master has `= Wicket {wicket_line} Reference Guide` and 
`:docinfo: shared`. Take master's header. The title then says 10.x, because the 
version comes from the pom. The second commit was not tried separately because 
the first stopped, but it only touches the guide's pom, css and LICENSE.
   
   The plugin setup on 10.x matches master's: asciidoctor-maven-plugin 2.2.6, 
and build-helper-maven-plugin managed in the root pom. Two things to check 
while picking:
   - The pedantic pom enforcer's plugin order in the `guide` profile.
   - The `asciidoctorj-pdf` version on 10.x (2.3.27). The PDF execution only 
gains `<icons>font</icons>`, but check the PDF still builds.
   
   This line is the LTS line; the change touches only the guide module, its 
LICENSE entries and `.rat-excludes`, not any shipped jar.
   
   ## Follow-ups to take along once they land on master
   
   These are still open on master. Bring them over in the same way when they 
are merged, or include them if they land first:
   - #1891 / #1903: dark-mode table headers and the 18 px sideways scroll at 
phone width.
   - #1885 / #1904: disclosure buttons for chapters in the table of contents.
   - #1929: the missing space between number and title in the TOC entries' 
accessible names.
   
   ## Done when
   
   - `mvn -pl wicket-user-guide -Pguide generate-resources` builds HTML and PDF 
on `wicket-10.x`.
   - The masthead shows **10.x**, and its Javadoc link points to 
https://nightlies.apache.org/wicket/apidocs/10.x/index.html, which exists.
   - Listings are highlighted, and the page makes no external requests.
   - `git ls-tree -r --name-only HEAD wicket-user-guide | grep -iE 
'\.(woff2?|ttf|otf)$'` returns nothing.
   - `mvn -N apache-rat:check` passes, and a full `mvn clean verify -Pjs-test` 
on the branch is green.
   


-- 
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.

To unsubscribe, e-mail: [email protected]

For queries about this service, please contact Infrastructure at:
[email protected]

Reply via email to