Authoring Rich Content

Choosing Markdown (.md) vs. Velocity Templates (.md.vm)

Doxia 2.0 supports two ways to author Markdown pages in src/site/markdown/:

#bsBadge( "primary" "" "v${project.version}" )
#bsBadge( "success" "subtle" "Stable API" )
#bsBadge( "info" "outline" "JDK 21+" )

#bsCard(
  "${project.name}"
  "${project.groupId}:${project.artifactId}"
  "Zero-config Sphinx Furo aesthetics powered by Bootstrap 6."
  "MIT License"
)

#bsCardGridStart( "" )
#bsGuideCard( "col-12 md:col-6" "rocket-takeoff" "primary" "getting-started.html" "Quickstart Tutorial" "Tutorial" "Step-by-step guide to configuring <code>pom.xml</code> and <code>site.xml</code>." )
#bsCardGridEnd()

Admonitions

Supa Maven Skin supports all 12 Sphinx Furo admonition types across 6 semantic categories, each rendered with a Bootstrap Icons glyph (<i class="bi bi-... supa-admonition-icon" aria-hidden="true"></i>), tinted header bar, and colored left accent border. Any text after the [!...] marker on the first line becomes a custom title, and nested blockquotes (> > [!WARNING]) are automatically transformed into nested admonitions. Inline Markdown such as code spans and emphasis works in custom titles too.

Select a category below to preview the rendered admonitions and copy their Markdown syntax:

> [!NOTE]
> Renders with `bi-info-circle` and the **Info** palette tokens.

> [!SEEALSO]
> Cross-reference related sections or external docs (`[!SEE-ALSO]` also works).

> [!TIP] Custom Admonition Title
> Provide text immediately after `[!TIP]` on the first line to override the default heading.

> [!HINT]
> Gentle guidance or troubleshooting hints (`bi-question-circle`).

> [!IMPORTANT]
> Highlights essential requirements or prerequisites (`bi-fire`).

> [!ADMONITION] Custom Admonition Heading
> Equivalent to Sphinx's generic `.. admonition:: Title` directive (`bi-card-text`).

> [!WARNING]
> Warns readers about potential configuration pitfalls (`bi-exclamation-triangle`).

> [!CAUTION]
> Advises caution before changing sensitive parameters (`bi-lightning-charge`).

> [!ATTENTION]
> Demands immediate attention before proceeding (`bi-exclamation-diamond`).

> [!DANGER]
> Alerts readers to destructive actions or data-loss risks (`bi-lightning-charge-fill`).

> [!ERROR]
> Documents known error states or failure modes (`bi-x-octagon`).

> [!TODO]
> Renders with `bi-check2-square` for tracking upcoming tasks.

Bootstrap 6 Semantic Alerts

When you need a Bootstrap 6 .alert banner (supporting all 8 .theme-* colors and optional dismiss buttons), you can use the GFM blockquote shorthand, raw HTML, or the #bsAlert Velocity macro:

> [!ALERT:primary dismissible] Release Ready
> Use `[!ALERT:theme dismissible]` in Markdown or `#bsAlert` in Velocity.

#bsAlert( "primary" "Release Ready" "Use #bsAlert in Velocity templates." true )

<div class="alert theme-primary not-prose" role="alert">
  <div class="flex-grow-1">
    <div class="alert-heading fw-semibold mb-1">Release Ready</div>
    <div>Standard Bootstrap 6 alert markup.</div>
  </div>
  <button type="button" class="btn-close ms-auto" data-bs-dismiss="alert" aria-label="Close"></button>
</div>

1. Markdown Shortcode

Write :bi-<icon-name>: anywhere in prose, table cells, headings, or lists. You can optionally append space-separated utility classes (such as text-primary, text-success, fs-5, me-1) before the closing colon:

- :bi-rocket-takeoff: Basic decorative icon
- :bi-check-circle-fill text-success fs-5: Icon with color and font-size utilities
- :bi-github me-1: Icon with right margin inside a link

[!NOTE] Code Block Safety Shortcodes inside inline `code` and <pre><code> blocks are automatically ignored and left untouched as literal text.

2. Velocity Macro

In .md.vm pages, use #bi( $name $extraClasses $ariaLabel ):

## Decorative icon (renders aria-hidden="true")
#bi( "rocket-takeoff" "" "" ) Launch

## Icon + extra CSS utility classes (renders aria-hidden="true")
#bi( "check-circle-fill" "text-success fs-5" "" ) Verified

## Semantic accessible icon (renders role="img" aria-label="Accessible")
#bi( "universal-access-circle" "text-info fs-5" "Accessible" ) WCAG 2.2 AAA

3. Raw HTML

<i class="bi bi-rocket-takeoff text-primary fs-5" aria-hidden="true"></i> Launch

File Header Bars & Line Numbers

To add a file-path header bar (.supa-code-header) or line numbers (.has-line-numbers) to a code block, use an HTML <pre> block with data-title="..." (or title="...") on <code> and class="line-numbers" on <pre>:

package io.example;

public final class Greeter {
  public static String greet(String name) {
    return "Hello, " + name + "!";
  }
}

<pre class="line-numbers"><code class="language-java" data-title="src/main/java/io/example/Greeter.java">package io.example;

public final class Greeter {
  public static String greet(String name) {
    return "Hello, " + name + "!";
  }
}</code></pre>

Unified Diffs

Use a standard ```diff fenced code block to highlight additions (+) and removals (-) with palette-aware semantic colors:

```diff
 <skin>
-  <groupId>org.apache.maven.skins</groupId>
-  <artifactId>maven-fluido-skin</artifactId>
+  <groupId>io.github.mepcotterell</groupId>
+  <artifactId>supa-maven-skin</artifactId>
 </skin>
```

Declarative Accordions (.supa-accordion)

Wrap <div title="Section Heading"> items inside <div class="supa-accordion">. Add class="open" to any item that should be expanded initially:

<div class="supa-accordion">
  <div title="How do I set a default color scheme?" class="open">
    <p>Set <code>&lt;colorScheme&gt;modus&lt;/colorScheme&gt;</code> inside <code>&lt;custom&gt;&lt;supaSkin&gt;</code> in your <code>src/site/site.xml</code>.</p>
  </div>
  <div title="Does Supa Maven Skin work offline?">
    <p>Yes. Bootstrap 6 CSS/JS, Bootstrap Icons fonts, and Highlight.js are all bundled directly inside the skin JAR.</p>
  </div>
</div>

Declarative Steppers (ol.supa-stepper)

Use <ol class="supa-stepper" title="2"> where title specifies the 1-based active step index (all steps up to that number are styled as active/completed):

<ol class="supa-stepper" title="2">
  <li>Configure pom.xml</li>
  <li>Author Markdown</li>
  <li>Deploy Site</li>
</ol>

Mermaid Diagrams

Use a standard fenced ```mermaid code block. The diagram automatically re-renders when the user toggles between Light and Dark themes:

```mermaid
flowchart LR
    A["src/site/markdown/*.md"] --> B["Doxia 2.0"]
    B --> C["Supa Maven Skin (site.vm)"]
    C --> D["Responsive HTML5 Site"]
```

KaTeX Mathematical Notation

Write inline math between single $...$ delimiters (such as $O(n \log n)$) and display equations between $$...$$ delimiters:

Inline complexity $O(n \log n)$ or display block:

$$
\hat{y} = \sigma\left( \sum_{i=1}^{d} w_i x_i + b \right)
$$

Self-Hosting Mermaid & KaTeX

Serve both libraries from your own site when you cannot depend on jsDelivr, for example on an intranet or under a strict Content Security Policy.

1. Copy the classic builds into src/site/resources/vendor/, keeping KaTeX's dist/ layout so the stylesheet finds fonts/ and the loader finds ../katex.min.js:

   mkdir -p src/site/resources/vendor/mermaid src/site/resources/vendor/katex
   curl -fsSL -o src/site/resources/vendor/mermaid/mermaid.min.js \
     https://cdn.jsdelivr.net/npm/mermaid@11.17.2/dist/mermaid.min.js
   npm pack katex@0.16.47 --pack-destination /tmp && tar -xzf /tmp/katex-0.16.47.tgz -C /tmp
   cp -R /tmp/package/dist/katex.min.js /tmp/package/dist/katex.min.css \
     /tmp/package/dist/fonts /tmp/package/dist/contrib src/site/resources/vendor/katex/
   

2. Point the overrides at root-relative paths (or absolute https:// URLs):

   <supaSkin>
     <mermaidCdnUrl>/my-project/vendor/mermaid/mermaid.min.js</mermaidCdnUrl>
     <katexCssCdnUrl>/my-project/vendor/katex/katex.min.css</katexCssCdnUrl>
     <katexJsCdnUrl>/my-project/vendor/katex/contrib/auto-render.min.js</katexJsCdnUrl>
   </supaSkin>
   

   Replace /my-project/ with the path your site is deployed under (/ for a site at the domain root).

[!WARNING] Avoid document-relative values such as vendor/mermaid/mermaid.min.js. Classic <script src> and <link href> URLs resolve against the current page, so they break on pages in subdirectories (for example, pages from src/site/markdown/guides/*.md). .mjs URLs loaded with import() resolve against js/supa-maven-skin.min.js instead and must start with ./, ../, or /. Root-relative and absolute URLs resolve the same way in all three cases.

Self-hosted URLs load without Subresource Integrity, because the skin only knows the hashes of its pinned defaults. The Configuration Reference lists every loading option, and Content Security Policy lists the origins to allow when you keep the jsDelivr defaults.