VS Code Extension¶

Extension kết nối tới Code To UML Gateway; Java core và renderer không được bundle trong VSIX. Extension hỗ trợ Live Preview, Markdown fence, render-on-save và export từ editor.

1. Cài extension¶

Cài VSIX do dự án phát hành:

code --install-extension .\code-to-uml-0.10.0.vsix

Tên file thay đổi theo version artifact. Extension hiện yêu cầu VS Code ^1.95.0.

2. Cấu hình¶

Setting	Mặc định	Ý nghĩa
`codeToUml.serverUrl`	`https://kroki-render-vsf.duckdns.org`	Base URL của Gateway
`codeToUml.defaultEngine`	`plantuml`	Fallback khi không nhận dạng được renderer
`codeToUml.livePreview`	`true`	Render lại khi source thay đổi
`codeToUml.renderOnSave`	`true`	Render khi lưu document
`codeToUml.followActiveEditor`	`true`	Preview theo editor đang active
`codeToUml.previewDelay`	`350`	Debounce từ 100 đến 3.000 ms

Không lưu token trong user hoặc workspace settings.

3. Thiết lập token¶

Mở Command Palette.
Chạy Code To UML: Set Rendering API Token.
Nhập shared rendering token.

Token được lưu bằng VS Code SecretStorage. Nhập chuỗi rỗng để xóa token.

4. Commands¶

Command ID	Mục đích
`codeToUml.preview`	Mở hoặc cập nhật Live Preview
`codeToUml.export`	Export diagram hiện tại
`codeToUml.setRenderingApiToken`	Lưu, thay hoặc xóa token
`codeToUml.togglePreviewTheme`	Đổi tone sáng/tối của Live Preview

Preview tone không thay option theme của diagram.

5. Nhận dạng renderer¶

Extension ưu tiên extension file và language ID, sau đó dùng codeToUml.defaultEngine. Với Markdown, language của fence chọn renderer:

```plantuml
@startuml
Alice -> Bob
@enduml
```

6. Params trong Markdown¶

Đặt params trong {...} ngay sau language:

```mermaid {scale=2 theme=dark} title="Checkout flow"
flowchart LR
  Cart --> Payment
```

title nằm ngoài {...} và dùng để nhận diện diagram.
Fence params thắng %%krokup trong phần đầu body.
Fence không có params giữ %%krokup trong body làm fallback.
File diagram độc lập dùng %%krokup vì không có Markdown info string.

7. Live Preview và Markdown Preview¶

Live Preview gửi authenticated POST và dựng heading, paragraph, list, table, code cùng diagram đúng vị trí. SVG và Markdown được sanitize trước khi nhúng.

Markdown Preview có sẵn của VS Code dùng public encoded GET. Source có thể được khôi phục từ URL, vì vậy dùng Live Preview hoặc export cho nội dung nhạy cảm.

8. Export và lỗi thường gặp¶

Sidebar export SVG, PNG và PDF bằng authenticated POST. Format thực tế phụ thuộc renderer.

Hiện tượng	Cách xử lý
`401`	Thiết lập lại token
Không kết nối	Kiểm tra `serverUrl`, DNS, TLS và `/healthz`
Renderer sai	Kiểm tra file extension, fence language và `defaultEngine`
Markdown không render	Kiểm tra language label và fence đóng đúng
Fence params bị bỏ qua	Đặt params trong `{...}` sau language
Export lỗi	Kiểm tra format và quyền ghi file