platform-integrations

What this skill does

# Platform Integrations for draw.io Diagrams

## Format Selection

| Format | Editable | Displayable | Best For |
|--------|----------|-------------|----------|
| `.drawio` | Yes (native) | No (needs app) | Source of truth |
| `.drawio.svg` | Yes (embedded XML) | Yes (renders as SVG) | GitHub, web, markdown |
| `.drawio.png` | Yes (embedded XML) | Yes (renders as PNG) | Confluence, Jira, email |
| `.svg` (exported) | No | Yes | Static documentation |
| `.png` (exported) | No | Yes | Universal fallback |
| `.pdf` (exported) | No | Yes | Print, formal docs |

**Recommended default:** Use `.drawio.svg` files. They render as images everywhere SVG is supported while retaining the editable XML inside the SVG metadata. Re-open in draw.io to edit.

---

## GitHub

### Repository Storage

Store diagrams alongside code in `docs/` or `diagrams/` directories:

```
project/
  docs/
    architecture.drawio.svg
    data-flow.drawio.svg
    er-diagram.drawio.svg
  src/
  README.md
```

### Markdown Embedding

Reference `.drawio.svg` files in any markdown file (README, wiki, PR descriptions):

```markdown
## Architecture

![System Architecture](./docs/architecture.drawio.svg)

## Data Flow

![Data Flow](./docs/data-flow.drawio.svg)
```

GitHub renders SVG files inline. Clicking the image shows the full SVG.

### Pull Request Diagrams

Include diagrams in PR descriptions to document changes:

```markdown
## Changes

This PR refactors the authentication flow:

![Auth Flow Before](./docs/auth-flow-before.drawio.svg)
![Auth Flow After](./docs/auth-flow-after.drawio.svg)
```

For PR comments, upload PNG exports directly or link to SVG files in the branch.

### GitHub Wiki

GitHub wikis support the same image syntax:

```markdown
![Diagram](uploads/architecture.drawio.svg)
```

Or reference from the repo:

```markdown
![Diagram](https://raw.githubusercontent.com/org/repo/main/docs/architecture.drawio.svg)
```

### GitHub Actions: Auto-Export on Push

Create `.github/workflows/drawio-export.yml` to automatically convert `.drawio` files to SVG on push:

```yaml
name: Export draw.io Diagrams

on:
  push:
    paths:
      - '**/*.drawio'

jobs:
  export:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout
        uses: actions/checkout@v4

      - name: Install draw.io Desktop (CLI)
        run: |
          wget -q https://github.com/jgraph/drawio-desktop/releases/download/v24.7.17/drawio-amd64-24.7.17.deb
          sudo apt-get install -y ./drawio-amd64-24.7.17.deb
          sudo apt-get install -y xvfb

      - name: Export changed .drawio to .drawio.svg
        run: |
          CHANGED=$(git diff --name-only HEAD~1 HEAD -- '*.drawio')
          for file in $CHANGED; do
            output="${file}.svg"
            xvfb-run -a drawio --export --format svg --embed-diagram \
              --output "$output" "$file"
            echo "Exported: $output"
          done

      - name: Commit exported SVGs
        run: |
          git config user.name "github-actions[bot]"
          git config user.email "github-actions[bot]@users.noreply.github.com"
          git add '*.drawio.svg'
          git diff --cached --quiet || git commit -m "chore: auto-export draw.io diagrams"
          git push
```

### GitHub Actions: Using drawio-export Action

Alternatively use the community action:

```yaml
- name: Export draw.io
  uses: rlespinasse/drawio-export-action@v2
  with:
    format: svg
    transparent: true
    embed-diagram: true
    output: docs/
```

### VS Code Integration

Install the **hediet.vscode-drawio** extension:

```json
// .vscode/extensions.json
{
  "recommendations": [
    "hediet.vscode-drawio"
  ]
}
```

This allows editing `.drawio`, `.drawio.svg`, and `.drawio.png` files directly in VS Code with a graphical editor. Files are saved in the draw.io format and render correctly on GitHub.

### GitHub Pages

For interactive diagrams on GitHub Pages, embed the draw.io viewer:

```html
<!-- docs/index.html -->
<div class="mxgraph" data-mxgraph='{"url":"architecture.drawio.svg","highlight":"#0000ff","nav":true,"resize":true}'>
</div>
<script src="https://viewer.diagrams.net/js/viewer-static.min.js"></script>
```

Or use an iframe:

```html
<iframe
  src="https://viewer.diagrams.net/?url=https://raw.githubusercontent.com/org/repo/main/docs/architecture.drawio.svg&nav=1"
  width="100%" height="600" frameborder="0">
</iframe>
```

---

## Confluence

### draw.io for Confluence (Marketplace App)

The official draw.io app (by draw.io AG) is the most popular Confluence marketplace app. It adds native diagram capabilities.

#### Insert Diagram

1. Edit a Confluence page
2. Click the `+` button or type `/drawio`
3. Select **draw.io Diagram**
4. Create or edit diagram in the embedded editor
5. Click **Save & Exit** to embed in the page

#### Embed Existing Diagram

Reference a diagram from another Confluence page:

1. Insert macro: **draw.io Diagram** > **Existing Diagram**
2. Select the page containing the source diagram
3. The diagram stays linked and updates when the source changes

#### Board Macro

For whiteboard-style collaborative diagrams:

1. Insert macro: **draw.io Board**
2. Provides an infinite canvas whiteboard
3. Supports real-time collaboration

#### REST API Management

Manage diagrams programmatically via Confluence REST API:

```bash
# Get page content (includes draw.io macro XML)
curl -u user:token \
  "https://your-confluence.atlassian.net/wiki/rest/api/content/PAGE_ID?expand=body.storage" \
  | jq -r '.body.storage.value'

# Update page with new diagram
curl -X PUT -u user:token \
  -H "Content-Type: application/json" \
  "https://your-confluence.atlassian.net/wiki/rest/api/content/PAGE_ID" \
  -d '{
    "version": {"number": NEW_VERSION},
    "title": "Page Title",
    "type": "page",
    "body": {
      "storage": {
        "value": "<ac:structured-macro ac:name=\"drawio\">...</ac:structured-macro>",
        "representation": "storage"
      }
    }
  }'
```

#### Mass Import from Gliffy

draw.io for Confluence includes a Gliffy mass importer:

1. Confluence Admin > draw.io Configuration
2. Select **Gliffy Mass Import**
3. Choose spaces to import
4. Review and confirm migration

#### Confluence Cloud vs Data Center

| Feature | Cloud | Data Center |
|---------|-------|-------------|
| Real-time collaboration | Yes | Yes |
| Custom libraries | Yes | Yes |
| Gliffy import | Yes | Yes |
| Custom colors/fonts | Yes | Yes |
| Lockdown (restrict editing) | Yes | Yes |
| Custom templates | Yes | Yes |
| Revision history | Via page versions | Via page versions |

---

## Jira

### draw.io for Jira (Marketplace App)

#### Attach Diagrams to Issues

1. Open a Jira issue
2. Click the draw.io panel or **Add draw.io diagram** button
3. Create/edit diagram
4. Diagram is stored as an attachment on the issue

#### Embed Confluence Diagrams

If using draw.io for Confluence, reference those diagrams in Jira:

1. In Jira issue description, use the Confluence macro:
   ```
   !confluence-page-url|draw.io diagram!
   ```
2. Or link to the Confluence page containing the diagram

#### Custom Fields for Diagram References

Configure a custom field to store diagram page references:

1. Jira Admin > Custom Fields > Add Custom Field
2. Type: URL
3. Name: "Architecture Diagram"
4. Add to relevant screens

#### Workflow Integration

Link diagrams to workflow statuses:

- Create a diagram per epic showing the feature architecture
- Reference diagrams in story acceptance criteria
- Attach updated diagrams when closing stories

```markdown
## Acceptance Criteria
- [ ] Implementation matches [architecture diagram](confluence-link)
- [ ] Updated sequence diagram reflects API changes
```

---

## Azure DevOps

### Wiki Embedding

Azure DevOps wikis support markdown image syntax. Export diagrams as SVG or PNG and embed:

```markdown
## System Architecture

![Architecture](/.attachments/architecture.drawio.svg)
```

Or reference from the repository:

```markdown
![Architecture](/docs/arch