Diagram Customization¶

Trang này dành cho người muốn đổi theme, kích thước, màu nền, hướng hoặc định dạng và lưu các tùy chọn đó cùng mã sơ đồ.

Không phải loại sơ đồ nào cũng hỗ trợ mọi tùy chọn. Hãy kiểm tra cảnh báo sau khi render vì cùng một tùy chọn có thể không áp dụng được cho mọi loại sơ đồ.

Đổi theme¶

Trong Markdown fence:

```plantuml {theme=corporate}
@startuml
Alice -> Bob: Review
@enduml
```

Trong file sơ đồ độc lập:

%%krokup {theme=corporate}
@startuml
Alice -> Bob: Review
@enduml

Thay đổi kích thước¶

Dùng scale để phóng hoặc thu toàn bộ sơ đồ:

%%krokup {scale=1.5}

Shorthand x2 tương đương scale=2. Khi cần giới hạn cụ thể, dùng width, height, max-width hoặc max-height nếu loại sơ đồ và định dạng hỗ trợ.

Scale quá lớn có thể làm kết quả vượt giới hạn. Hãy giảm scale trước; nếu vẫn không render được, liên hệ quản trị viên.

Đổi background¶

Đặt màu trong mã sơ đồ:

%%krokup {background="#f8fafc"}

Trong Playground hoặc Export của VS Code, lựa chọn background cho file cuối có thể độc lập với tùy chọn trong mã sơ đồ. Nếu cần kết quả có thể tái tạo ở mọi công cụ, giữ background trong mã sơ đồ.

Đổi direction¶

%%krokup {direction=lr}

Các giá trị thường dùng là lr, rl, tb và bt. Direction chỉ có tác dụng khi loại sơ đồ cho phép thay đổi hướng layout.

Chọn định dạng¶

Chọn SVG, PNG, JPEG hoặc PDF trong công cụ preview/export hoặc đặt format trong API request. Các định dạng khả dụng phụ thuộc loại sơ đồ:

SVG phù hợp với tài liệu và thao tác zoom.
PNG/JPEG phù hợp với nơi không hỗ trợ SVG.
PDF phù hợp với tài liệu cần in.
Text hoặc định dạng đặc thù chỉ xuất hiện với loại sơ đồ hỗ trợ.

Không đổi phần mở rộng của file sau khi tải để giả lập định dạng khác.

Cú pháp trong Markdown¶

Mẫu chung:

```language {render options} title="Diagram name"
diagram source
```

Đặt các tùy chọn trong đúng một cặp {...} sau language.
Phân cách tùy chọn bằng khoảng trắng, dấu phẩy hoặc dấu chấm phẩy.
Đặt giá trị có khoảng trắng trong dấu ngoặc kép.
Giữ title bên ngoài {...}.
Giữ fence params không vượt quá 1.024 byte.

Ví dụ đầy đủ:

```plantuml {theme=corporate scale=1.5 direction=lr} title="Review flow"
@startuml
Alice -> Bob: Request review
Bob --> Alice: Approved
@enduml
```

Đặt ID ổn định khi review merge request¶

diagram-id giúp GitLab MR Browser Extension ghép đúng phiên bản Before và After. Đặt ID bên ngoài cặp {...} vì đây là metadata phục vụ review, không phải tùy chọn render:

```plantuml diagram-id=review-flow {theme=corporate} title="Review flow"
@startuml
Author -> Reviewer: Request review
@enduml
```

Giữ nguyên ID khi đổi title, vị trí fence, mã sơ đồ hoặc loại sơ đồ. ID phải duy nhất trong file và chỉ dùng chữ thường, số, ., _, -, với độ dài từ 1 đến 64 ký tự. VS Code Extension và GitLab Markdown Integration bỏ metadata này khỏi request render; nó không làm thay đổi hình được tạo ra.

Cú pháp trong mã sơ đồ¶

Đặt %%krokup trong tối đa 20 dòng đầu:

%%krokup {theme=dark scale=2}

Mã sơ đồ chỉ nên có một directive. Dạng %%krokup x2, %%krokup theme=dark, scale=2 và dạng có {...} đều hợp lệ.

Công cụ hỗ trợ cú pháp nào¶

Công cụ	Fence params	Directive trong mã
Playground Fenced block	Có	Playground chuẩn bị directive
VS Code Live Preview	Có	Có
GitLab Documents với GitLab Markdown Integration	Có	Có
GitLab MR Browser Extension	Chưa	Có
Confluence	Có	Có

Thứ tự ưu tiên¶

Fence params được ưu tiên hơn directive ở đầu phần thân. Cấu hình chung của hệ thống có thể đặt mặc định hoặc cố định một số giá trị. Nếu kết quả khác mong đợi, hãy kiểm tra cảnh báo và hỏi quản trị viên xem tùy chọn nào đang được áp dụng chung.

Giới hạn thường gặp¶

Option	Giới hạn chung
`scale`	0,25 đến 8
`width`, `height`	1 đến 32.768
`padding`, `spacing`	0 đến 1.000
`quality`	0 đến 1

Endpoint GET /api/diagram-types cho biết định dạng và tùy chọn mà server hiện hỗ trợ. Chi tiết dành cho người tích hợp API nằm trong API Integration.

Xử lý cảnh báo¶

Playground hiển thị cảnh báo bên dưới preview. Cảnh báo thường có nghĩa một tùy chọn không áp dụng được, không nhất thiết là render thất bại. Client tích hợp API có thể đọc cùng thông tin trong header X-Diagram-Warnings.

Hiện tượng	Cách xử lý
Theme không đổi	Chọn theme được công cụ cung cấp hoặc thử loại sơ đồ khác
Direction bị bỏ qua	Kiểm tra loại sơ đồ có hỗ trợ layout direction
Kết quả quá lớn	Giảm scale, width, height hoặc padding
Định dạng không xuất hiện	Chọn định dạng được công cụ cung cấp
Fence params không có tác dụng trong MR extension	Chuyển tùy chọn vào `%%krokup` trong phần thân