Repository navigation
Style the wicket-10.x reference guide like wicket.apache.org - #1933
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 #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)
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.
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:parse-version.guideprofile, 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 theasciidoctorj-pdf(2.3.27) andasciidoctorj-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-resourcesbuilds 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.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
#footerwidth:100%, and the guide'smargin-leftfor the TOC pushes it past the edge. The CSS is the same on master, so the fix belongs there first.🤖 Generated with Claude Code