Troubleshooting

Admonitions, Tabs, and the Table of Contents Are Missing

The page has the skin's colors and layout, but > [!NOTE] blocks are plain blockquotes, .supa-tabs panels are stacked, headings have no # permalink, and the right-hand “On this page” column is empty.

Cause: You opened the page straight from disk (a file:// URL such as target/site/index.html). Supa Maven Skin loads its script as a JavaScript module (<script type="module">), and browsers such as Chrome and Firefox do not run module scripts on pages opened from file://. Chrome reports it in the console as Access to script at '…/js/supa-maven-skin.min.js' from origin 'null' has been blocked by CORS policy. The stylesheet and the small inline theme script in <head> still run, which is why the page looks partly styled.

Fix: Preview the site over HTTP instead:

# Render and serve the site on http://localhost:8080
mvn site:run

# Or serve an already-generated site with any static file server
python3 -m http.server 8000 --directory target/site

Old Skin or Labels After a Rebuild

Some pages still show the old skin or old labels after changing site.xml or the skin version.

Cause: Doxia Sitetools 2 skips pages whose source is unchanged during a plain mvn site, even when the skin or site.xml has changed. Generated reports can pick up the new settings while authored pages keep the old skin, labels, language, or options.

Fix: After changing the skin or site.xml (including a locale's site_<lang>.xml), rebuild every page:

mvn clean site

clean removes target/, so save any old site you want to compare outside target/ first. Then preview the rebuilt site over HTTP.

Search Results Are Out of Date After a Rebuild

You rebuilt the site, but the search dialog still lists old headings or misses new pages.

Cause: The first time you open search, Supa Maven Skin fetches the other pages and caches the index in the tab's sessionStorage under a key that starts with supa-search-index-<project version>, followed by the page language and the URL of the site root (each locale of a multi-locale site has its own). When you rebuild with the same version (for example a -SNAPSHOT), the cache key stays the same, so that tab keeps using the old index.

Fix: Open the site in a new tab (each tab has its own sessionStorage), or remove the supa-search-index-… entries under Session Storage in your browser's developer tools.

A Second-Level Heading Disappeared

A ## Section line in a .md.vm file is missing from the rendered page and from the table of contents.

Cause: Velocity treats everything from ## to the end of the line as a comment and removes it before Markdown parsing. A level-1 heading (# Title) survives because # followed by a space is not a directive.

Fix: Wrap the hash marks in Velocity's unparsed-content syntax so they reach the Markdown parser unchanged:

#[[##]]# Maven Coordinates
#[[###]]# Subsection

A Code Sample Shows a Real Value Instead of ${project.version}

You wanted readers to see a literal Maven placeholder in a code block, but the rendered page shows 1.0.0-SNAPSHOT (or whatever your project version is).

Cause: Velocity replaces every reference it can resolve, including references inside fenced code blocks. References it cannot resolve, such as $HOME, are left as written. That is why only some dollar signs change.

Fix: Wrap the whole fenced block in #[[ ... ]]# so Velocity copies it unchanged. For a single reference you can also escape the dollar sign (\${project.version} renders as ${project.version}). Escape only references Velocity would otherwise replace: inside a code block, Velocity keeps the backslash in front of an undefined reference, so \$HOME stays \$HOME.

#[[
```xml
<version>${project.version}</version>
```
]]#

The Build Fails With “Error parsing … as a Velocity template”

mvn site stops with BUILD FAILURE and a message such as Failed to render site: Error parsing src/site/markdown/page.md.vm as a Velocity template: Encountered "DEBUG" or The #define directive requires one argument.

Cause: Velocity reads # followed by a directive name as a directive, even inside fenced code blocks. C preprocessor lines such as #if DEBUG, #else, and #define FOO 1 (and lines starting with #foreach, #macro, #parse, or #end) are not valid Velocity syntax, so parsing fails and the whole site build stops. Lines such as #ifdef and #endif are not Velocity directive names and pass through unchanged.

Fix: Wrap the code block in #[[ ... ]]# as shown above, or move the page to a plain .md file if it does not need any Velocity features.

Part of a Code Sample or Page Vanished

A C sample such as #include <stdio.h> renders as <stdio.h>, losing the #include part, or everything after a line starting with #stop is missing.

Cause: These are also Velocity directives. For #include without parentheses, Velocity drops the directive name and keeps the rest of the line. #stop ends template processing, so the rest of the page is never rendered.

Fix: Wrap the code block in #[[ ... ]]#, or use a plain .md file.

A Macro Call Appears as Literal Text

The page shows text like #bi( "rocket" "" "" ) instead of an icon or component.

Cause: Helper macros such as #bi, #bsAlert, #bsBadge, and #bsCard are Velocity macros. They only run in files processed by Velocity (.md.vm). In a plain .md file they are ordinary text.

Fix: Rename the file to .md.vm (and escape any ## headings as described above), or use the plain-Markdown equivalents: :bi-rocket: shortcodes for icons and > [!ALERT:primary] blockquotes for alerts. See Adding Bootstrap Icons.

Part of an HTML Block Renders as a Code Block

Inside a raw HTML wrapper such as <div class="supa-tabs">, some of your HTML appears as escaped source text in a grey code block.

Cause: In CommonMark, a blank line ends a raw HTML block. The parser treats the lines after it as Markdown again, and lines indented by four or more spaces become an indented code block.

Fix: Keep multi-line HTML wrappers free of blank lines. If you need an empty line inside an HTML <pre><code> block, write 
 instead.

<div class="supa-tabs" title="build-tool">
  <div title="Maven">
    <p>First paragraph.</p>
    <p>Second paragraph, with no blank line in between.</p>
  </div>
</div>

A Blockquote Did Not Become an Admonition

A blockquote that starts with an admonition marker renders as a plain quote.

Cause: Supa Maven Skin only converts a blockquote when its first paragraph starts with one of the supported markers. Markers are case-insensitive, but they must be the very first text and must not be wrapped in formatting. Unsupported types such as [!INFO] and formatted markers such as **[!WARNING]** are left as blockquotes.

Fix: Use one of the supported markers on the first line: [!NOTE], [!SEEALSO] (or [!SEE-ALSO]), [!TIP], [!HINT], [!IMPORTANT], [!ADMONITION], [!WARNING], [!CAUTION], [!ATTENTION], [!DANGER], [!ERROR], [!TODO], or [!ALERT:<theme>]. See Writing Admonitions and Alerts.

An Admonition Shows a Title but No Body

The admonition box shows your sentence in its title bar and nothing underneath.

Cause: Any text after the marker on the same line becomes the admonition's custom title.

Fix: Start the body on the next line:

> [!NOTE] Optional Custom Title
> The body starts on the second line.

An Icon Shortcode Renders Nothing or Stays as Text

A :bi-...: shortcode leaves a blank gap, or stays as literal text.

Cause: Shortcode icon names must be lowercase (:bi-ROCKET: is left as text). A lowercase name that is not a real Bootstrap Icons name still produces an <i> element, but the icon font has no glyph for it, so nothing is visible. Shortcodes inside inline code, code blocks, <kbd>, and <samp> are intentionally left as text.

Fix: Copy the exact icon name from the Bootstrap Icons catalogue and write it in lowercase, for example :bi-rocket-takeoff:.

A Datepicker, Combobox, or Carousel Does Nothing

The rest of the page works, but a widget stays plain HTML: a Datepicker is an ordinary text field, a Combobox does not open, a carousel never moves. The browser console shows Supa Maven Skin: could not load the Datepicker script; its markup stays plain HTML. (with the widget's name), usually next to a failed request for a file in js/.

Cause: To keep every page light, the skin loads the scripts for its less common Bootstrap 6 widgets (Carousel, Chips, Combobox, Datepicker, NavOverflow, OtpInput, Range, Strength, Tab, and the Component Playground) only on pages that contain them, as separate files next to the main script: js/supa-maven-skin-datepicker.min.js, js/supa-maven-skin-combobox.min.js, and so on. The browser could not load that file:

• The deployment copied js/supa-maven-skin.min.js but not the other js/supa-maven-skin-*.min.js files.
• A Content Security Policy only allows specific script URLs instead of the site's own origin.
• After a skin upgrade, a browser or CDN cache serves the old main script next to the new widget files. The files are not renamed between versions, so the two do not fit together.

Fix: Publish the whole generated target/site/ directory, including every file in js/. If the site sends a Content Security Policy, allow the site's own scripts (script-src 'self'). Also follow Content Security Policy for the inline anti-FOUC script's hash and the stylesheet error handler's behavior under a strict policy. After an upgrade, purge the CDN cache or force-reload the page.

If the console shows no such warning and the widget's markup was added by a script of your own after the page loaded, see Running Scripts After the Skin Initializes.

A Code Block Is Not Syntax Highlighted

A fenced code block renders in a single color.

Cause: One of the following:

• The fence has no language. Doxia marks such blocks nohighlight, so they are never highlighted.
• The language is not one of the grammars bundled with Supa Maven Skin. The browser console then shows “Could not find the language ‘…’”, and the block falls back to plain text. The bundled grammars are Bash (bash, sh, zsh), shell sessions with prompts (shell, console), css, diff (patch), groovy, java, JavaScript (javascript, js, jsx, mjs, cjs), json, Kotlin (kotlin, kt, kts), Markdown (markdown, md), plain text (plaintext, text, txt), properties, Python (python, py), scss, sql, TypeScript (typescript, ts, tsx), XML and HTML (xml, html, svg, xsd, xsl), and yaml (yml). The velocity and vm names are accepted but use the XML highlighter, so Velocity directives themselves are not colored.
• The block contains HTML elements, for example a raw <pre><code> block with <b> tags, or the linked URLs that Maven project reports put inside <pre>. Supa Maven Skin deliberately skips highlighting such blocks so that the links and markup stay intact.
• <syntaxHighlighting> is set to false in site.xml.

Fix: Add a bundled language name after the opening fence (for example java or xml), or use text for output that should stay plain. Blocks that contain HTML elements are left unhighlighted on purpose.

The Copy Button Says “Copy failed”

Clicking a code block's copy button shows a cross icon and the tooltip “Copy failed”, and the clipboard keeps its old contents.

Cause: The browser blocked both ways Supa Maven Skin copies text. It first uses the asynchronous Clipboard API (navigator.clipboard), which browsers only provide in secure contexts: pages served over HTTPS, or from localhost and 127.0.0.1. When that API is missing (on a site served over plain HTTP from another host, such as an internal staging server) or clipboard access is denied, the skin falls back to the older document.execCommand('copy'), which some browsers and embedded webviews also block.

Fix: Serve the site over HTTPS, or preview it from localhost. Readers can still select the code and copy it manually.

A Link to a Heading Does Not Jump to It

A link such as page.html#my-section, perhaps a sub-item in site.xml, opens the page but does not scroll to the heading.

Cause: Heading IDs are assigned in the browser by Supa Maven Skin, and they may differ from the slug you guessed. The rules are:

• The text is lowercased, and every character other than letters, digits, _, spaces, and hyphens is removed. Dots, parentheses, backticks, and emoji disappear, so (.md.vm) becomes mdvm. Letters and digits of every script are kept, accents included, so Überblick becomes überblick and 概要 stays 概要. A heading with no letters or digits at all gets the ID section.
• Runs of spaces, underscores, and hyphens become a single -.
• Repeated headings get -2, -3, and so on.

Doxia's own anchors (such as #My_Section) are kept, so older links keep working.

Fix: Do not guess the ID. Open the rendered page, hover over the heading, and copy the link from its # permalink, or copy the entry from the “On this page” column. In a Markdown page, write an ID with non-ASCII letters in plain characters (#überblick), not percent-encoded (see the next entry).

Links to Headings With Non-ASCII Letters Changed After Upgrading to 0.1.6

After you upgrade Supa Maven Skin to 0.1.6, links to headings that contain accented or non-Latin letters (German, Japanese, Cyrillic, Greek, or Hindi headings, for example) open the right page but no longer jump to the heading.

Cause: Before 0.1.6, heading IDs kept only ASCII letters and digits. Every other letter was dropped, so Überblick became berblick, and a heading with no ASCII letters at all became section, then section-2, section-3, and so on in page order. Since 0.1.6, IDs keep the letters, accents, and digits of every script. IDs of headings written only in ASCII did not change, with one exception: on a page that also has headings with non-ASCII letters, the -2 or -3 suffix of a repeated ASCII heading can change, and an old link without a suffix can now open a different heading.

Fix: Update the links to these headings, for example guide.html#berblick becomes guide.html#überblick, and check links to repeated ASCII headings on the same pages. The new ID follows the rules in the previous entry. Write it in the form that fits where the link lives:

• In a Markdown page, write the ID in plain characters: [Überblick](guide.html#überblick). Doxia rewrites the fragment of every relative link in a Markdown page into its own encoding (guide.html#a.C3.BCberblick), and Supa Maven Skin adds an anchor with that encoded ID before each heading whose ID Doxia rewrites, so the link still lands on the heading. Do not paste the percent-encoded form there: Doxia encodes its % signs too (#a.25C3.25BCberblick), and no anchor has that ID.
• In a site.xml menu item, either form works (guide.html#überblick or guide.html#%C3%BCberblick), because the href reaches the page unchanged and browsers treat both forms the same.
• In email, chat, and other plain text, paste the full URL the # permalink copies. It is percent-encoded (https://example.org/guide.html#%C3%BCberblick), so linkifiers keep it whole.

Doxia's own anchor for the heading (#a.C3.9Cberblick for Überblick) did not change and still works.

Doxia rewrites the fragment of a Markdown link whenever it is not a valid Doxia ID, one that starts with an ASCII letter or _ and holds only ASCII letters, digits, _, -, and .. That includes the ID of every heading that starts with a digit: [1. Install](#1-install) is written as #a1-install, and Supa Maven Skin adds that anchor before the heading too. Before 0.1.7, such a link opened the page without jumping to the heading.

One limit remains: the rewritten ID can be an ID that another element on the page already has. Supa Maven Skin never changes a heading's ID to make room for its anchor, so the Markdown link then opens that element instead:

• Headings that differ only in case or separators (Überblick and überblick on one page): a Markdown link to the first opens the second, whose Doxia anchor is #a.C3.BCberblick.
• A heading that starts with a digit and one that is A followed by the same text (1. Install, ID 1-install, and A1 Install, ID a1-install): a Markdown link to #1-install is written as #a1-install and opens A1 Install, wherever on the page it is.
• An id you wrote yourself that equals the rewritten ID, such as <div id="a1-install">.

Rename one of them, or link from site.xml, whose hrefs reach the page unchanged.

Changing <colorScheme> or <defaultTheme> Has No Visible Effect

You edited site.xml and rebuilt, but your browser still shows the old palette or light/dark mode.

Cause: One of the following:

• A saved preference wins. When a reader picks a theme or color scheme, Supa Maven Skin saves it in localStorage (supa-theme and supa-palette), and saved values take precedence over the site.xml defaults. localStorage is shared by every page on the same origin, so a choice made while previewing another project on http://localhost:8080, or on another project under the same github.io domain, also applies to your site.
• The value is misspelled. Color scheme IDs are exact and lowercase: furo, bootstrap, modus, modus-tinted, modus-deuteranopia, or modus-tritanopia. Any other value (including Modus) falls back to furo. Any <defaultTheme> value other than light or dark behaves like auto.

Fix: Correct the value, then remove the supa-theme and supa-palette entries under Local Storage in your browser's developer tools (or run localStorage.removeItem('supa-palette') and localStorage.removeItem('supa-theme') in the console) and reload. See Configuration Options.

The Theme or Color Scheme Resets on Every Page

Readers pick a theme or color scheme, but the next page goes back to the site default.

Cause: The browser is not allowing the site to store data. Browsers block access to localStorage when the user has set them to stop the site from saving data (cookies and site data). Supa Maven Skin catches the error and falls back to the site.xml defaults.

Fix: There is nothing to fix on the site side. Readers who want their choice to stick need to allow site data for your documentation domain.

The Site Uses High-Contrast Colors Instead of Furo

Your site uses the default furo color scheme, but a reader sees the black-and-white Modus palette.

Cause: This is intentional. When the operating system or browser asks for more contrast (the prefers-contrast: more media query, such as macOS Increase contrast), the default furo scheme switches to the WCAG AAA modus tokens. This only happens while the reader has not picked a color scheme themselves.

Fix: Readers can choose any color scheme from the palette menu in the header, and that choice is kept. See Built-In Accessible Color Schemes.

A Custom Brand Color Looks Wrong in Dark Mode

Cause: Values in <lightCssVariables> are written as plain CSS custom properties that apply in every mode. Only <darkCssVariables> overrides them in dark mode. If you set a color only in <lightCssVariables>, the light-mode color is also used on the dark background. The build-time WCAG contrast check only covers the built-in color schemes, not your overrides.

Fix: Set every overridden color in both <lightCssVariables> and <darkCssVariables>, and check its contrast against both backgrounds yourself. See Extending Palettes.

Settings in <furoSkin> Are Ignored

Cause: Supa Maven Skin reads <custom><supaSkin> and only falls back to the legacy <custom><furoSkin> element when there is no <supaSkin> element. The two are not merged: if both are present, everything inside <furoSkin> is ignored.

Fix: Move all options into <supaSkin> and delete the <furoSkin> element.

English Text on a Translated Site

You translated the skin's labels in site.xml, but some of its text is still English.

Cause: One of the following:

• The key is misspelled or does not exist. A <labels> child the skin does not know changes nothing. The browser console names it: Supa Maven Skin: unknown <labels> keys in site.xml were ignored: serchPlaceholder.
• The label contains markup. An element inside a label, such as <pageNext>Nach <b>vorne</b></pageNext>, empties it. The console names it: Supa Maven Skin: <labels> in site.xml that contain markup were ignored (write < as &lt;): pageNext.
• The TOC drawer buttons are labelled separately. <tocTitle> names the table of contents; its drawer buttons use the tocToggle label.
• The label is empty. An empty element, such as <backToTop></backToTop>, keeps the English text, so that no control loses its accessible name.
• The page belongs to another locale. With <locales>default,fr</locales>, Maven renders the /fr/ pages from site_fr.xml instead of site.xml. The two are not merged, so the labels in site.xml do not reach the French pages.
• Bootstrap's own widget wrote the text. A chip's “Remove” button, a Combobox's “{n} selected”, and the Datepicker's buttons are Bootstrap's text, not the skin's labels.
• Maven wrote the page. The menus and pages of Maven's reports, such as Project Information, come from Maven, which writes them in the locale it renders.

Fix: Check the console for unknown keys and labels with markup, and compare the names with the Labels reference; keys are case-sensitive. Write labels as plain text. Give each locale's site_<lang>.xml its own <labels>. For widget text, use the widget's own option where it has one, such as a strength meter's data-bs-messages or a nav overflow's data-bs-more-text. See Translating the Skin's Labels.

A Mermaid Diagram Shows Its Source Text

Cause: One of the following:

• <mermaid>false</mermaid> is set, so the fenced block stays a plain <pre> block without the usual code-block header, copy button, or highlighting.
• The Mermaid library could not be loaded. By default Supa Maven Skin loads a version-pinned mermaid.min.js from cdn.jsdelivr.net with Subresource Integrity (SRI); <mermaidCdnUrl> only overrides that URL. With no network access, a blocked CDN, a Content-Security-Policy whose script-src does not allow that host (or your override's host), or an integrity mismatch (for example from a proxy that rewrites the file), loading fails quietly and the diagram source is left on the page as plain text. An integrity mismatch shows up in the browser console as an integrity error, not a 404.
• The block is not marked as Mermaid. Only fenced blocks with the mermaid language, or elements with the mermaid class, are rendered.

Fix: Use a ```mermaid fence, keep <mermaid> at auto or true, and make sure readers' browsers can reach cdn.jsdelivr.net (or your override). For offline or locked-down sites, follow Self-Hosting Mermaid & KaTeX: copy the single mermaid.min.js file into your site and point <mermaidCdnUrl> at its root-relative or absolute URL. An .mjs override still loads with import(), but the ES module build imports chunk files by relative path, so its chunks/ folder must be copied next to it. If diagrams render but look unstyled, your style-src lacks 'unsafe-inline'; see Content Security Policy.

Dollar Amounts Render as Italic Math

A sentence like the one below shows “5perseatand” run together in italic math type, because math mode ignores spaces:

The plan costs $5 per seat and $10 per admin.

Cause: With <katex>auto</katex> (the default), any text that looks like $...$ makes Supa Maven Skin load KaTeX, which then renders the text between each pair of dollar signs as inline math. Escaping the dollar sign does not help: Markdown turns \$ and $ into a plain $ before KaTeX sees the text.

Fix: Put one of the amounts in inline code (KaTeX skips <code> and <pre>), wrap a dollar sign in its own element, or turn math off with <katex>false</katex> if the site has no formulas:

The plan costs `$5` per seat and `$10` per admin.
The plan costs <span>$</span>5 per seat and <span>$</span>10 per admin.

KaTeX Math Does Not Render

Cause: One of the following:

• Markdown removed a backslash. In CommonMark, \( and \[ are escapes for ( and [, so \(a+b\) reaches the browser as (a+b).
• Markdown added emphasis. Asterisks inside math, as in $a*b*c$, are turned into <em> tags before KaTeX runs.
• The page was not detected as containing math. In auto mode, inline math needs a non-space character straight after the opening $. A page whose only formula is $ x $ never loads KaTeX.
• KaTeX could not be loaded. <katex>false</katex> is set, the CDN is unreachable, a Content-Security-Policy blocks the jsDelivr defaults (or your <katexJsCdnUrl> / <katexCssCdnUrl> overrides) in script-src, style-src, or font-src, or a file fails its integrity check. When you self-host a classic contrib/auto-render.min.js, the skin first loads katex.min.js from the folder above it (../katex.min.js), so copying only contrib/ leaves a 404 in the console.

Fix: Double the backslashes (\\(a+b\\), \\[ ... \\]), escape asterisks inside math (\*), write inline math without a space after the opening $ ($x$), or set <katex>true</katex> to always load KaTeX. Prefer $$ ... $$ for display math. To serve KaTeX yourself, keep its dist/ layout as described in Self-Hosting Mermaid & KaTeX, and allow the origins listed under Content Security Policy.

The Sidebar or “On this page” Column Is Missing

Cause: One of the following:

• The window is narrow. Below 1024px the left navigation moves into a drawer opened from the menu button in the top bar. Below 1280px the “On this page” column moves into a drawer opened from the table-of-contents button. <stickyContentHeader> only pins the content header at 1024px and wider, because the mobile header is already sticky below that width.
• The page has no section headings. The table of contents lists h2 headings and deeper, down to <tocMaxDepth> (default 4). A page with only a title has no table of contents, and its table-of-contents buttons are hidden.
• The column is turned off. <tocSidebar>false</tocSidebar> removes it on every page.

Fix: Widen the window or use the drawer buttons, add ## sections to long pages, and check <tocSidebar> and <tocMaxDepth>.

Search Does Not Find Text on Other Pages

Cause: Search indexes the current page's headings plus up to 30 pages linked from the left navigation. For those other pages it only indexes the title, the first few hundred characters of text, and h1–h4 headings, not the full text. Pages that are not linked from the navigation menu in site.xml are not indexed at all.

Fix: Add every page you want to be searchable to a <menu> in site.xml (sub-items count), and put the terms readers will search for in headings or near the top of the page.

Rules in css/site.css Are Not Applied

Cause: Supa Maven Skin links exactly one custom stylesheet, css/site.css, after its own stylesheet so that your rules can override its styles. Maven copies src/site/resources/ into the root of the generated site, so the source file must be src/site/resources/css/site.css. If you do not provide the file, maven-site-plugin writes a placeholder css/site.css that contains only a comment.

Fix: Save the stylesheet as src/site/resources/css/site.css and rebuild. For colors, prefer <lightCssVariables> and <darkCssVariables> in site.xml (see Extending Palettes) over restyling individual components.