Skip to content

Style the 11.x reference guide like wicket.apache.org - #1937

Merged
dashorst merged 2 commits into
wicket-11.xfrom
user-guide-design-11.x
Nov 15, 2026
Merged

dashorst merged 2 commits into
wicket-11.xfrom
user-guide-design-11.x

Conversation

@dashorst

Copy link
Copy Markdown
Contributor

Summary

Testing

  • mvn -pl wicket-user-guide -Pguide generate-resources builds single.html and single.pdf.
  • Full mvn clean verify -Pjs-test on the branch: BUILD SUCCESS.
  • mvn -N apache-rat:check: passes.
  • git ls-tree -r --name-only HEAD wicket-user-guide | grep -iE '\.(woff2?|ttf|otf)$' returns nothing.
  • Rendered single.html: the title and masthead say 11.x, and the Javadoc link points to https://nightlies.apache.org/wicket/apidocs/11.x/index.html.
  • Listings: 522 of 527 are highlighted, and each has a language label and a copy button. The other 5 are not highlighted; the cause was not checked.
  • In a browser served over HTTP, the page makes no requests outside its own origin, and the fonts load locally.
  • Light mode, dark mode and a 390 px phone width were checked in a browser, and dark mode works.
  • Known gap, also on master and not changed here: at 1280 px the page scrolls 304 px sideways, because #footer keeps the full viewport width while getting margin-left: var(--toc-w). At 390 px the page is 408 px wide, which is the overflow Fix dark-mode table headers and mobile TOC overflow (#1891) #1903 addresses.

GitHub issue #1932

The guide used a 2017 copy of the minified default Asciidoctor
stylesheet, changed only for a sans-serif body (WICKET-6372), and it
had no syntax highlighting at all: the pom passed <sourceHighlighter>,
which asciidoctor-maven-plugin 2.x does not know and silently ignores,
so every listing rendered as plain text. The page also loaded Font
Awesome from cdnjs for the admonition icons.

The guide now keeps the plugin's default stylesheet and adds a small
override through docinfo, in the design of the project site: its
colour tokens, its self-hosted Alegreya and JetBrains Mono fonts (SIL
OFL, licences alongside) and its Rouge colours. Rouge is set through
the source-highlighter attribute. A masthead links to the site, the
Javadoc of the line and the other versions; the table of contents
follows the section being read and opens only that chapter; listings
get a language label and a copy button, and wicket:id and the wicket:
tags are marked in HTML samples; admonitions become asides; a dark
mode follows the system setting. Webfonts and the icon font are off,
so the page makes no external requests.

The body text moves back to a serif, as on the site, which reverses
WICKET-6372. The PDF keeps its font icons and is otherwise unchanged.
The design tokens are copied from the site's _sass/ribbon/_base.scss
and have to be kept in step with it by hand.

LICENSE lists the fonts under the SIL Open Font License next to the
fonts of the examples, and .rat-excludes covers their licence texts.
The Asciidoctor (MIT) entry and licenses/LICENSE-asciidoctor.txt go,
as the copied stylesheet they covered is gone from the source tree.

The page is usable without a mouse and with a screen reader: a skip
link comes first, #content and the table of contents are landmarks,
the logo link keeps its name on phones, a chapter's sections also open
while focus is inside it, the current entry carries aria-current, copy
buttons are named after their language and "Copied" is announced
through one status region. Diagrams get a white background in dark
mode so their dark lines stay visible.

The version line in the title, the masthead and the Javadoc link come
from the project version through build-helper's parse-version goal,
so nothing has to be changed by hand at a major release or on a
cherry-pick.

GitHub issue #1844
GitHub issue #1932

Generated-by: Claude Code (Claude Opus 5.5)
(cherry picked from commit 745ae01)
The guide's fonts, Alegreya, Alegreya Sans, Alegreya SC and JetBrains
Mono, are under the SIL Open Font License, which the ASF puts in
Category B: they may ship in a built artifact, but not in a source
release. release.sh builds the source release with git archive, so the
files in wicket-user-guide/src/main/asciidoc/fonts/ would have gone
into it.

The guide profile now unpacks them from the fontsource webjars
(org.webjars.npm:fontsource__*:5.3.0) into target/generated-docs/fonts/
in generate-sources: only the eight woff2 files that css/wicket.css
uses, each family with its licence as LICENSE-<family>.txt. The files
are byte for byte the ones removed, so the rendered guide is
unchanged. The fonts directory, its line in .rat-excludes and its
entry in LICENSE go.

The font stacks fall back to faces of the same kind that the systems
ship, for a guide built or read without the fonts: Iowan Old Style,
Palatino Linotype, Palatino, URW Palladio L and P052 before Georgia
for Alegreya; Seravek, Gill Sans Nova, Ubuntu and Calibri for Alegreya
Sans; Cascadia Code and Consolas join the monospace stack. They are
the site's stacks.

The fonts of wicket-examples are not part of this change.

GitHub issue #1846
GitHub issue #1932

Generated-by: Claude Code (Claude Opus 5.5)
(cherry picked from commit e5999f0)
@dashorst
dashorst merged commit 0740160 into wicket-11.x Nov 15, 2026
3 checks passed
@dashorst
dashorst deleted the user-guide-design-11.x branch November 15, 2026 10:38
@codecov-commenter

Copy link
Copy Markdown

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 62.70%. Comparing base (977e1a9) to head (8c54888).
⚠️ Report is 3 commits behind head on wicket-11.x.

Additional details and impacted files
@@                Coverage Diff                @@
##             wicket-11.x    #1937      +/-   ##
=================================================
- Coverage          62.72%   62.70%   -0.03%     
+ Complexity         11509    11508       -1     
=================================================
  Files               1254     1254              
  Lines              48665    48665              
  Branches            6845     6845              
=================================================
- Hits               30527    30517      -10     
- Misses             15460    15472      +12     
+ Partials            2678     2676       -2     
🚀 New features to boost your workflow:
  • ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.
  • 📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants