WharfMap VS Code Extension

Overview

WharfMap is a Visual Studio Code extension that visualizes Mermaid diagrams from Docker Compose YAML files using custom TypeScript logic. It is designed to help you quickly understand and explore network and system topologies described in Docker Compose files, including custom x-wharfmap fields.

Features

• Visualize Docker Compose YAML files as Mermaid diagrams with a single click.
• Context menu integration: Right-click .yml or .yaml files and select "Visualize with Wharf Map".
• Inline visualization button: A "Visualize with Wharf Map" button appears at the top of Docker Compose YAML files.
• Export diagrams: Save the raw Mermaid diagram as a .txt file from the visualization webview.
• Supports custom x-wharfmap fields for enhanced diagram generation and styling.
• Zoom and pan: Use mouse wheel, drag, or buttons to zoom and navigate the diagram in the webview (powered by panzoom).
• Real-time updates: Diagrams update as you edit the YAML file.

Installation

1. Clone or download this repository to your local machine.
2. Open the folder in Visual Studio Code.
3. Run npm install to install dependencies.
4. Run npm run compile to build the extension.
5. Press F5 to launch the extension in a new Extension Development Host window.

Usage

Visualizing a Docker Compose YAML File

• Open any Docker Compose .yml or .yaml file in VS Code.
• Click the "Visualize with Wharf Map" button at the top of the editor, or right-click the file in the Explorer and select "Visualize with Wharf Map".
• A webview panel will open, displaying the Mermaid diagram generated from your Docker Compose file.

Exporting the Diagram

• In the visualization webview, click the "Export as HTML" button to save the diagram as a .txt file containing only the raw Mermaid code.

x-wharfmap Fields

WharfMap supports custom fields in your Docker Compose YAML files to enhance diagram generation and styling. These fields should be prefixed with x-wharfmap and can be used to provide additional metadata, styling, or relationships for the visualization.

Example Docker Compose YAML with x-wharfmap

services:
  db:
    image: postgres
    x-wharfmap:
      color: "#FFD700"
      border-color: "#333"
      border-width: "2px"
      border-style: "dashed"
  app:
    image: myapp
    x-wharfmap:
      color: "#87CEEB"
      border-color: "#222"
      border-width: "2px"
      border-style: "solid"

Supported x-wharfmap Fields

• color: Node or subgraph fill color (hex or CSS color).
• border-color: Border color for nodes or subgraphs.
• border-width: Border width (e.g., "2px").
• border-style: "dashed" or "solid" for border style.

Advanced Styling

• You can use these fields under services, x-wharfmap.networks, x-wharfmap.profiles, and x-wharfmap.conditions to style nodes, network subgraphs, profile subgraphs, and link edges respectively.
• For depends_on conditions, you can style edges using x-wharfmap.conditions (e.g., stroke-width, stroke-dasharray).

Example for Edge Styling

x-wharfmap:
  conditions:
    service_healthy:
      stroke-width: "3px"
      stroke-dasharray: "5 5"

Troubleshooting

• If the diagram does not render, ensure your Docker Compose YAML is valid and contains the expected structure.
• For issues with custom fields or styling, check your TypeScript logic in visualizer.ts.

Contributing

Feel free to submit issues or pull requests to improve WharfMap!

License

MIT