WharfMap VS Code Extension

A Visual Studio Code extension that visualizes Docker Compose YAML files as interactive Mermaid diagrams with real-time updates and comprehensive styling options.

Features

🎯 Core Functionality

• Visual Docker Compose Analysis: Convert docker-compose.yml files into clear Mermaid diagrams
• Real-time Updates: Diagrams automatically refresh when you edit your YAML files
• Interactive Navigation: Pan, zoom, and explore your container architecture
• Version Information: Display service versions with automatic Docker Hub tag resolution

🎨 Customizable Styling

• Live Settings Panel: Dedicated activity bar with real-time configuration
• Element-specific Colors: Customize colors for services, networks, profiles, and built containers
• Border Styling: Configure border colors, widths, and styles (solid/dashed)
• Advanced Options: Support for x-wharfmap custom styling in YAML files

📤 Export Options

• Mermaid Text Export: Save diagrams as .txt files for use in other tools
• Image Export: Export as PNG or SVG files with high-quality rendering
• Multiple Formats: Choose between vector (SVG) and raster (PNG) formats

🚀 Smart Features

• Profile Support: Visualize Docker Compose profiles with grouped containers
• Network Visualization: Show container networking relationships
• Build Context Detection: Highlight containers built from Dockerfiles
• Dependency Mapping: Display depends_on relationships with condition labels

Installation

1. Open VS Code
2. Go to Extensions (Ctrl+Shift+X)
3. Search for "WharfMap"
4. Click Install

Usage

Basic Usage

1. Right-click on any docker-compose.yml or docker-compose.yaml file
2. Select "Visualize with WharfMap"
3. The diagram will open in a new panel alongside your editor

Settings Configuration

1. Open the WharfMap activity panel (left sidebar)
2. Adjust colors, borders, and display options in real-time
3. Changes apply immediately to all open diagrams

Export Diagrams

• Text Export: Click "Export as Mermaid Text" to save the raw Mermaid code
• Image Export: Click "Export as Image" and choose PNG or SVG format

Advanced Configuration

Custom Styling with x-wharfmap

The x-wharfmap extension allows you to define custom styling directly in your Docker Compose YAML files using Docker's extension field syntax. This provides granular control over the visual appearance of your diagrams.

Service-Level Styling

Apply custom styles to individual services by adding x-wharfmap under any service:

services:
  web:
    image: nginx:latest
    x-wharfmap:
      color: "#e3f2fd"           # Fill/background color
      border-color: "#1976d2"    # Border color
      border-width: "3px"        # Border thickness (with units)
      border-style: "dashed"     # Border style: "solid" or "dashed"
  
  api:
    image: node:18
    x-wharfmap:
      color: "#fff3e0"
      border-color: "#f57c00"
      border-width: "2px"
      border-style: "solid"

Global Profile Styling

Style entire Docker Compose profiles to visually group related services:

x-wharfmap:
  profiles:
    production:
      color: "#fff3e0"          # Orange theme for production
      border-color: "#f57c00"
      border-width: "2px"
      border-style: "solid"
    
    development:
      color: "#e8f5e9"          # Green theme for development
      border-color: "#388e3c"
      border-width: "2px"
      border-style: "dashed"    # Dashed for dev environment
    
    testing:
      color: "#fce4ec"          # Pink theme for testing
      border-color: "#c2185b"
      border-width: "1px"

Network Styling

Customize the appearance of network containers that group services:

x-wharfmap:
  networks:
    frontend:
      color: "#e3f2fd"          # Light blue for frontend network
      border-color: "#1976d2"
      border-width: "2px"
      border-style: "solid"
    
    backend:
      color: "#fff3e0"          # Light orange for backend network
      border-color: "#f57c00"
      border-width: "2px"
      border-style: "solid"

Dependency Condition Styling

Style the lines that represent service dependencies and their conditions:

x-wharfmap:
  conditions:
    service_healthy:
      stroke-width: "3px"       # Thick line for health checks
      stroke-dasharray: "5 5"   # Dashed pattern (dash, gap)
    
    service_started:
      stroke-width: "2px"       # Medium line for startup dependencies
      stroke-dasharray: "0"     # Solid line (no dashes)
    
    service_completed_successfully:
      stroke-width: "4px"       # Extra thick for completion dependencies
      stroke-dasharray: "10 5"  # Long dash pattern

Complete Example

Here's a comprehensive example showing all styling options:

version: '3.8'

services:
  nginx:
    image: nginx:alpine
    profiles: ["production"]
    depends_on:
      api:
        condition: service_healthy
    x-wharfmap:
      color: "#e8f5e9"
      border-color: "#2e7d32"
      border-width: "3px"
      border-style: "solid"

  api:
    image: node:18
    profiles: ["production", "development"]
    depends_on:
      database:
        condition: service_started
    x-wharfmap:
      color: "#fff3e0"
      border-color: "#e65100"
      border-width: "2px"
      border-style: "dashed"

  database:
    image: postgres:15
    profiles: ["production"]
    x-wharfmap:
      color: "#f3e5f5"
      border-color: "#7b1fa2"
      border-width: "2px"

# Global styling configuration
x-wharfmap:
  # Background styling options
  backgroundColor: "#f5f5f5"
  backgroundBorderColor: "#cccccc"
  backgroundBorderWidth: 2
  # Style profiles (overrides individual service styles within profiles)
  profiles:
    production:
      color: "#e8f5e9"
      border-color: "#2e7d32"
      border-width: "2px"
    development:
      color: "#fff3e0"
      border-color: "#e65100"
      border-width: "1px"
      border-style: "dashed"
  
  # Style networks
  networks:
    frontend:
      color: "#e3f2fd"
      border-color: "#1976d2"
      border-width: "2px"
    backend:
      color: "#fff8e1"
      border-color: "#f9a825"
      border-width: "2px"
  
  # Style dependency conditions
  conditions:
    service_healthy:
      stroke-width: "3px"
      stroke-dasharray: "5 5"
    service_started:
      stroke-width: "2px"
      stroke-dasharray: "0"
    service_completed_successfully:
      stroke-width: "4px"
      stroke-dasharray: "10 2"

Styling Priority

The extension applies styles in the following order (highest to lowest priority):

1. Service-level x-wharfmap - Highest priority, overrides everything
2. Global profile styles - Applied to all services in a profile
3. Global network styles - Applied to network containers
4. Activity panel defaults - Your configured default colors
5. Built-in defaults - Extension's default color scheme

Color Format Support

• Hex colors: "#ff0000", "#f00"
• RGB values: "rgb(255, 0, 0)"
• Color names: "red", "blue", "green"

Border Style Options

• "solid": Continuous line (default)
• "dashed": Converts to dashed pattern automatically

Stroke Dash Array Patterns

For dependency conditions, use stroke-dasharray values:

• "0": Solid line
• "5 5": Equal dashes and gaps
• "10 3": Long dashes, short gaps
• "2 3 5 3": Complex alternating pattern

Supported Files

• docker-compose.yml
• docker-compose.yaml
• compose.yml
• compose.yaml

Requirements

• VS Code 1.70.0 or higher
• Docker Compose YAML files with valid syntax

Extension Settings

All settings are managed through the integrated activity panel with real-time updates. No manual configuration required!

Known Issues

• Large diagrams (50+ services) may take a few seconds to render
• Internet connection required for Docker Hub tag resolution

Release Notes

1.0.1

• Added comprehensive activity panel with live settings
• Implemented PNG and SVG export functionality
• Added real-time diagram updates
• Enhanced styling options with border controls
• Improved responsive design for activity panel
• Added version display controls

Previous Versions

• Basic Mermaid diagram generation
• Context menu integration
• Profile and network support