Customizing the Skin

Choosing a Customization Layer

Reach for the lightest layer that does the job. Built-in options are tested with every release; your own CSS and scripts are not.

[!TIP] Check the Options First Many changes need no CSS at all. Browse the Configuration Options before writing overrides.

Adding a Custom Stylesheet

1. Create src/site/resources/css/site.css in your project:

   /* src/site/resources/css/site.css */
   :root {
     --supa-content-max-width: 60rem;
   }
   

2. Run mvn site. Maven Site Plugin copies everything under src/site/resources/ to the site root, so the file lands at target/site/css/site.css.

Every page links your stylesheet immediately after the skin's own stylesheet, with a path relative to that page. A top-level page and a page in a subdirectory render:

<!-- index.html -->
<link rel="stylesheet" href="./css/supa-maven-skin.min.css" />
<link rel="stylesheet" href="./css/site.css" onerror="this.remove()" />

<!-- sub/page.html -->
<link rel="stylesheet" href="../css/supa-maven-skin.min.css" />
<link rel="stylesheet" href="../css/site.css" onerror="this.remove()" />

How your rules win:

• Source order: site.css loads after the skin's stylesheet, so your rule wins over a skin rule of equal specificity.
• Cascade layers: Bootstrap 6 places its styles in cascade layers (@layer), but the skin's own rules are unlayered. Any rule in your unlayered site.css beats Bootstrap's layered rules regardless of specificity. To beat a skin rule, match or exceed its specificity.
• Asset URLs: relative URLs inside a stylesheet resolve against the stylesheet's own location (css/). Reference a file in src/site/resources/images/ as url("../images/pattern.svg").

[!NOTE] When You Have No Custom Stylesheet If your project does not provide css/site.css, Doxia Sitetools writes a placeholder containing only /* You can override this file with your own styles */, so the link never fails in a normal mvn site build. The onerror="this.remove()" attribute only matters when pages are served without that file.

Injecting Extra <head> Content

Use the <head> element inside <body> in site.xml for markup that belongs in every page's <head>, such as a favicon, a web font stylesheet, or an extra script. Wrap the markup in <![CDATA[ ... ]]>: Maven Site Plugin requires XHTML content in <head> to be escaped (since version 3.5).

<body>
  <head>
    <![CDATA[
    <link rel="icon" type="image/svg+xml" href="./images/favicon.svg" />
    <script src="./js/custom.js" defer></script>
    ]]>
  </head>
  <menu name="Documentation">
    <!-- ... -->
  </menu>
</body>

Supa Maven Skin evaluates this block with Velocity separately for each page, so . becomes the path from the current page back to the site root. Put the referenced files in src/site/resources/images/ and src/site/resources/js/. The snippet above renders as:

<!-- index.html -->
<link rel="icon" type="image/svg+xml" href="./images/favicon.svg" />
<script src="./js/custom.js" defer></script>

<!-- sub/page.html -->
<link rel="icon" type="image/svg+xml" href="../images/favicon.svg" />
<script src="../js/custom.js" defer></script>

The injected markup appears near the end of <head>: after the skin's stylesheet, your site.css, and the <style id="supa-custom-css-variables"> block generated from <lightCssVariables> / <darkCssVariables>.

[!WARNING] Velocity Syntax in Head Content Because the block is evaluated as a Velocity template, text that looks like a Velocity reference ($name) or directive (#if, #set) is interpreted rather than copied. Keep JavaScript in separate files under src/site/resources/js/ instead of inline <script> blocks.

[!CAUTION] Avoid Root-Relative URLs A URL such as /js/custom.js only works when the site is served from the root of its domain. Sites published to a subdirectory (for example GitHub project pages at https://example.github.io/my-project/) need the . prefix.

// src/site/resources/js/custom.js
document.addEventListener('DOMContentLoaded', () => {
  const tocLinks = document.querySelectorAll('#supaTocNav a');
  console.log(`This page has ${tocLinks.length} table-of-contents links.`);
});

// src/site/resources/js/custom.js
function whenSupaReady(callback) {
  const html = document.documentElement;
  if (html.dataset.supaReady === 'true') {
    callback();
    return;
  }
  new MutationObserver((records, observer) => {
    if (html.dataset.supaReady === 'true') {
      observer.disconnect();
      callback();
    }
  }).observe(html, { attributes: true, attributeFilter: ['data-supa-ready'] });
}

whenSupaReady(() => {
  console.log(`${document.querySelectorAll('.mermaid svg').length} Mermaid diagrams rendered.`);
});

document.addEventListener('supa:theme-changed', (event) => {
  // event.detail.mode is 'light', 'dark', or 'auto'; event.detail.resolvedTheme is 'light' or 'dark'.
  console.log(event.detail.mode, event.detail.resolvedTheme);
});

document.addEventListener('supa:palette-changed', (event) => {
  console.log(event.detail.palette); // e.g. 'modus-tinted'
});

Overriding Design Tokens

Supa Maven Skin styles almost everything through CSS custom properties, so changing a token restyles every component that uses it, across all 6 color schemes and both polarities.

[!IMPORTANT] Override Source Tokens, Not Derived Ones The skin derives Bootstrap 6's component tokens (--primary-*, --success-*, --bg-*, --fg-*, and similar) from the tokens above. Override --color-brand-primary rather than --primary-bg, so brand-colored components stay consistent. Bootstrap focus rings and article links follow --color-brand-content; most skin-owned focus rings follow --color-brand-primary. Two do not: the options in the color-scheme menu follow --color-brand-content, and the links in the documentation channels follow --color-foreground-primary.

@font-face {
  font-family: "Inter";
  src: url("../fonts/Inter.woff2") format("woff2");
  font-display: swap;
}

:root {
  --font-stack: "Inter", system-ui, sans-serif;
  --supa-content-max-width: 60rem;
}

html[data-supa-palette="furo"] {
  --color-brand-primary: light-dark(#6d28d9, #c4b5fd);
  --color-brand-content: light-dark(#6d28d9, #c4b5fd);
}

Adding Logos and a Favicon

Put logo files in src/site/resources/images/ and reference them from <supaSkin>:

<custom>
  <supaSkin>
    <lightLogo>images/logo-light.svg</lightLogo>
    <darkLogo>images/logo-dark.svg</darkLogo>
    <sidebarBrandAlign>left</sidebarBrandAlign>
  </supaSkin>
</custom>

• Paths: write relative paths from the site root (images/logo-light.svg). The skin rewrites them for the directory of each page, so pages in subdirectories load the same file. Values with a URL scheme (such as https: or data:) or a leading / are used unchanged.
• One or two logos: with both options set, the skin shows <lightLogo> in light mode and <darkLogo> in dark mode. With only <lightLogo>, that image is used in both.
• Fallback: without <lightLogo>, the skin uses the <bannerLeft><image src="..."/></bannerLeft> image from site.xml. A <bannerLeft href="..."> also sets where the sidebar brand links to.
• Size: logos are limited to 2.75rem tall. The skin's rule uses two classes, so match them in site.css: .supa-sidebar-logo-container .supa-sidebar-logo { max-height: 3.5rem; }. A single-class .supa-sidebar-logo rule has no effect.

The <lightLogo> and <darkLogo> images carry generic alternative text (“Light Logo” and “Dark Logo”, or “Logo” when only <lightLogo> is set), so keep the project name visible next to the logo (the default; see <sidebarHideName> in Theme & Branding) to give the sidebar brand link a meaningful accessible name.

The skin has no favicon option. Add one with a <link rel="icon"> in <body><head>, as shown in Injecting Extra <head> Content.

Adjusting Page Furniture

Prefer a <supaSkin> option when one exists, because it removes the markup instead of hiding it:

See Configuration Options for every option and its default: most of these are under Layout & Navigation and Footer & Links, the color scheme picker is under Theme & Branding, the source buttons are under Source Repository, and search is under Code, Search, Diagrams & Math.

For elements without an option, or to restyle one, use site.css:

/* Hide the floating "Back to top" button. */
.supa-back-to-top {
  display: none;
}

/* Quieter announcement banner built from palette tokens. */
.supa-announcement {
  background-color: var(--color-background-secondary);
  color: var(--color-foreground-primary);
  border-bottom: 1px solid var(--color-background-border);
}

.supa-announcement a {
  color: var(--color-brand-content);
}

The announcement example reuses token pairs the skin already checks: the build verifies that --color-foreground-primary and --color-brand-content meet the scheme's contrast minimum on --color-background-secondary in every built-in scheme. Inventing new color pairs would bypass that check.

Translating the Skin's Labels

The skin's own interface text (search, navigation, the table of contents, the theme and color-scheme controls, copy buttons, the footer, and the default titles of admonitions) is English. Supa Maven Skin ships no translations: your site supplies the text for each label it wants to change in site.xml, and every label it leaves out stays English. Your own pages, menus, and page titles are already in whatever language you write them.

<plugin>
  <groupId>org.apache.maven.plugins</groupId>
  <artifactId>maven-site-plugin</artifactId>
  <configuration>
    <locales>default,fr</locales>
  </configuration>
</plugin>

Adjusting the Printed Page

When a reader prints a page or saves it as PDF, the skin's @media print styles print only the article. They leave out the sidebar, the “On this page” TOC, both drawers, the mobile header, the content header (breadcrumbs, source buttons, color-scheme and theme controls), the search box, the announcement banner, the skip link, the previous/next cards, the “Back to top” button, copy buttons, heading permalinks, tooltips, and floating toasts (a .toast-container.position-static in the article prints). The footer keeps only the copyright line, or your <body><footer>, so the printout still names who owns the text. The “Built with” credit, the “Last updated” date, and the footer icons are left out.

Other changes on paper:

• Colors: browsers print without backgrounds by default, so every page prints in the active color scheme's light polarity, even when the reader views it in dark mode, chosen in the theme menu or followed from the operating system in Auto mode. Text, links, code highlighting, admonitions, alerts, and tables print dark on white paper, and <darkCssVariables> overrides apply on screen only. Components whose text or state is drawn on a fill keep their light-polarity fills: badges, buttons, chips, avatars, progress bars, steppers, checkboxes, radios, switches, range sliders, strength meters, placeholders, breadcrumb dividers, active nav pills and links, active list-group items, and the current and disabled pagination links. Other backgrounds, such as the page, cards, code blocks, and an active tab, print as white paper, and tabs mark the active one with their borders. Shadows print at the light polarity's strength. A Mermaid diagram rendered in dark mode prints inverted into light colors.
• Layout: the article spans the page, long code lines and table cells wrap instead of scrolling, and nothing stays fixed or sticky.
• Links: an external link in the article prints its URL in parentheses after the link text, unless the text already is the URL. Links to other pages of the site, in-page links, and links in code blocks or navigation print as text only.
• Page breaks: headings stay with the content that follows them, and the browser avoids breaking inside code blocks, admonitions, alerts, cards, diagrams, figures, and table rows.
• Interactive content: only the selected tab of a tab group prints, and closed accordions and <details> stay closed. Readers open what they want on paper before printing.

To change the printout, add your own @media print block to site.css. The skin hides furniture with display: none !important, so a rule that shows an element again needs !important too:

/* src/site/resources/css/site.css */
@media print {
  /* Print the "Built with" line, which carries the "Last updated" date. */
  .supa-built-with {
    display: block !important;
  }

  /* Print link text only, without URLs. */
  .supa-article a::after {
    content: none !important;
  }

  /* Smaller text and wider margins on paper. */
  .supa-article {
    font-size: 11pt;
  }

  @page {
    margin: 2cm;
  }
}

Print your page in light and dark mode to check the result, or save it as PDF.

Choosing Selectors That Survive Upgrades

Supa Maven Skin prefixes everything it owns with supa (.supa-* classes, data-supa-* attributes, #supa* IDs, and --supa-* properties). The prefix marks ownership; it is not a compatibility promise. The skin is still in its 0.x series, so read the changelog when you upgrade. The hooks named in the configuration docs, plus a few page landmarks, are the safest choices:

Avoid these, because they are implementation details that can change in any release:

• Bookkeeping attributes the scripts add to avoid initializing an element twice, such as data-supa-tabs-ready or data-supa-drawer-bound.
• Derived and build-generated properties, such as Bootstrap 6's --primary-*, --bg-*, and --fg-* tokens, or --lightningcss-* properties in the compiled stylesheet.
• Long descendant chains through internal wrapper classes, such as .supa-sidebar-container .supa-nav-list .supa-nav-item. Target the element you need with the shortest selector that works.

Caveats

• Bootstrap 6 is an alpha. Supa Maven Skin builds on Bootstrap 6 (6.0.0-alpha.1). Bootstrap's own class names and tokens may change before a stable release, which is one more reason to customize through the skin's --color-* tokens.
• Your overrides are not contrast-checked. At build time, scripts/lint-scss.ts checks only the skin's built-in color schemes: text and accent tokens on both background surfaces, the text, link, and icon colors on admonition title bars and bodies and on .alert.theme-* callouts, the sidebar, TOC, and search-result states, and Bootstrap 6 components with and without a theme, at rest, hovered, and toggled on, in both polarities, against WCAG 2.2 AA (4.5:1) for furo and bootstrap and AAA (7.0:1) for the four modus* schemes. Check your own colors against the same minimums in light and dark mode.
• data-bs-theme on part of a page does not recolor it. The skin resolves its colors once, on <html>, so data-bs-theme="dark" on a section or card, or the Datepicker's datepickerTheme option, switches only browser-drawn controls such as form fields and scrollbars inside it, not the skin's or Bootstrap's colors. The whole page follows the reader's light, dark, or auto choice; to give one panel different colors, set them in site.css.
• --color-brand-primary is also a background. The announcement banner puts white text (light mode) or black text (dark mode) on --color-brand-primary, so check that pair whenever you change the brand color.
• Changes in target/site/ do not last. mvn site regenerates that directory. Always edit files under src/site/.