Migrating from Apache Maven Fluido Skin

Before You Begin

Step 1: Upgrade the Site Toolchain

Fluido 1.x (and, for item 1 only, Fluido 2.0.0-M milestones). Doxia Sitetools 2.0 still converts an old Decoration 1.x descriptor, but it logs a warning that the old model “will break in the future”. Upgrade the plugin and the descriptor together:

1. Upgrade the plugins. Set maven-site-plugin to 3.21.0 (or newer) and add doxia-module-markdown 2.2.0 if you write Markdown pages. The Quickstart Tutorial has a complete pom.xml block, including maven-project-info-reports-plugin.

2. Switch the descriptor schema. The root element changes from <project> (namespace http://maven.apache.org/DECORATION/1.x.0) to <site> (namespace http://maven.apache.org/SITE/2.0.0):

   <site xmlns="http://maven.apache.org/SITE/2.0.0"
         xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
         xsi:schemaLocation="http://maven.apache.org/SITE/2.0.0 https://maven.apache.org/xsd/site-2.0.0.xsd"
         name="${project.name}">
     <!-- skin, custom, and body elements go here -->
   </site>
   

3. Fix elements that Site 2.0.0 dropped or reshaped. The 2.0.0 schema has no <googleAnalyticsAccountId> element (see Social, Analytics, and Ribbons below), and the img / alt attributes on menus, menu items, links, and poweredBy logos became an <image src="..." alt="..."/> child element.

4. Rewrite the banners. In Decoration 1.x, <bannerLeft> and <bannerRight> hold <name>, <src>, <alt>, and <href> child elements. In Site 2.0.0, name and href are attributes and the logo is an <image> child element. Supa Maven Skin builds its sidebar brand from <bannerLeft>, so convert it:

   <!-- Before (Decoration 1.x) -->
   <bannerLeft>
     <name>My Project</name>
     <src>images/logo.png</src>
     <href>https://example.org/</href>
   </bannerLeft>
   
   <!-- After (Site 2.0.0) -->
   <bannerLeft name="My Project" href="https://example.org/">
     <image src="images/logo.png" alt="My Project"/>
   </bannerLeft>
   

Validate the result against the site descriptor reference. If you want to separate toolchain problems from skin problems, build once with Fluido 2.1.0 at this point: its skin.xml requires Doxia Sitetools 2.0.0, and its own site build uses maven-site-plugin 3.21.0.

Step 2: Replace the Skin

Replace the Fluido <skin> element in src/site/site.xml:

<!-- Before -->
<skin>
  <groupId>org.apache.maven.skins</groupId>
  <artifactId>maven-fluido-skin</artifactId>
  <version>2.1.0</version>
</skin>

<!-- After -->
<skin>
  <groupId>io.github.mepcotterell</groupId>
  <artifactId>supa-maven-skin</artifactId>
  <version>0.2.0</version>
</skin>

After completing the remaining configuration changes below, run mvn clean site as described in the Verification Checklist, including when switching back to Fluido.

Check for a newer release of io.github.mepcotterell:supa-maven-skin on Maven Central; the Quickstart Tutorial shows the complete site.xml. Supa Maven Skin packages its CSS, JavaScript, and icon fonts inside the skin JAR, so consumer projects do not need Node.js or any extra build plugin.

Step 3: Rename the Configuration Block

Supa Maven Skin reads <custom><supaSkin> (or the legacy <custom><furoSkin>) and ignores <custom><fluidoSkin>. Fluido reads only <fluidoSkin> (plus the top-level <custom><matomo> block). That means you can keep both blocks while you migrate and switch back by changing only <skin>:

<custom>
  <!-- Read by Supa Maven Skin -->
  <supaSkin>
    <defaultTheme>auto</defaultTheme>
    <colorScheme>furo</colorScheme>
    <sourceRepository>https://github.com/your-org/your-repo</sourceRepository>
    <sourceBranch>main</sourceBranch>
    <lightLogo>images/logo.svg</lightLogo>
    <navIcons>
      <icon>
        <href>https://github.com/your-org/your-repo</href>
        <title>GitHub Repository</title>
        <html><![CDATA[<i class="bi bi-github" aria-hidden="true"></i>]]></html>
      </icon>
    </navIcons>
  </supaSkin>

  <!-- Read by Fluido only; delete once the migration is done -->
  <fluidoSkin>
    <topBarEnabled>true</topBarEnabled>
    <gitHub>
      <projectId>your-org/your-repo</projectId>
    </gitHub>
  </fluidoSkin>
</custom>

Do not just rename <fluidoSkin> to <supaSkin>: almost none of the option names overlap. Translate each option with the option mapping reference, and see the Configuration Reference for every <supaSkin> option and its default.

Step 4: Review Custom CSS and Resources

• css/site.css still loads. Both skins link css/site.css after their own stylesheet, so an existing src/site/resources/css/site.css is picked up unchanged. Remove rules that target Fluido markup (#banner, #breadcrumbs, #leftColumn, #bodyColumn, .sidebar-nav, #poweredBy). They no longer match anything, and some may fight the new layout.
• Fluido's images are not shipped. The Fluido JAR provides files such as images/logos/maven-feather.png, images/accessories-text-editor.png, images/icon_info_sml.gif, and the Glyphicons sprites in img/. The Supa Maven Skin JAR ships only css/, js/, and css/fonts/. If a page references one of Fluido's images, copy your own version into src/site/resources/images/.
• No jQuery. Fluido bundles jQuery 1.11.2 and the Bootstrap v2.3.2 jQuery plugins. Supa Maven Skin bundles neither, so inline scripts that call $(...) or rely on data-toggle plugins need a rewrite (see Updating Hand-Written Markup).

Option Mapping Reference

Every option that Fluido 2.1.0 and 1.12.0 read from <custom><fluidoSkin>, with its Supa Maven Skin replacement. Options marked “No equivalent” are ignored by Supa Maven Skin, so you can safely leave them in place until you delete the <fluidoSkin> block.

/* src/site/resources/css/site.css */
html:root {
  --supa-sidebar-width: 18rem;
  --supa-content-max-width: 64rem;
}

<body>
  <head>
    <![CDATA[<script async src="https://analytics.example.com/tracker.js"></script>]]>
  </head>
</body>

How Site Descriptor Elements Render

Fluido and Supa Maven Skin both read the standard site.xml elements, but Supa Maven Skin renders some of them differently and ignores others:

Updating Hand-Written Markup

Doxia-generated content (headings, lists, tables, code blocks, and report pages) needs no changes. Supa Maven Skin restyles it at runtime: Doxia tables become responsive Bootstrap 6 tables, <pre><code> blocks are highlighted, and headings get a table-of-contents entry and a permalink. Supa Maven Skin keeps the id anchors that Doxia generates for headings, so deep links that work with Fluido 2.x keep working. Coming from Fluido 1.x also means moving from Doxia 1.x to Doxia 2, which encodes some characters differently: Doxia 1.x's DoxiaUtils.encodeId kept : in anchors (Step_2:_Install), while the Doxia 2 version encodes it (Step_2.3A_Install). Recheck deep links to headings that contain punctuation.

Hand-written HTML in .md, .xhtml, or .xdoc pages is a different story. Fluido styled it with Bootstrap v2.3.2, whose class names are mostly gone in Bootstrap 6:

[!TIP] Wrap Raw Components in .not-prose The article column applies Bootstrap 6 prose typography (margins, list spacing, heading sizes) to everything inside it. Add not-prose to a hand-written component wrapper (for example <div class="card not-prose">) so those rules skip it. Headings inside a .not-prose element are also left out of the “On this page” table of contents.

Verification Checklist

After completing the skin and configuration changes, rebuild with mvn clean site. Doxia Sitetools 2 skips pages whose source is unchanged during a plain mvn site, even when the skin or site.xml has changed. See Old Skin or Labels After a Rebuild.

After the clean build succeeds, preview the site over HTTP with mvn site:run (or python3 -m http.server 8000 --directory target/site) and check the following. Pages opened from file:// skip the skin's JavaScript, so search, the theme and color scheme controls, the “On this page” table of contents, and other enhancements would look broken; see Previewing Your Site.

• [ ] The build log shows no errors from parsing site.xml, and the generator comment at the top of each page reads “Rendered using Supa Maven Skin”.
• [ ] The sidebar brand shows the right name and logo, and every menu, including ref="reports" and ref="modules", appears in the left sidebar.
• [ ] Every link that used to live in <links>, <bannerRight>, or <poweredBy> has a new home in a <menu> or <navIcons>.
• [ ] On pages in subdirectories, sidebar, breadcrumb, footer icon, and Previous / Next links open the right pages, and the sidebar highlights the current page. Hrefs migrated from Fluido no longer start with / (see Pages in Subdirectories).
• [ ] “View page source” and “Edit this page” open the right files, if you configured <sourceRepository>.
• [ ] Hand-written alerts, wells, labels, buttons, and icons render with Bootstrap 6 classes, and no image request points at Fluido's images/ or img/ folders.
• [ ] Analytics or other scripts moved to <body><head> load once per page.
• [ ] Search finds your pages. It fetches up to 30 sidebar-linked pages in the browser.
• [ ] Pages read well in Light and Dark mode and in at least one high-contrast color scheme (modus).

Next, tune colors and layout in the Configuration Reference, or browse Authoring Rich Content for the components that replace Fluido-era markup.