Repository navigation
Style the 11.x reference guide like wicket.apache.org - #1937
Merged
Merged
Conversation
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)
Codecov Report✅ All modified and coverable lines are covered by tests. 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:
|
This was referenced Nov 15, 2026
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
745ae018ec(style) ande5999f0896(fonts). Both keep the-xline, and neither needed an 11.x-specific change..rat-excludesline andlicenses/LICENSE-asciidoctor.txt.single.adoc, resolved to master's= Wicket {wicket_line} Reference Guide.Testing
mvn -pl wicket-user-guide -Pguide generate-resourcesbuildssingle.htmlandsingle.pdf.mvn clean verify -Pjs-teston 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.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.#footerkeeps the full viewport width while gettingmargin-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