Rolfe Dlugy-Hegwer

Rolfe Dlugy-Hegwer, technical writer. September to October 2026.

Why it matters

AI agents and LLMs (the large language models behind them) read documentation more reliably as plain Markdown than as web pages full of HTML. Markdown is a simple text format that is easy for both people and programs to read.

A “Markdown twin” is a Markdown copy of each documentation page, published next to the normal HTML page so that AI tools can read it.

A web page, as a program sees it:

<div class="sect2">
<h2 id="_install">Install the tools</h2>
<div class="paragraph">
<p>Run the command below.</p>
</div></div>

Its Markdown twin:

## Install the tools
Run the command below.

A simplified example. Both say the same thing, but the twin is shorter and has no extra tags.

The parser, and who made it

Many technical documents, including the Quarkus guides, are written in AsciiDoc, a markup language for documentation. A parser is the program that reads AsciiDoc so it can be turned into a finished page.

Yupiik’s asciidoc-java is an AsciiDoc parser written entirely in Java. Romain Manni-Bucau at Yupiik wrote it and maintains it. I did not write the parser. My work builds on his.

What I added

I contributed a renderer that lets the parser turn AsciiDoc into GitHub-Flavored Markdown (the version of Markdown used on GitHub), not only into HTML.

A pull request is a proposed change that a project’s maintainers review and then merge, or accept, into their code.

• Pull request #133, “Add GithubFlavoredMarkdownRenderer”: about 4,300 lines added, merged on 25 September 2026 after 42 review comments.
• The renderer started in my Quarkus Roq plugin that publishes Markdown twins: quarkus-roq pull request #1105. It is still open, waiting for a Yupiik release.

Testing on real documents

I rendered all 282 guides on quarkus.io with the parser and compared the results with Asciidoctor, the reference AsciiDoc tool. Each difference became a fix or an issue (a reported problem). Some of the fixes, grouped by what a reader would notice:

• Text that appears only for some readers, such as instructions for Maven or Gradle (two tools programmers use to build software): #126, #174, #188
• Tables: #143, #151, #159
• Links to sections of other pages: #146, #165
• Robustness, meaning no crashes or endless loops on unusual input: #116, #123, #166

The remaining gaps are listed in issue #142.

So far

• 47 pull requests merged
• 4 more open
• 20 issues reported

The first one was merged on 8 September 2026. See the full list of merged pull requests.

Thank you

Thank you to Romain Manni-Bucau and François Papon at Yupiik for their reviews and for merging this work.

Rolfe Dlugy-Hegwer on GitHub: github.com/rolfedh

Numbers as of 4 October 2026.