--- 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](https://github.com/rlespinasse) - NOT official Draw.io** ## Response Strategy **ALWAYS start with context questions, then provide ONLY relevant section.** ### Initial Response Pattern ```text 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 --- ## Response Sections (Provide On-Demand) ### [GitHub Action Section] **When to provide:** User mentions GitHub Actions, CI/CD, or automated commits ```yaml - 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:** --- ### [Docker Export Section] **When to provide:** User needs custom output structure, batch exports, or organized files ```bash 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:** --- ### [Base Docker Section] **When to provide:** Simple one-off export, validation, or full CLI control ```bash docker run -v $(pwd):/data -w /data \ rlespinasse/drawio-desktop-headless \ -x diagram.drawio -f pdf ``` **Essential options:** - `-f ` - pdf, png, svg, jpg - `-o ` - custom filename - `-t` - transparent PNG - `--scale ` - resolution - `-a` - all pages - `--check` - validate only **Offer:** "Need batch export, page selection, or error handling?" **Full docs:** --- ### [Advanced Section] **When to provide:** User needs custom processing, pre/post hooks, or pipeline integration **Three approaches:** 1. **Pre-process diagram (modify XML):** ```bash # 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:** ```bash # Export → Transform output → Save docker run ... drawio-desktop-headless -x diagram.drawio -o temp.pdf convert temp.pdf [transformations] final.pdf ``` 1. **Custom pipeline:** ```bash #!/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 ```rust use drawio_exporter::Exporter; // Build your custom export pipeline ``` **Full docs:** **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"** ```text Format: -f pdf|png|svg|jpg|vsdx|xml Output: -o Quality: -t (transparent), --scale , -q (jpeg quality), --border Pages: -a (all), -p (index), --page-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"** ```yaml 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:** ```bash docker run -u $(id -u):$(id -g) -e HOME=/data/home ... ``` **Timeouts:** ```bash docker run -e DRAWIO_DESKTOP_COMMAND_TIMEOUT=60s ... ``` **Debug mode:** ```bash docker run -e SCRIPT_DEBUG_MODE=true ... ``` --- ## Response Examples ### Example 1: User says "export diagrams in GitHub Actions" **Response:** ```text 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:** ```text 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:** ```text 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:** ```text 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 ```text 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:** ```text 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