bertysentry opened a new issue, #1067:
URL: https://github.com/apache/maven-doxia/issues/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:
```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 `<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:
```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 `<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](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 `<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`.
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: [email protected]
For queries about this service, please contact Infrastructure at:
[email protected]
