PlantUML Diagram Export Feature

[izhyvaiev]

PlantUML Diagram Export Feature

Summary

Successfully extended the Confluence Markdown Exporter to support exporting PlantUML diagrams from Confluence pages to Markdown code blocks.

Changes Made

1. Added Dependencies

• File: pyproject.toml
• Added lxml package to project dependencies for XML parsing support
• This allows proper parsing of the Confluence editor2 XML format

2. Core Implementation

• File: confluence_markdown_exporter/confluence.py
• Added json import for parsing PlantUML data structures
• Implemented convert_plantuml() method in the Page.Converter class
• Registered plantuml handler in the macro handlers dictionary

3. Test Coverage

• File: tests/unit/test_plantuml_conversion.py (new file)
• Created comprehensive test suite with 5 test cases:
  • Basic PlantUML conversion
  • Missing macro-id handling
  • Complex diagram conversion
  • Macro not found in editor2 handling
  • Invalid JSON handling

How It Works

1. Detection: When the exporter encounters a PlantUML macro in the Confluence HTML (identified by data-macro-name="plantuml"), it triggers the convert_plantuml() method

2. XML Parsing: The method parses the editor2 XML format to find the corresponding PlantUML macro using the macro-id attribute

3. Data Extraction: Extracts the PlantUML definition from the JSON structure stored in the CDATA section of the <ac:plain-text-body> element

4. Markdown Conversion: Converts the UML definition to a Markdown code block with plantuml syntax highlighting

Example

Input (Confluence XML):

<ac:structured-macro ac:name="plantuml" ac:macro-id="123">
    <ac:plain-text-body><![CDATA[{"umlDefinition":"@startuml\nAlice -> Bob: Hello\n@enduml"}]]></ac:plain-text-body>
</ac:structured-macro>

Output (Markdown):

@startuml
Alice -> Bob: Hello
@enduml

Error Handling

The implementation includes robust error handling for:

• Missing macro-id attributes
• Macro not found in editor2 XML
• Empty or missing content
• Invalid JSON parsing
• Missing UML definition in JSON

All error cases result in HTML comments in the output, allowing the export to continue without failing.

Testing

All tests pass successfully:

• 5 PlantUML-specific tests
• 78 total unit tests (including existing tests)

[Spenhouet]

@izhyvaiev Thanks for the contribution. Looks like a great addition.

I just added support for Mermaid diagrams via draw.io: #112
Sorry that I introduced conflicts with your PR. Could you address these?

[Spenhouet]

What PlantUML add-on is this expecting?

[izhyvaiev]

@Spenhouet conflicts resolved. It's expecting - https://marketplace.atlassian.com/apps/1222993/flowchart-plantuml-diagrams-for-confluence

[Spenhouet]

@izhyvaiev Thank you for your contribution. This will be released with the next version.