Snippet macro: add a parameter to set the CSS class on the generated <pre>/<code> element
- Dominant language
- Java
- Stars
- 34
- Forks
- 54
- Avg merge
- 1d 12h
- Merged PRs (30d)
- 16
Description
## Summary
The `snippet` macro currently provides no way to set a CSS class (or other attributes) on the `
`/`` 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:
```java
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 `
` (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 `
` 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:
```java
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 `
…
`.
A class on `
` 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 `` element, which is what the [HTML spec suggests](https://html.spec.whatwg.org/multipage/text-level-semantics.html#the-code-element) for indicating the language — but that would require `Xhtml5BaseSink` to forward attributes to the inner `` 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`.
Contributor guide
No contributing guide indexed for this repository
Research direction
Start by locating SnippetMacro.execute() and the existing tests for the snippet macro, then read Xhtml5BaseSink.verbatim() and SinkUtils.SINK_VERBATIM_ATTRIBUTES to confirm how attributes flow to the generated markup. Add optional class forwarding while preserving the source attribute behavior, and verify that a class such as language-yaml appears on the generated pre element without changing existing output when it is omitted.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- java
- Domain
- documentation
- Issue type
- Feature
- Difficulty
- 2/5
- Estimated time
- Half a day
- Activity status
- Quiet
- Clarity
- Mostly clear
- Newbie friendliness
- 68/100