Repository navigation
Document how Markdown code blocks reach the Sink - #1076
Merged
Merged
Conversation
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.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Part of #876 (DOXIA-762), which asks for the Markdown side of code highlighting to be written down somewhere. The module page currently says nothing about code blocks at all.
Two things here.
The module page gains a "Code blocks" section. Verified against the current parser rather than inferred:
```javalanguage-java<pre><code class="language-java">```with no info stringnohighlight nocode<pre><code class="nohighlight nocode">nohighlight nocode<pre><code class="nohighlight nocode">The first row is asserted by
fencedCodeBlockSinkEventin the module's own tests. I confirmed the indented case by dumping the events forcode.md, since only the fenced case was covered. The two odd class names come fromFENCED_CODE_NO_LANGUAGE_CLASSand are the opt-out markers for highlight.js and code-prettify, which is worth stating since they look arbitrary otherwise.The
MarkdownHtmlParserjavadoc is corrected. It currently says:That is no longer what happens, and the module's own test comment says as much: "instead of using a decoration tag on the verbatim event an additional inline event is used". The
verbatimevent carries no attributes; the nestedinlineevent carries the semantics and the language. Leaving the old description in place is worse than having none, since it points at a mechanism that is not there.The replacement also records why Markdown differs from APT and XDoc, where
+--and<source>put thesourcedecoration on theverbatimevent: Markdown has a language to convey as well, and the inline event already carries it, so the decoration would add nothing.On its own this does not cover all of #876. The APT half is apache/maven-doxia-site#70, and whether the four parsers should converge on one representation is a separate question I have deliberately not touched here.