(maven-doxia) branch master updated: Document how Markdown code blocks reach the Sink

[sl...@apache.org]

This is an automated email from the ASF dual-hosted git repository.

slachiewicz pushed a commit to branch master
in repository https://gitbox.apache.org/repos/asf/maven-doxia.git


The following commit(s) were added to refs/heads/master by this push:
     new d39dc2be Document how Markdown code blocks reach the Sink
d39dc2be is described below

commit d39dc2be4b4a03eee89c1ac31cb2effc8c913605
Author: Sylwester Lachiewicz <sl...@apache.org>
AuthorDate: Sat Aug 8 18:57:47 2026 +0200

    Document how Markdown code blocks reach the Sink
    
    The module page said nothing about code blocks, and the parser javadoc
    described an approach the code no longer takes: it claimed PRE elements
    are marked as "source" so the sink wraps them in a div the skins
    recognise. They are not. A code block emits a plain verbatim event with
    an inline event inside it carrying the code semantics and, for a fenced
    block, the language as a class.
    
    That is a deliberate difference from the APT and XDoc modules, which put
    the source decoration on the verbatim event itself, so say what Markdown
    does instead, and why, in both places.
---
 .../apache/maven/doxia/module/markdown/MarkdownParser.java   |  8 ++++----
 .../doxia-module-markdown/src/site/markdown/index.md         | 12 ++++++++++++
 2 files changed, 16 insertions(+), 4 deletions(-)

diff --git a/doxia-modules/doxia-module-markdown/src/main/java/org/apache/maven/doxia/module/markdown/MarkdownParser.java b/doxia-modules/doxia-module-markdown/src/main/java/org/apache/maven/doxia/module/markdown/MarkdownParser.java
index 8a5e21d3..8d8faeec 100644
--- a/doxia-modules/doxia-module-markdown/src/main/java/org/apache/maven/doxia/module/markdown/MarkdownParser.java
+++ b/doxia-modules/doxia-module-markdown/src/main/java/org/apache/maven/doxia/module/markdown/MarkdownParser.java
@@ -331,10 +331,10 @@ public class MarkdownParser extends AbstractTextParser implements TextMarkup {
      * <ul>
      * <li> DIV elements are translated as Unknown Sink events
      * </ul>
-     * PRE elements need to be "source" because the Xhtml5Sink will surround the
-     * corresponding verbatim() Sink event with a DIV element with class="source",
-     * which is how most Maven Skin (incl. Fluido) recognize a block of code, which
-     * needs to be highlighted accordingly.
+     * A code block does not carry the {@code source} decoration on its {@code verbatim} event, unlike the APT
+     * and XDoc modules. The language of a fenced code block has to be conveyed anyway, and the {@code inline}
+     * event emitted for the nested CODE element carries both that and the code semantics, so the decoration
+     * would add nothing. See {@code fencedCodeBlockSinkEvent} in the module tests for the exact events.
      */
     @Named
     public static class MarkdownHtmlParser extends Xhtml5Parser {
diff --git a/doxia-modules/doxia-module-markdown/src/site/markdown/index.md b/doxia-modules/doxia-module-markdown/src/site/markdown/index.md
index 81c276c5..e9464818 100644
--- a/doxia-modules/doxia-module-markdown/src/site/markdown/index.md
+++ b/doxia-modules/doxia-module-markdown/src/site/markdown/index.md
@@ -66,6 +66,18 @@ GitHub specified [extensions](https://github.github.com/gfm) to the original Mar
 
 The parser will first convert Markdown into HTML, convert to XHTML via [JSoup](https://jsoup.org/) and then parse the XHTML into Doxia Sink API methods calls leveraging the [XHTML5 parser](../doxia-module-xhtml5/index.html).
 
+## Code blocks
+
+Both indented and fenced code blocks become a `verbatim` Sink event containing an `inline` event with the `code` semantics, rendered as `<pre><code>`.
+
+The info string of a fenced code block, if there is one, is passed on as a class on that inline event, so
+
+<pre>```java</pre>
+
+produces `<pre><code class="language-java">`, which is the convention syntax highlighters look for. A fenced block without an info string, and an indented block, produce `<pre><code class="nohighlight nocode">` instead, which is how [highlight.js](https://highlightjs.readthedocs.io/en/latest/readme.html#ignoring-a-code-block) and [code-prettify](https://github.com/googlearchive/code-prettify#how-do-i-prevent-a-portion-of-markup-from-being-marked-as-code) are told to leave a block alone.
+
+Note that this differs from the APT and XDoc modules, where `+--` and `<source>` mark a code block by putting the `source` decoration on the `verbatim` event itself. Markdown carries the same information on the nested inline event instead, because it has a language to convey as well.
+
 ## References
 
 - [Markdown project website](http://daringfireball.net/projects/markdown)