UML Navigator
Preview Mermaid diagrams in VS Code and click on entities to navigate directly to the corresponding source code file and line number.
Currently supported diagram types:
- classDiagram: click on class names to jump to source
- graph / flowchart: click on nodes to jump to source (via
.classmap.json)
- sequenceDiagram: reserved for future support
Features
- Interactive Diagrams: Renders Mermaid diagrams in a Webview panel with full interactivity.
- Click-to-Navigate: Click on any entity (class name, node ID, etc.) in the diagram to jump to its source file and line number.
- Multi-Diagram Support: Extensible architecture supporting multiple Mermaid diagram types.
- Theme Sync: Automatically adapts the diagram theme when you switch between light and dark VS Code themes.
- Context Menu Integration: Right-click on
.md files in the editor or explorer to preview diagrams.
Usage
1. Prepare Your Markdown File
Your .md file should contain Mermaid code blocks (e.g. classDiagram, graph TD, etc.):
```mermaid
classDiagram
class UserService {
+getUser(id: string) User
+createUser(data: UserData) User
}
class UserRepository {
+findById(id: string) User
+save(user: User) void
}
UserService --> UserRepository : uses
```
2. Create a .classmap.json File
Place a .classmap.json file in the same directory as your .md files. This file maps entity names (class names, node IDs, etc.) to their source file locations, keeping your Markdown clean and free of navigation metadata.
The top-level keys are Markdown file names, and the values are entity-to-location mappings. A single .classmap.json can describe entities for multiple .md files:
{
"design.md": {
"UserService": {
"path": "src/services/userService.ts",
"line": 10
},
"UserRepository": {
"path": "src/repositories/userRepository.ts",
"line": 5
}
},
"architecture.md": {
"OrderService": {
"path": "src/services/orderService.ts",
"line": 8
}
}
}
Each entry in the navigation map must have:
- path: Relative path from the workspace root to the source file.
- line: 1-based line number where the entity is defined.
3. Preview the Diagram
You can trigger the preview in three ways:
- Command Palette: Press
Ctrl+Shift+P (or Cmd+Shift+P on macOS), then type UML Navigator: Preview.
- Editor Context Menu: Right-click inside a
.md file and select Preview Mermaid Diagram.
- Explorer Context Menu: Right-click on a
.md file in the file explorer and select Preview Mermaid Diagram.
4. Navigate to Source Code
Click on any entity in the rendered diagram. If the entity is defined in the .classmap.json file, the corresponding source file will open and scroll to the specified line.
code --install-extension uml-navigator-0.0.1.vsix
From Source
git clone <repository-url>
cd uml-navigator
npm install
npm run compile
Then press F5 in VS Code to launch the Extension Development Host.
File Structure
uml-navigator/
├── package.json # Extension manifest: commands, activation, menus
├── tsconfig.json # TypeScript compiler configuration
├── .vscodeignore # Packaging exclusion rules
├── src/
│ ├── extension.ts # Entry point, command registration, module coordination
│ ├── markdownParser.ts # Markdown parsing, Mermaid block extraction, diagram type detection
│ ├── classmapLoader.ts # External .classmap.json navigation map loading
│ ├── webviewProvider.ts # Webview panel creation, HTML content generation
│ └── fileNavigator.ts # Source file navigation logic
├── media/
│ └── mermaid.min.js # Mermaid.js library (bundled locally)
├── example/
│ ├── test-diagram.md # Example Markdown file for testing
│ └── .classmap.json # Example navigation map descriptor
└── README.md
Requirements
License
MIT
