apache / apache/maven-doxia

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

Open Beginner friendly
#1,067 0 comments 0 reactions 0 assignees View on GitHub
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

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.