Skip to content

Style the wicket-10.x reference guide like wicket.apache.org - #1933

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

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

Conversation

@dashorst

Copy link
Copy Markdown
Contributor

Brings the restyled reference guide from master to the 10.x line (#1931). Both commits are cherry-picked with -x, in order, and keep their master messages:

  1. Style the reference guide like wicket.apache.org (745ae01, Style the reference guide like wicket.apache.org #1845): Rouge highlighting, the docinfo masthead, the following TOC, language labels and copy buttons, asides for admonitions, dark mode, no external requests, the accessibility fixes, and the version line taken from the pom through build-helper's parse-version.
  2. Take the reference guide's fonts from webjars at build time (e5999f0, Take the reference guide's fonts from webjars at build time #1896): the SIL OFL fonts (ASF Category B) come from the fontsource webjars in the guide profile, so they are not in the source tree. The two commits belong together; the first alone would put the fonts into the 10.x source release.

The only conflict was the title in single.adoc: 10.x had = Wicket 10.x Reference Guide. I took master's = Wicket {wicket_line} Reference Guide, which renders as 10.x because the version comes from the pom. The second commit applied cleanly. No 10.x adaptation was needed. The guide pom now equals master's apart from the project version and the asciidoctorj-pdf (2.3.27) and asciidoctorj-diagram (2.3.2) versions 10.x already had. build-helper is managed in the root pom, and the pedantic enforcer passes.

The change touches only the guide module, LICENSE (the Asciidoctor stylesheet entry goes) and .rat-excludes. No shipped jar changes.

Tested

  • mvn clean verify -Pjs-test: green.
  • mvn -N apache-rat:check: passes.
  • mvn -pl wicket-user-guide -Pguide generate-resources builds HTML and PDF. The title and masthead say 10.x, and the Javadoc link is https://nightlies.apache.org/wicket/apidocs/10.x/index.html.
  • Checked in headless Chromium at 1400px and 390px, light and dark: 519 highlighted listings with labels and copy buttons; all fonts loaded from fonts/; no requests outside the local files; no script errors.
  • git ls-tree -r --name-only HEAD wicket-user-guide | grep -iE '\.(woff2?|ttf|otf)$' returns nothing.

Not included

🤖 Generated with Claude Code

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 #1931

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 #1931

Generated-by: Claude Code (Claude Opus 5.5)
(cherry picked from commit e5999f0)
@dashorst dashorst self-assigned this Nov 15, 2026
@dashorst
dashorst merged commit 7b8455b into wicket-10.x Nov 15, 2026
3 checks passed
@dashorst
dashorst deleted the user-guide-design-10.x branch November 15, 2026 10:37
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.

1 participant