Convert the plugin site pages from xdoc to Markdown - #581
Merged
Conversation
Git's rename detection is similarity-based, so a rename and a rewrite in one commit is recorded as a delete plus an add and git log --follow stops there. Please merge or rebase rather than squash. Generated-by: Claude Opus 5 (1M context)
Eight modello-plugin index pages, converted with doxia-converter. The YAML front matter is kept: it carries each page's title and author, which the skin turns into <title> and <meta name="author">. The method signatures were bulleted list items wrapping a <code> span, with <br/> and runs of   standing in for the line break and the indent before "throws". They are now fenced java blocks, so the break and the indent are real, consecutive overloads sit in one block, and the skin renders them as <code class="language-java"> for the highlighter to pick up. Class names inside sentences are ordinary code spans. That drops the <i> and <b> those spans used to mark which part of a name the reader substitutes. It is a deliberate trade: the emphasis cannot survive in a Markdown code span, and carrying it as inline HTML would leave every signature written as markup in an otherwise plain document. Verified by rendering the site before and after and comparing the two. The differences are only the intended ones: list items became code blocks, and the emphasis inside code is gone. Titles, authors, visible text and every link target are unchanged. Generated-by: Claude Opus 5 (1M context)
slachiewicz
force-pushed
the
agent/convert-xdoc-to-markdown
branch
from
August 9, 2026 15:26
d6e7cb0 to
35a8160
Compare
slachiewicz
marked this pull request as ready for review
August 9, 2026 15:27
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.
Converts the eight
modello-plugin-*index pages from xdoc to Markdown withdoxia-converter, leavingdownload.xml.vmalone.Please merge or rebase rather than squash — the rename is in its own commit so
git log --followkeeps working, and squashing collapses it back into a delete plus an add.Method signatures become fenced java blocks
In xdoc each signature was a bulleted list item wrapping a
<code>span, with<br/>and a run of standing in for the line break and the indent beforethrows:They are now fenced
```javablocks, with consecutive overloads of the same method in one block:The line break and the indent are real characters instead of markup, and the skin renders the block as
<pre class="prettyprint"><code class="language-java">, so the syntax highlighter picks it up — which the old<code>spans never got. Class names appearing inside a sentence stay inline code spans.What this gives up
The
<i>and<b>in those spans marked which part of a name the reader substitutes and which part is fixed —<i>my.model.package</i><b>.io.xpp3.</b><i>ModelName</i><b>Xpp3Reader</b>. A Markdown code span cannot carry that, so it is gone. Keeping it would have meant writing every signature as inline HTML in an otherwise plain document; the highlighting is worth more than the emphasis.Verification
The site was rendered before and after and the two compared page by page on title, author, visible text and link targets. The only differences are the two intended ones — list items became code blocks, and the emphasis inside code spans is gone. Titles, authors and every link target are unchanged.
The YAML front matter is kept and must stay the first bytes of each file: it carries the title and author, and without it the parser falls back to the first heading and
<meta name="author">disappears. Plexus parent 26 already excludes**/src/site/markdown/**from spotless's flexmark formatter, which would otherwise rewrite the fence closing the front matter;spotless:checkpasses.