dashorst opened a new issue, #1932:
URL: https://github.com/apache/wicket/issues/1932
The reference guide on `master` now follows the design of wicket.apache.org
(#1844). The guide of the 11.x line, on `wicket-11.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 11.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 11.x source release.
Cherry-pick with `-x` so the origin stays traceable.
## Expected conflicts
I tried both cherry-picks on `wicket-11.x`. The first conflicts only in
`single.adoc`, on the title line: 11.x has `= Wicket 11.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 11.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 11.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 11.x (2.3.27). The PDF execution only
gains `<icons>font</icons>`, but check the PDF still builds.
Related: #1840 notes that the 11.x guide still presents itself as the Wicket
10 guide in places. The title already says 11.x on this branch, and after this
change it comes from the project version. The remaining text in
`introduction.adoc` and the apidocs link in `keepControl_9.adoc` are still
#1840's to fix.
## 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-11.x`.
- The masthead shows **11.x**, and its Javadoc link points to
https://nightlies.apache.org/wicket/apidocs/11.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]