Skip to content

Convert the plugin site pages from xdoc to Markdown - #581

Merged
slachiewicz merged 2 commits into
masterfrom
agent/convert-xdoc-to-markdown
Aug 9, 2026
Merged

Convert the plugin site pages from xdoc to Markdown#581
slachiewicz merged 2 commits into
masterfrom
agent/convert-xdoc-to-markdown

Conversation

@slachiewicz

@slachiewicz slachiewicz commented Aug 9, 2026

Copy link
Copy Markdown
Member

Converts the eight modello-plugin-* index pages from xdoc to Markdown with doxia-converter, leaving download.xml.vm alone.

Please merge or rebase rather than squash — the rename is in its own commit so git log --follow keeps 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 &#160; standing in for the line break and the indent before throws:

<li><code>public <i>RootClass</i> read( Reader reader, boolean strict )<br/>
  &#160;&#160;&#160;&#160;throws IOException, XmlPullParserException</code></li>

They are now fenced ```java blocks, with consecutive overloads of the same method in one block:

```java
public RootClass read( Reader reader, boolean strict )
    throws IOException, XmlPullParserException

public RootClass read( Reader reader )
    throws IOException, XmlPullParserException
```

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:check passes.

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)
@slachiewicz slachiewicz added documentation Improvements or additions to documentation maintenance Cleanup, refactoring or other internal change labels Aug 9, 2026
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 &#160; 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
slachiewicz force-pushed the agent/convert-xdoc-to-markdown branch from d6e7cb0 to 35a8160 Compare August 9, 2026 15:26
@slachiewicz
slachiewicz marked this pull request as ready for review August 9, 2026 15:27
@slachiewicz
slachiewicz merged commit 1252936 into master Aug 9, 2026
12 checks passed
@slachiewicz
slachiewicz deleted the agent/convert-xdoc-to-markdown branch August 9, 2026 17:18
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

documentation Improvements or additions to documentation maintenance Cleanup, refactoring or other internal change

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant