{"record":{"id":"5d53aed28e95b355","repo":"quarkusio/quarkus","slug":"conversion-from-markdown-to-asciidoc-is-not-suppor","errorCode":null,"errorMessage":"Conversion from Markdown to Asciidoc is not supported","messagePattern":"Conversion from Markdown to Asciidoc is not supported","errorType":"exception","errorClass":"IllegalArgumentException","httpStatus":null,"severity":"error","filePath":"core/processor/src/main/java/io/quarkus/annotation/processor/documentation/config/formatter/JavadocToAsciidocTransformer.java","lineNumber":94,"sourceCode":"\n    private static final Pattern INLINE_TAG_MARKER_PATTERN = Pattern.compile(\"§§([0-9]+)§§\");\n\n    private JavadocToAsciidocTransformer() {\n    }\n\n    public static String toAsciidoc(String javadoc, JavadocFormat format) {\n        return toAsciidoc(javadoc, format, false);\n    }\n\n    public static String toAsciidoc(String javadoc, JavadocFormat format, boolean inlineMacroMode) {\n        if (javadoc == null || javadoc.isBlank()) {\n            return null;\n        }\n\n        if (format == JavadocFormat.ASCIIDOC) {\n            return javadoc;\n        } else if (format == JavadocFormat.MARKDOWN) {\n            throw new IllegalArgumentException(\"Conversion from Markdown to Asciidoc is not supported\");\n        }\n\n        // the parser expects all the lines to start with \"* \"\n        // we add it as it has been previously removed\n        Javadoc parsedJavadoc = StaticJavaParser.parseJavadoc(START_OF_LINE.matcher(javadoc).replaceAll(\"* \"), false);\n\n        StringBuilder htmlJavadoc = new StringBuilder(javadoc.length());\n\n        int markerCounter = 0;\n        StringBuilder sb = new StringBuilder();\n        Map<Integer, String> inlineTagsReplacements = new TreeMap<>();\n\n        for (JavadocDescriptionElement javadocDescriptionElement : parsedJavadoc.getDescription().getElements()) {\n            if (javadocDescriptionElement instanceof JavadocInlineTag inlineTag) {\n                String content = inlineTag.getContent().trim();\n                switch (inlineTag.getType()) {\n                    case CODE:\n                    case VALUE:","sourceCodeStart":76,"sourceCodeEnd":112,"githubUrl":"https://github.com/quarkusio/quarkus/blob/e1c734241f34c7919086ceb4c9262b4a58f6de44/core/processor/src/main/java/io/quarkus/annotation/processor/documentation/config/formatter/JavadocToAsciidocTransformer.java#L76-L112","documentation":"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.","triggerScenarios":"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.","commonSituations":"Extension authors writing config property Javadoc in Markdown style (**bold**, `code`, # headings) while Quarkus documentation generation targets Asciidoc; mixed-format Javadoc across extension modules.","solutions":["Rewrite the Javadoc of the offending config item using Asciidoc conventions (use *bold*, `code` as-is, == headings)","Detect the Javadoc format and convert Markdown to Asciidoc yourself before invoking the transformer","Route the conversion through JavadocTransformer.toMarkdown instead if Markdown output is acceptable","Fix source comments so the format detector classifies them as ASCIIDOC"],"exampleFix":"// before\n/**\n * The port. **Must be > 0**\n */\n// after\n/**\n * The port. *Must be > 0*\n */","handlingStrategy":"validation","validationCode":"JavadocFormat fmt = JavadocFormatDetector.detect(javadoc);\nif (fmt == JavadocFormat.MARKDOWN && targetFormat == JavadocFormat.ASCIIDOC) {\n    throw new IllegalArgumentException(\"Rewrite Javadoc in Asciidoc: \" + elementName);\n}","typeGuard":null,"tryCatchPattern":"try {\n    return JavadocTransformer.transform(javadoc, from, JavadocFormat.ASCIIDOC);\n} catch (IllegalArgumentException e) {\n    if (e.getMessage().contains(\"Markdown to Asciidoc\")) {\n        log.warn(\"Config item Javadoc uses Markdown; skipping conversion\");\n        return javadoc;\n    }\n    throw e;\n}","preventionTips":["Write config Javadoc in Asciidoc conventions for Quarkus extensions","Add a CI check that runs the doc processor on all extension modules","Avoid pasting Markdown-formatted text from READMEs into Javadoc"],"tags":["annotation-processor","javadoc","asciidoc","documentation"],"backgroundTag":"unsupported-format-conversion","analyzedSha":"e1c734241f34c7919086ceb4c9262b4a58f6de44","analyzedAt":"2026-09-05T17:01:29.979Z","contentChangedAt":"2026-09-05T17:01:29.979Z","schemaVersion":2},"datasetVersion":"2026-09-12T22:17:10.623Z"}