VS Code Extension¶

VS Code Extension dành cho người viết Diagram as Code trong workspace. Bạn có thể mở Live Preview cho file sơ đồ, xem nhiều sơ đồ trong Markdown và xuất file mà không rời editor.

Trước khi bắt đầu¶

Bạn cần VS Code 1.95.0 trở lên, VSIX do dự án phát hành, địa chỉ Code To UML và token truy cập.

Cài VSIX:

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

Tên file thay đổi theo version được phát hành.

Kết nối tới Code To UML¶

Mở Settings và tìm Code To UML.
Kiểm tra Code To UML: Server Url.
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, không nằm trong User Settings hoặc Workspace Settings. Nhập chuỗi rỗng khi chạy lệnh đặt token để xóa token đã lưu.

Các setting thường dùng:

Setting	Mặc định	Khi nào cần đổi
`codeToUml.serverUrl`	Địa chỉ production của dự án	Khi dùng local hoặc môi trường khác
`codeToUml.defaultEngine`	`plantuml`	Khi extension không nhận ra loại sơ đồ từ file
`codeToUml.livePreview`	`true`	Tắt nếu không muốn render khi đang gõ
`codeToUml.renderOnSave`	`true`	Tắt nếu không muốn render ngay khi lưu
`codeToUml.followActiveEditor`	`true`	Tắt để preview giữ nguyên document hiện tại
`codeToUml.previewDelay`	`350` ms	Tăng nếu document lớn hoặc thay đổi liên tục

Mở Live Preview cho file diagram¶

Mở một file được hỗ trợ, ví dụ .puml hoặc .mmd.
Chạy Code To UML: Open Live Preview từ Command Palette hoặc menu editor.
Chỉnh sửa mã sơ đồ.
Kiểm tra preview cập nhật và đọc cảnh báo nếu có.

Ví dụ PlantUML:

@startuml
Editor -> Gateway: Render
Gateway --> Editor: SVG
@enduml

Kết quả mong đợi: webview hiển thị diagram của active editor. Khi livePreview bật, preview cập nhật sau khoảng delay đã cấu hình.

Preview Markdown có nhiều diagram¶

Đặt language cho từng fence:

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

```mermaid
flowchart LR
  Source --> Diagram
```

Mở file Markdown rồi chạy Code To UML: Open Live Preview. Extension giữ heading, paragraph, list, table, code và diagram theo thứ tự trong document.

Nếu một fence không render, kiểm tra language label và dấu đóng fence. Extension chọn loại sơ đồ từ language của fence; defaultEngine chỉ là fallback.

Tùy chỉnh một diagram trong Markdown¶

Đặt options trong cặp {...} ngay sau language:

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

title nằm ngoài cặp ngoặc và giúp nhận diện sơ đồ. File sơ đồ độc lập không có Markdown fence nên dùng directive %%krokup. Xem Diagram Customization để biết ví dụ và thứ tự ưu tiên.

Xuất diagram¶

Đặt con trỏ trong file hoặc diagram cần xuất.
Chạy Code To UML: Export Diagram.
Chọn SVG, PNG hoặc PDF nếu loại sơ đồ hỗ trợ.
Chọn vị trí lưu.
Mở file đã lưu để kiểm tra.

Lệnh export dùng cùng địa chỉ Code To UML và token với Live Preview. Nếu một định dạng không xuất hiện hoặc bị từ chối, hãy chọn định dạng khác được loại sơ đồ đó hỗ trợ.

Điều khiển thời điểm cập nhật¶

Với livePreview=true, preview đang mở cập nhật khi mã sơ đồ thay đổi.
Với renderOnSave=true, thao tác lưu document kích hoạt render ngay.
Với followActiveEditor=true, preview chuyển theo editor active.

Nếu muốn giữ nguyên mã và preview để so sánh, tạm tắt followActiveEditor hoặc livePreview, sau đó chạy lại lệnh preview khi sẵn sàng.

Xử lý sự cố¶

Hiện tượng	Cách xử lý
`401`	Chạy lại lệnh đặt token
Không kết nối	Kiểm tra server URL, DNS, TLS và endpoint `/healthz`
Chọn sai loại sơ đồ	Kiểm tra file extension, fence language và `defaultEngine`
Markdown không render	Kiểm tra language label và fence đóng đúng
Options bị bỏ qua	Đặt options trong `{...}` sau language hoặc dùng `%%krokup` cho file độc lập
Preview cập nhật quá nhiều	Tăng `previewDelay` hoặc tắt `livePreview`
Export lỗi	Kiểm tra định dạng hỗ trợ và quyền ghi thư mục đích