Kroki Diagram Preview & Export

Preview and export diagrams directly in VS Code/Cursor using Kroki API

Features • Installation • Usage • Examples • Contributing • License

🌟 Features

Core Features

✅ Modern UI - Professional preview panel with toolbar, status bar, and smooth animations
✅ Zoom & Pan - Full zoom controls (zoom in/out, fit to window, reset) with mouse wheel and keyboard shortcuts
✅ Fullscreen Mode - Toggle fullscreen view for better diagram viewing experience
✅ Auto-refresh - Automatically updates preview when editing diagram code (debounced 500ms)
✅ Image Caching - Intelligent caching system for faster diagram loading (5-minute TTL)

Diagram Support

✅ 20+ Diagram Types - PlantUML, Mermaid, GraphViz, Ditaa, C4, D2, DBML, Excalidraw, BPMN, Vega, and more
✅ Multiple Formats - Export as SVG, PNG, JPEG, or PDF
✅ Smart Detection - Automatically detects diagram at cursor position

Developer Experience

✅ Keyboard Shortcuts - Quick access with Ctrl+Shift+K (preview) and Ctrl+Alt+K (export)
✅ Copy Diagram URL - Share diagrams with shareable URLs
✅ Error Handling - Beautiful error messages with network and server error detection
✅ Loading States - Visual feedback during diagram generation

Technical

✅ No Dependencies - No need to install Java or other dependencies
✅ Free API - Uses free Kroki API service
✅ Lightweight - Fast and efficient extension

📦 Installation

Option 1: Install from GitHub Releases (Easiest - Recommended)

Go to Releases on GitHub
Download the latest .vsix file (e.g., kroki-preview-1.1.0.vsix)
Open VS Code or Cursor
Open Extensions view (Ctrl+Shift+X or Cmd+Shift+X)
Drag and drop the downloaded .vsix file into the Extensions panel
The extension will be installed automatically!

Alternative method:

Click ... (three dots) in Extensions view → Install from VSIX... → Select the downloaded file

Or use command line:

code --install-extension kroki-preview-1.1.0.vsix
# For Cursor:
cursor --install-extension kroki-preview-1.1.0.vsix

Option 2: Build from Source

# Clone the repository
git clone https://github.com/TienNHM/vscode-kroki-preview.git
cd vscode-kroki-preview

# Install dependencies
npm install

# Compile TypeScript
npm run compile

# Package extension
npm run vscode:prepublish
vsce package

# Install the generated .vsix file
code --install-extension kroki-preview-*.vsix

Option 3: Development Mode

# Clone and install
git clone https://github.com/TienNHM/vscode-kroki-preview.git
cd vscode-kroki-preview
npm install

# Open in VS Code
code .

# Press F5 to run Extension Development Host

🚀 Usage

Preview Diagram

Open a Markdown file containing a diagram (PlantUML, Mermaid, GraphViz, etc.)
Place cursor inside the diagram code block
Right-click → Select "Kroki: Preview Diagram"
- Or use keyboard shortcut: Ctrl+Shift+K (Mac: Cmd+Shift+K)
- Or Command Palette (Ctrl+Shift+P) → Kroki: Preview Diagram

The diagram will be displayed in a modern webview panel with:

Zoom controls: Zoom in/out, fit to window, reset
Pan: Click and drag to move the diagram
Fullscreen: Click fullscreen button or press F11
Copy URL: Copy link to share the diagram
Auto-refresh: Automatically updates when you edit the code

Export Diagram

Place cursor inside the diagram code block
Right-click → Select "Kroki: Export Diagram as Image"
- Or use keyboard shortcut: Ctrl+Alt+K (Mac: Cmd+Alt+K)
Choose format (SVG, PNG, JPEG, PDF)
Select save location

Keyboard Shortcuts

Global Shortcuts

Ctrl+Shift+K / Cmd+Shift+K - Preview diagram
Ctrl+Alt+K / Cmd+Alt+K - Export diagram

Preview Panel Shortcuts

Ctrl/Cmd + or Ctrl/Cmd + = - Zoom in
Ctrl/Cmd + - - Zoom out
Ctrl/Cmd + 0 - Fit to window
Ctrl/Cmd + 1 - Reset zoom (1:1)
F11 - Toggle fullscreen
Mouse wheel + Ctrl/Cmd - Zoom in/out
Click + Drag - Pan diagram

Auto-Refresh

When previewing a diagram, it will automatically refresh after 500ms when you edit the diagram code. No need to click preview again!

⚙️ Configuration

Open Settings (Ctrl+,) and search for "Kroki":

Setting	Description	Default
Kroki: Server Url	URL of the Kroki server	`https://kroki.io`
Kroki: Default Format	Default export format	`svg`
Kroki: Use Post Request	Use POST instead of GET requests	`false`

Note:

false (GET): Creates shareable URLs, suitable for small to medium diagrams
true (POST): Suitable for large diagrams, no URL length limitations

📊 Supported Diagram Types

This extension supports 20+ diagram types from Kroki:

Category	Diagram Types
UML & Architecture	PlantUML, C4, Structurizr, UMLet
Flowcharts & Diagrams	Mermaid, GraphViz/DOT, BlockDiag, Nomnoml
Database	DBML, ERD
Business	BPMN
Design	Excalidraw, Diagrams.net
Data Visualization	Vega, Vega-Lite
Technical	Ditaa, D2, Bytefield, Pikchr, SVGBob, WaveDrom, WireViz

See EXAMPLES.md for comprehensive examples.

Quick Examples

PlantUML

```plantuml
@startuml
Alice -> Bob: Hello
Bob --> Alice: Hi!
@enduml
```

Mermaid

```mermaid
graph TD
    A[Start] --> B{Decision}
    B -->|Yes| C[Action 1]
    B -->|No| D[Action 2]
```

GraphViz

```graphviz
digraph G {
    A -> B
    B -> C
    C -> A
}
```

📚 Examples

Check out EXAMPLES.md for comprehensive examples including:

Sequence diagrams
Class diagrams
Flowcharts
Gantt charts
State diagrams
ER diagrams
And more!

🐛 Troubleshooting

Diagram Not Displaying

Check internet connection - Kroki API requires internet access
Verify diagram syntax - Check for syntax errors in your diagram code
Check Output panel - View → Output → Select "Kroki Preview" for detailed errors
Try different format - Some diagrams work better with POST requests (enable in settings)

Export Fails

Check file permissions - Ensure you have write permissions at the save location
Verify format support - Check if the selected format is supported by Kroki
Check Output panel - View detailed error messages

Performance Issues

Enable caching - Caching is enabled by default (5-minute TTL)
Use POST requests - For large diagrams, enable POST requests in settings
Check network - Slow network can affect diagram loading

Still Having Issues?

Check TROUBLESHOOTING.md for detailed solutions
Open an issue on GitHub
Check Kroki API documentation

🛠️ Development

Prerequisites

Node.js 18+ and npm
VS Code 1.80.0+
TypeScript 5.0+

Setup

# Clone repository
git clone https://github.com/TienNHM/vscode-kroki-preview.git
cd vscode-kroki-preview

# Install dependencies
npm install

# Compile TypeScript
npm run compile

# Watch mode (auto-compile on changes)
npm run watch

Build

# Build extension
npm run compile

# Package extension
vsce package

Debug

Open project in VS Code
Press F5 to launch Extension Development Host
Open a Markdown file with diagrams and test commands

Project Structure

vscode-kroki-preview/
├── src/
│   └── extension.ts      # Main extension code
├── out/                  # Compiled JavaScript
├── package.json          # Extension manifest
├── tsconfig.json         # TypeScript configuration
└── README.md            # This file

🤝 Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

How to Contribute

Fork the repository
Create a feature branch (git checkout -b feature/amazing-feature)
Make your changes
Commit your changes (git commit -m 'Add some amazing feature')
Push to the branch (git push origin feature/amazing-feature)
Open a Pull Request

Contribution Guidelines

Follow the existing code style
Add tests if applicable
Update documentation as needed
Ensure all tests pass
Be respectful and constructive in discussions

Reporting Issues

When reporting issues, please include:

VS Code version
Extension version
Steps to reproduce
Expected vs actual behavior
Screenshots if applicable

See CONTRIBUTING.md for detailed guidelines.

📝 Changelog

See CHANGELOG.md for a list of changes and version history.

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

🙏 Acknowledgments

Kroki - Unified API for diagram libraries
PlantUML - PlantUML diagram library
Mermaid - Mermaid diagram library
VS Code Extension API - VS Code extension framework

⭐ Show Your Support

If this extension is helpful to you, please consider:

⭐ Starring this repository
🐛 Reporting bugs
💡 Suggesting new features
🔄 Contributing code improvements
📢 Sharing with others

Made with ❤️ for the VS Code community

GitHub • Issues • Releases

Name		Name	Last commit message	Last commit date
Latest commit History 9 Commits
.github/workflows		.github/workflows
src		src
.gitignore		.gitignore
.vscodeignore		.vscodeignore
BUILD_LOCAL.md		BUILD_LOCAL.md
CHANGELOG.md		CHANGELOG.md
CONTRIBUTING.md		CONTRIBUTING.md
CURSOR_INSTALL.md		CURSOR_INSTALL.md
EXAMPLES.md		EXAMPLES.md
HUONGDAN.md		HUONGDAN.md
KROKI_API.md		KROKI_API.md
LICENSE		LICENSE
MARKETPLACE_PUBLISH.md		MARKETPLACE_PUBLISH.md
PUBLISH.md		PUBLISH.md
QUICKSTART.md		QUICKSTART.md
README.md		README.md
RELEASE_GUIDE.md		RELEASE_GUIDE.md
TROUBLESHOOTING.md		TROUBLESHOOTING.md
build-local.ps1		build-local.ps1
package-lock.json		package-lock.json
package.json		package.json
publish-marketplace.ps1		publish-marketplace.ps1
publish.ps1		publish.ps1
release.ps1		release.ps1
setup.ps1		setup.ps1
tsconfig.json		tsconfig.json

License

TienNHM/vscode-kroki-preview

Folders and files

Latest commit

History

Repository files navigation