[DOXIA-762] Clarify code highlighting for verbatim text in Markdown and APT #876

Activity

1. jira-importer

   added

   enhancementNew feature or requestNew feature or request

   priority:majorMajor loss of functionMajor loss of function

   on Jul 15, 2025
2. kwin

   self-assigned this

   on Feb 10, 2026
3. kwin commented on Feb 26, 2026

   

   kwin

   on Feb 26, 2026

   Last edited by kwin

   Member

   More actions

   The situation right now differs a lot between the different markup parsers:

   1. AptParser

   • +--: Sink.verbatim(SinkEventAttributeSet(DECORATION, "source"))
   • ---: Sink.verbatim(null)

   2. MarkdownParser:

   • ```: <pre><code class="nohighlight nocode"> -> Sink.verbatim(); Sink.inline(new SinkEventAttributeSet("semantics", "code", "class", "nohighlight nocode"))
   • ```java: <pre><code class="language-java"> -> Sink.verbatim(); Sink.inline(new SinkEventAttributeSet("semantics", "code", "class", "language-java"))

   3. XDocParser:

   • <source>: Sink.verbatim(new SinkEventAttributeSet(DECORATION, "source"))

   4. XHTML5Parser

   • <pre>: Sink.verbatim(null)
   • <pre><code>: Sink.verbatim(null); Sink.inline(SinkEventAttributeSet.Semantics.CODE)

   Particularly the class nohighlight seems to be very specific to https://highlightjs.readthedocs.io/en/latest/readme.html?highlight=nohighlight#ignoring-a-code-block while nocode is specific to https://github.com/googlearchive/code-prettify?tab=readme-ov-file#how-do-i-prevent-a-portion-of-markup-from-being-marked-as-code
4. slachiewicz commented on Aug 8, 2026

   

   slachiewicz

   on Aug 8, 2026

   Member

   More actions

   Picked this up. Two PRs cover the documentation the issue asks for; the behavioural question underneath it I have left alone deliberately.

   • apache/maven-doxia-siteBump plexus-utils from 3.3.0 to 3.4.1 #70 — the APT reference. It still describes +-- as drawing a box, which is the pre Doxia 2 BOXED wording. Replaced with what the two forms actually emit and which to reach for.
   • Document how Markdown code blocks reach the Sink #1076 — the Markdown module page, which said nothing about code blocks, plus a correction to the MarkdownHtmlParser javadoc.

   Current state, verified against master

   Confirming @kwin's table, which still holds, with the sink output added:

   Source	verbatim event	nested inline event	rendered
   APT +--	source decoration	—	<pre><code>
   APT ---	no attributes	—	<pre>
   XDoc <source>	source decoration	—	<pre><code>
   XHTML5 <pre>	tag attributes only	—	<pre>
   XHTML5 <pre><code>	tag attributes only	Semantics.CODE	<pre><code>
   Markdown ```java	no attributes	semantics=code, class=language-java	<pre><code class="language-java">
   Markdown ```	no attributes	semantics=code, class=nohighlight nocode	<pre><code class="nohighlight nocode">
   Markdown indented	no attributes	semantics=code, class=nohighlight nocode	<pre><code class="nohighlight nocode">

   Xhtml5BaseSink.verbatim(SinkEventAttributes) opens the CODE element only when the decoration is source, so both representations land on <pre><code> in XHTML5 output; they differ in what a Sink other than XHTML5 sees.

   One thing worth flagging, found while writing this up: the MarkdownHtmlParser javadoc claims PRE elements are marked as source so the sink wraps them in <div class="source"> for the skins. Neither half of that is true any more — there is no div wrapper in Xhtml5BaseSink and Markdown sets no decoration. That is fixed in #1076.

   What the docs cannot settle

   There are two representations of "this is code" in the Sink API, source on the verbatim event and Semantics.CODE on a nested inline event, and which one you get depends on the input format rather than on anything meaningful. A Sink that is not the XHTML5 one has to handle both to treat code blocks consistently, and a Sink implementor has nothing telling them that.

   Documenting it, as these PRs do, is worth doing either way. But if the intent is that the two should converge, the docs will need rewriting when they do, so it may be worth deciding that first. Happy to open a separate issue for the convergence question if that is useful.
5. slachiewicz

   removed

   priority:majorMajor loss of functionMajor loss of function

   on Sep 21, 2026
6. slachiewicz commented on Nov 4, 2026

   

   slachiewicz

   on Nov 4, 2026

   Member

   More actions

   The documentation this issue asks for is in place: #1076 covers Markdown code blocks, and the APT reference now explains +-- versus --- (https://maven.apache.org/doxia/references/apt-format.html). The remaining design question, the two Sink representations of code, moved to #1121. Closing this one.
7. slachiewicz

   closed this as completedon Nov 4, 2026