drawio-export-tools

name	drawio-export-tools
description	Decision guide for the third-party Draw.io export ecosystem by @rlespinasse. Covers docker-drawio-desktop-headless (base Docker), drawio-exporter (Rust backend), drawio-export (enhanced Docker), and drawio-export-action (GitHub Actions). Use when user mentions diagram export, CI/CD automation, batch processing, or Draw.io files. Helps select the right tool based on context.

Draw.io Export Tools - Optimized Decision Guide

Third-party ecosystem by @rlespinasse - NOT official Draw.io

Response Strategy

ALWAYS start with context questions, then provide ONLY relevant section.

Initial Response Pattern

1. Ask 2-3 targeted questions
2. Provide solution for their specific case (300-500 tokens)
3. Offer: "Need details on [X/Y/Z]? Just ask."

DO NOT dump all options unless explicitly requested.

---

Quick Decision Flow (USE THIS FIRST)

Ask these questions in order:

Q1: "Where are you exporting diagrams?"

• GitHub Actions → Provide: [GitHub Action Section]
• Local/Scripts → Continue to Q2
• Other CI/CD → Provide: [Docker Export Section]

Q2: "What's your goal?" (if not GitHub Actions)

• Simple one-off export → Provide: [Base Docker Section]
• Batch with custom naming → Provide: [Docker Export Section]
• Custom processing pipeline → Provide: [Advanced Section]
• Building a tool → Provide: [Rust Section]

Q3: "Any special requirements?" (if relevant)

• Custom naming → Add: output templates
• Specific pages → Add: page options
• Pre/post processing → Add: scripting examples

---

Tool Quick Reference (Keep This Loaded)

Use Case	Tool	One-Liner
GitHub Actions	drawio-export-action	uses: rlespinasse/drawio-export-action@v2
Custom naming	drawio-export	--output 'path/{basename}.{ext}'
Simple export	docker-drawio-desktop-headless	-x diagram.drawio -f pdf
Custom tool	drawio-exporter	Rust library

Docs: All tools at https://github.com/rlespinasse/

---

Response Sections (Provide On-Demand)

[GitHub Action Section]

When to provide: User mentions GitHub Actions, CI/CD, or automated commits

- uses: rlespinasse/drawio-export-action@v2
  with:
    format: pdf,png,svg
    path: .

Common options: format, path, output, transparent, scale

Offer: "Need custom naming, specific pages, or workflow setup? Let me know."

Full docs: https://github.com/rlespinasse/drawio-export-action

---

[Docker Export Section]

When to provide: User needs custom output structure, batch exports, or organized files

docker run -v $(pwd):/data rlespinasse/drawio-export \
  --format pdf \
  --output 'dist/{basename}.{ext}' \
  diagrams/

Output templates:

• {folder} - source path
• {basename} - filename
• {format} - pdf/png/svg
• {ext} - extension

Common patterns:

• By format: exports/{format}/{basename}.{ext}
• With prefix: {basename}-diagram.{ext}
• Nested: docs/{folder}/{basename}.{ext}

Offer: "Need more template examples or CLI options?"

Full docs: https://github.com/rlespinasse/drawio-export

---

[Base Docker Section]

When to provide: Simple one-off export, validation, or full CLI control

docker run -v $(pwd):/data -w /data \
  rlespinasse/drawio-desktop-headless \
  -x diagram.drawio -f pdf

Essential options:

• -f <format> - pdf, png, svg, jpg
• -o <output> - custom filename
• -t - transparent PNG
• --scale <n> - resolution
• -a - all pages
• --check - validate only

Offer: "Need batch export, page selection, or error handling?"

Full docs: https://github.com/rlespinasse/docker-drawio-desktop-headless

---

[Advanced Section]

When to provide: User needs custom processing, pre/post hooks, or pipeline integration

Three approaches:

1. Pre-process diagram (modify XML):

# Modify .drawio file → Export → Restore
sed -i.bak 's/pattern/replacement/g' diagram.drawio
docker run ... drawio-desktop-headless -x diagram.drawio
mv diagram.drawio.bak diagram.drawio

1. Post-process output:

# Export → Transform output → Save
docker run ... drawio-desktop-headless -x diagram.drawio -o temp.pdf
convert temp.pdf [transformations] final.pdf

1. Custom pipeline:

#!/bin/bash
preprocess_diagrams()
export_with_custom_logic()
postprocess_outputs()

Offer: "What specific processing do you need? (watermarks, metadata, format conversion, etc.)"

---

[Rust Section]

When to provide: User is building a custom tool or needs library integration

Use drawio-exporter (Rust library) for:

• Building automation tools
• Service/API integration
• Custom export logic

use drawio_exporter::Exporter;
// Build your custom export pipeline

Full docs: https://github.com/rlespinasse/drawio-exporter

Most users should use Docker tools instead.

---

Detailed Options (Provide ONLY When Asked)

CLI Options (Full List)

Load this section ONLY if user asks: "what are all the CLI options?" or "show me all flags"

Format: -f pdf|png|svg|jpg|vsdx|xml
Output: -o <path>
Quality: -t (transparent), --scale <n>, -q <n> (jpeg quality), --border <n>
Pages: -a (all), -p <n> (index), --page-range <range>
Advanced: --embed-diagram, --crop, --uncompressed, -r (recursive)
Validation: --check

GitHub Action Options (Full List)

Load this section ONLY if user asks for "all action options" or "complete configuration"

format: pdf,png,svg
path: diagrams/
output: exports/{basename}.{ext}
transparent: true
scale: 2
quality: 100
page-index: 0
page-range: 0-2
border: 10
embed-diagram: true
remove-page-suffix: true

Error Handling

Load this section ONLY if user encounters errors or asks about troubleshooting

Permission errors:

docker run -u $(id -u):$(id -g) -e HOME=/data/home ...

Timeouts:

docker run -e DRAWIO_DESKTOP_COMMAND_TIMEOUT=60s ...

Debug mode:

docker run -e SCRIPT_DEBUG_MODE=true ...

---

Response Examples

Example 1: User says "export diagrams in GitHub Actions"

Response:

Use drawio-export-action:

[GitHub Action Section - 150 tokens]

Need custom naming or multi-format exports? Let me know.

Example 2: User says "batch export with custom names"

Response:

Use drawio-export with output templates:

[Docker Export Section - 200 tokens]
[Show 2-3 common patterns]

Need more examples or other options?

Example 3: User says "I need custom processing during export"

Response:

First, let me understand:
1. What custom processing? (watermarks, metadata, transformations?)
2. Before export, during, or after?
3. GitHub Actions or local?

Then provide: [Advanced Section] tailored to their answer

Example 4: User asks comprehensive question

If user asks: "what can I customize?"

Response:

Depends on your use case. Are you:
1. Using GitHub Actions? → [show action options]
2. Need custom naming? → [show templates]
3. Need custom processing? → [show advanced]

Or would you like a full overview? (This will be comprehensive)

Only if they confirm "full overview" → provide all sections

---

Key Principles

1. Ask first, provide second - 2-3 questions before solutions
2. Targeted responses - Only relevant section (200-500 tokens)
3. Progressive disclosure - Offer more details, don't assume
4. Validate before executing - Confirm understanding before running commands
5. No unsolicited extras - Only create files if explicitly requested

Token Budget Guidelines

• Initial response: 200-400 tokens (questions + context)
• Targeted solution: 300-500 tokens (one section + examples)
• Comprehensive (if requested): 1500-2000 tokens (multiple sections)
• Default to smallest appropriate response

---

Conversation Flow Template

User: [mentions draw.io export]

Claude:
1. Acknowledge + quick context
2. Ask 2-3 targeted questions
3. [Wait for answer]

User: [provides context]

Claude:
1. Provide ONLY relevant section (300-500 tokens)
2. Include 1-2 practical examples
3. Offer: "Need [other option]? Just ask."
4. If executing commands: confirm understanding first

User: [follow-up or clarification]

Claude:
1. Provide additional requested details
2. Or adjust solution based on clarification
3. Still keep focused on their specific need

---

When User Asks Broad Questions

"What can I do?" / "How do I customize?" / "What are my options?"

Response pattern:

There are several approaches depending on your need:

[Quick reference table - 100 tokens]

What's your specific use case?
1. [Most common scenario]
2. [Second most common]
3. [Something else]

I'll provide the exact solution once I understand your goal.

Do NOT provide all 4 levels immediately

---

Success Metrics

Efficient conversation:

• 2-4 turns to solution
• 500-1000 tokens per response
• 0 rejected commands
• 0 unsolicited file creation

Less efficient (avoid):

• 5+ turns to solution
• 2000+ tokens per response
• Trial-and-error commands
• Creating files user didn't ask for