quarkusio/quarkus · error · IllegalArgumentException

Conversion from Markdown to Asciidoc is not supported

Error message

Conversion from Markdown to Asciidoc is not supported

What it means

JavadocToAsciidocTransformer.toAsciidoc converts Javadoc into Asciidoc. If the source Javadoc is already Asciidoc it is returned unchanged, but Markdown-formatted Javadoc cannot be converted to Asciidoc by this transformer, so it throws IllegalArgumentException.

Source

Thrown at core/processor/src/main/java/io/quarkus/annotation/processor/documentation/config/formatter/JavadocToAsciidocTransformer.java:94

    private static final Pattern INLINE_TAG_MARKER_PATTERN = Pattern.compile("§§([0-9]+)§§");

    private JavadocToAsciidocTransformer() {
    }

    public static String toAsciidoc(String javadoc, JavadocFormat format) {
        return toAsciidoc(javadoc, format, false);
    }

    public static String toAsciidoc(String javadoc, JavadocFormat format, boolean inlineMacroMode) {
        if (javadoc == null || javadoc.isBlank()) {
            return null;
        }

        if (format == JavadocFormat.ASCIIDOC) {
            return javadoc;
        } else if (format == JavadocFormat.MARKDOWN) {
            throw new IllegalArgumentException("Conversion from Markdown to Asciidoc is not supported");
        }

        // the parser expects all the lines to start with "* "
        // we add it as it has been previously removed
        Javadoc parsedJavadoc = StaticJavaParser.parseJavadoc(START_OF_LINE.matcher(javadoc).replaceAll("* "), false);

        StringBuilder htmlJavadoc = new StringBuilder(javadoc.length());

        int markerCounter = 0;
        StringBuilder sb = new StringBuilder();
        Map<Integer, String> inlineTagsReplacements = new TreeMap<>();

        for (JavadocDescriptionElement javadocDescriptionElement : parsedJavadoc.getDescription().getElements()) {
            if (javadocDescriptionElement instanceof JavadocInlineTag inlineTag) {
                String content = inlineTag.getContent().trim();
                switch (inlineTag.getType()) {
                    case CODE:
                    case VALUE:

View on GitHub (pinned to e1c734241f)

Solutions

1. Rewrite the Javadoc of the offending config item using Asciidoc conventions (use *bold*, `code` as-is, == headings)
2. Detect the Javadoc format and convert Markdown to Asciidoc yourself before invoking the transformer
3. Route the conversion through JavadocTransformer.toMarkdown instead if Markdown output is acceptable
4. Fix source comments so the format detector classifies them as ASCIIDOC

Example fix

// before
/**
 * The port. **Must be > 0**
 */
// after
/**
 * The port. *Must be > 0*
 */

JavadocFormat fmt = JavadocFormatDetector.detect(javadoc);
if (fmt == JavadocFormat.MARKDOWN && targetFormat == JavadocFormat.ASCIIDOC) {
    throw new IllegalArgumentException("Rewrite Javadoc in Asciidoc: " + elementName);
}

try {
    return JavadocTransformer.transform(javadoc, from, JavadocFormat.ASCIIDOC);
} catch (IllegalArgumentException e) {
    if (e.getMessage().contains("Markdown to Asciidoc")) {
        log.warn("Config item Javadoc uses Markdown; skipping conversion");
        return javadoc;
    }
    throw e;
}

When it happens

Trigger: Calling JavadocTransformer.transform(javadoc, JavadocFormat.MARKDOWN, JavadocFormat.ASCIIDOC) or directly toAsciidoc with a javadoc string whose detected format is MARKDOWN — e.g. extension Javadoc written with Markdown headers/backticks while the doc pipeline requests Asciidoc output.

Common situations: Extension authors writing config property Javadoc in Markdown style (**bold**, `code`, # headings) while Quarkus documentation generation targets Asciidoc; mixed-format Javadoc across extension modules.

Related errors

• Converting to ${toFormat} is not supported
• Unable to find javadoc for config item ${enclosingElement} $
• Unable to read the resolved model from: ${resolvedModelPath}
• Could not parse HTML entity &${abbrev}; in ${text}
• Unable to parse: ${javadocPath}

AI-assisted analysis of quarkusio/quarkus@e1c734241f (2026-09-05). Data as JSON: /api/errors/5d53aed28e95b355. Report an issue: GitHub.