Skip to content

Commit 5b61dfc

Browse files
brunoborgesbrunoborges
committed
Add documentation for custom site and JaCoCo CSS theming
1 parent a36fa1c commit 5b61dfc

File tree

1 file changed

+187
-0
lines changed

1 file changed

+187
-0
lines changed

‎docs/CUSTOM_SITE_CSS.md‎

Lines changed: 187 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,187 @@
1+
# Custom Site CSS
2+
3+
This project applies custom CSS themes to both the **Maven-generated documentation site** and the **JaCoCo coverage reports** so they share a consistent visual identity: light backgrounds, GitHub-inspired colors, purple gradient accents, and rounded card-style containers.
4+
5+
## Architecture Overview
6+
7+
```
8+
src/site/
9+
├── resources/
10+
│ ├── css/
11+
│ │ └── site.css ← Maven site theme (loaded automatically by Fluido)
12+
│ └── images/
13+
│ └── github-copilot.jpg ← Copilot logo for "Powered By" sidebar
14+
├── jacoco-resources/
15+
│ └── report.css ← JaCoCo report theme (overlaid after generation)
16+
└── site.xml ← Fluido skin configuration
17+
18+
.github/
19+
├── templates/
20+
│ ├── index.html ← Version picker page template
21+
│ └── styles.css ← Version picker CSS
22+
└── workflows/
23+
└── deploy-site.yml ← Deploys site + overlays JaCoCo CSS
24+
```
25+
26+
## Maven Site Theme (`src/site/resources/css/site.css`)
27+
28+
### How It Works
29+
30+
The Maven Fluido Skin 2.1.0 (configured in `src/site/site.xml`) automatically loads `css/site.css` from the site resources directory. No additional configuration is needed — placing the file at `src/site/resources/css/site.css` is sufficient.
31+
32+
### Design Choices
33+
34+
| Element | Style |
35+
|---------|-------|
36+
| **Navbar** | Dark (`#24292f`) with no gradient or border, subtle box shadow |
37+
| **Sidebar** | White card with rounded corners (`border-radius: 10px`), 1px border |
38+
| **Active nav item** | Purple gradient (`#667eea → #764ba2`) |
39+
| **Links** | GitHub-blue (`#0969da`), hover darkens to `#0550ae` |
40+
| **Code blocks** | Light gray background (`#eef1f6`) to distinguish from the white page |
41+
| **Inline code** | Tinted purple background (`rgba(102, 126, 234, 0.1)`) |
42+
| **Tables** | Rounded borders, light header, subtle row hover |
43+
| **Sections** | White card with border and padding (nested sections are transparent) |
44+
| **Alerts** | Rounded with 4px left accent border, color-coded (info/warning/danger/success) |
45+
| **Typography** | System font stack (`-apple-system, BlinkMacSystemFont, 'Segoe UI', ...`) |
46+
47+
### GitHub Ribbon Override
48+
49+
The Fluido skin renders a "Fork me on GitHub" ribbon using a `::after` pseudo-element with `content: attr(data-ribbon)`. We override this to say "View on GitHub" with a purple gradient background:
50+
51+
```css
52+
.github-fork-ribbon:before {
53+
background-color: #667eea !important;
54+
background-image: linear-gradient(135deg, #667eea, #764ba2) !important;
55+
}
56+
57+
.github-fork-ribbon:after {
58+
content: 'View on GitHub' !important;
59+
}
60+
```
61+
62+
> **Note:** Both `background-color` and `background-image` with `!important` are required because Fluido injects an inline `<style>` tag that sets the ribbon background.
63+
64+
### Powered By — GitHub Copilot Logo
65+
66+
The `poweredBy` section in Fluido's sidebar doesn't support custom entries via `site.xml` (the `<poweredBy>` element isn't supported in Maven Site Descriptor 2.0.0). Instead, the logo is injected via a CSS `::after` pseudo-element on the `#poweredBy` div:
67+
68+
```css
69+
#poweredBy::after {
70+
content: '';
71+
display: block;
72+
width: 240px;
73+
height: 120px;
74+
background-image: url('../images/github-copilot.jpg');
75+
background-size: contain;
76+
background-repeat: no-repeat;
77+
background-position: center;
78+
}
79+
```
80+
81+
The logo image is stored at `src/site/resources/images/github-copilot.jpg`.
82+
83+
## JaCoCo Report Theme (`src/site/jacoco-resources/report.css`)
84+
85+
### The Challenge
86+
87+
JaCoCo generates standalone HTML reports with their own `report.css`, completely independent of the Maven site theme. The generated reports reference `jacoco-resources/report.css` via a `<link>` tag. There is no built-in mechanism to customize this CSS.
88+
89+
### How the Overlay Works
90+
91+
The custom CSS is applied by **replacing** JaCoCo's default `report.css` after report generation. This happens through two mechanisms:
92+
93+
#### 1. Maven build phase (local builds)
94+
95+
In `pom.xml`, a `maven-resources-plugin` execution runs during the `site` phase — **after** JaCoCo has generated its report and default CSS:
96+
97+
```xml
98+
<execution>
99+
<id>overlay-jacoco-css</id>
100+
<phase>site</phase>
101+
<goals>
102+
<goal>copy-resources</goal>
103+
</goals>
104+
<configuration>
105+
<outputDirectory>${project.reporting.outputDirectory}/jacoco/jacoco-resources</outputDirectory>
106+
<resources>
107+
<resource>
108+
<directory>src/site/jacoco-resources</directory>
109+
<filtering>false</filtering>
110+
</resource>
111+
</resources>
112+
<overwrite>true</overwrite>
113+
</configuration>
114+
</execution>
115+
```
116+
117+
#### 2. Deploy workflow (CI builds)
118+
119+
The deploy workflow (`deploy-site.yml`) has a catch-all step that overlays the CSS across **all version directories** in the site. This covers cases where the Maven overlay ran in a different directory structure:
120+
121+
```yaml
122+
- name: Overlay custom JaCoCo CSS
123+
run: |
124+
cd site
125+
for dir in */jacoco/jacoco-resources; do
126+
if [ -d "$dir" ]; then
127+
cp ../src/site/jacoco-resources/report.css "$dir/report.css"
128+
echo "Overlaid JaCoCo CSS in $dir"
129+
fi
130+
done
131+
```
132+
133+
### Important: JaCoCo Report Path
134+
135+
The JaCoCo **reporting** plugin (used during `mvn site`) outputs to `jacoco/` by default. The **build** plugin execution (`build-coverage-report-from-tests`, phase `verify`) outputs to `jacoco-coverage/`. Only the reporting plugin path matters for the deployed site, since the deploy workflow runs `mvn site`, not `mvn verify`.
136+
137+
### Design Choices
138+
139+
The JaCoCo theme mirrors the main site design:
140+
141+
| Element | Style |
142+
|---------|-------|
143+
| **Background** | Light gray (`#f6f8fa`), same as main site |
144+
| **Coverage table** | White card with rounded corners, sticky header |
145+
| **Row hover** | Subtle purple tint (`rgba(102, 126, 234, 0.04)`) |
146+
| **Source code** | White background with rounded border |
147+
| **Coverage highlights** | Green (`#dafbe1`) for covered, red (`#ffeef0`) for missed, yellow (`#fff8c5`) for partial |
148+
| **Branch hover** | Saturated versions of coverage colors |
149+
| **Typography** | Same system font stack and monospace fonts as main site |
150+
151+
### When JaCoCo Reports Are Available
152+
153+
JaCoCo only generates a report when test execution data (`.exec` file) exists:
154+
155+
- **Snapshot builds in CI**: The deploy workflow downloads test results from the "Build & Test" workflow and restores the `.exec` file before running `mvn site`. Reports are generated.
156+
- **Release tag builds**: Tests don't run at tag checkout, so no `.exec` file exists and JaCoCo skips report generation. No report to style.
157+
- **Local builds**: Run `mvn clean verify site` to ensure tests run first and the `.exec` file is available for report generation.
158+
159+
## Version Picker Page (`.github/templates/`)
160+
161+
The `index.html` and `styles.css` in `.github/templates/` power the top-level version picker at the documentation root. These are **not** part of the Maven site — they are copied directly by the deploy workflow.
162+
163+
The styles use the same design language (purple gradients, rounded cards, GitHub-blue links) but are a standalone CSS file with no dependency on Bootstrap or Fluido.
164+
165+
## Modifying the Theme
166+
167+
### Maven site CSS
168+
169+
Edit `src/site/resources/css/site.css`. Changes take effect on the next `mvn site` build. Preview locally:
170+
171+
```bash
172+
mvn clean site -DskipTests -Dcheckstyle.skip=true
173+
open target/site/index.html
174+
```
175+
176+
### JaCoCo report CSS
177+
178+
Edit `src/site/jacoco-resources/report.css`. Preview locally (requires test data):
179+
180+
```bash
181+
mvn clean verify site
182+
open target/site/jacoco/index.html
183+
```
184+
185+
### Version picker page
186+
187+
Edit `.github/templates/index.html` and `.github/templates/styles.css`. These are deployed as-is by the workflow — no build step needed. Preview by opening `index.html` directly in a browser.

0 commit comments

Comments
 (0)