Snippet macro: add a parameter to set the CSS class on the generated <pre>/<code> element #1067

Summary

The snippet macro currently provides no way to set a CSS class (or other attributes) on the <pre>/<code> elements it generates. Supporting an optional class parameter would allow client-side syntax highlighters such as Prism or highlight.js to pick up the language (e.g. language-yaml) without any post-processing.

Current behavior

SnippetMacro.execute() reads the parameters id, url, file, encoding, debug, ignoreDownloadError, verbatim and source, then emits:

sink.verbatim(source ? SinkEventAttributeSet.SOURCE : null);
sink.text(snippet.toString());
sink.verbatim_();

so the only attribute that ever reaches the sink is DECORATION=source, which Xhtml5BaseSink.verbatim() consumes to produce <pre><code> (and strips before writing the tags). There is no way to attach a class to the output.

Why it's a small change

The sink layer already supports this: SinkUtils.SINK_VERBATIM_ATTRIBUTES includes CLASS (as well as ID, LANG, STYLE, TITLE), and Xhtml5BaseSink.verbatim() copies these filtered attributes onto the <pre> start tag. Only the macro fails to forward anything.

Proposed enhancement

Add an optional class parameter to the snippet macro:

%{snippet|id=my-snippet|file=src/main/connector/MyConnector.yaml|class=language-yaml}

which would result in:

SinkEventAttributeSet atts = new SinkEventAttributeSet();
if (source) {
    atts.addAttributes(SinkEventAttributeSet.SOURCE);
}
if (cssClass != null) {
    atts.addAttribute(SinkEventAttributes.CLASS, cssClass);
}
sink.verbatim(atts.getAttributeCount() > 0 ? atts : null);

producing <pre class="language-yaml"><code>…</code></pre>.

A class on <pre> is sufficient for Prism (which resolves language-* classes from ancestors) and can be configured for highlight.js. Alternatively (or additionally), the macro could place the class on the <code> element, which is what the HTML spec suggests for indicating the language — but that would require Xhtml5BaseSink to forward attributes to the inner <code> tag as well.

Use case

We generate connector reference documentation with maven-site-plugin 4.0.0-M16 and include YAML fragments from the sources via the snippet macro. All other code blocks on the site (fenced Markdown blocks) get syntax highlighting, but snippet-included blocks render unhighlighted because there is no way to tag them with language-yaml.