Bỏ qua

GitLab Documents

Trang này dành cho người muốn hiển thị Diagram as Code trong GitLab repository, wiki hoặc AsciiDoc. Cách dùng cơ bản là tạo một image URL từ mã sơ đồ rồi chèn URL đó vào tài liệu.

Encoded URL không chứa token nhưng có thể được giải mã để lấy lại mã sơ đồ. Chỉ dùng cách này với nội dung được phép xuất hiện trong URL.

Thêm diagram vào tài liệu GitLab

1. Chuẩn bị mã sơ đồ

Lưu mã sơ đồ vào file diagram.puml:

@startuml
Author -> Reviewer: Request review
Reviewer --> Author: Approved
@enduml

Mở file trong Playground hoặc VS Code để chắc chắn sơ đồ render thành công trước khi tạo URL.

2. Tạo đường dẫn ảnh

Chạy từ thư mục chứa diagram.puml:

$encoded = node -e "const z=require('node:zlib'),f=require('node:fs');process.stdout.write(z.deflateSync(f.readFileSync(process.argv[1])).toString('base64url'))" diagram.puml
$url = "https://code-to-uml.example/plantuml/svg/$encoded"
$url

Thay hostname, plantuml và svg bằng địa chỉ Code To UML, loại sơ đồ và định dạng bạn muốn dùng. URL có dạng:

https://code-to-uml.example/{renderer}/{format}/{encodedSource}

3. Chèn URL vào tài liệu

Markdown:

![Review flow](https://code-to-uml.example/plantuml/svg/ENCODED_SOURCE)

AsciiDoc:

image::https://code-to-uml.example/plantuml/svg/ENCODED_SOURCE[Review flow]

Commit hoặc lưu wiki page sau khi chèn.

4. Mở preview và kiểm tra

  1. Mở Markdown preview hoặc trang đã render trên GitLab.
  2. Xác nhận sơ đồ xuất hiện đúng vị trí.
  3. Mở image URL trong tab riêng để kiểm tra khi ảnh không hiển thị.
  4. Xác nhận người đọc mục tiêu cũng mở được địa chỉ ảnh.

Kết quả mong đợi: trình duyệt tải sơ đồ từ Code To UML mà không yêu cầu người đọc nhập token.

5. Sửa lỗi khi ảnh không hiển thị

Hiện tượng Cách xử lý
Trình duyệt không mở được URL Kiểm tra lại hostname và liên hệ quản trị viên nếu địa chỉ không truy cập được
GitLab chặn ảnh Gửi hostname của Code To UML cho quản trị viên GitLab kiểm tra
404 Kiểm tra loại sơ đồ, định dạng và phần mã hóa trong URL
Sơ đồ lỗi Render mã sơ đồ trong Playground hoặc VS Code trước
Ảnh cũ Tạo encoded URL mới từ mã sơ đồ mới rồi tải lại trang

Tùy chỉnh diagram trong URL

Vì URL chứa mã sơ đồ đã encode, hãy đặt directive ở đầu mã trước khi tạo URL:

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

Sau khi đổi directive, tạo lại encoded URL. Xem Diagram Customization để chọn tùy chọn.

Dùng fence params trên GitLab self-managed

Nếu quản trị viên xác nhận GitLab đã bật GitLab Markdown Integration của Code To UML, bạn có thể đặt tùy chọn trên dòng mở fence:

```plantuml {theme=corporate scale=1.5 direction=lr} title="Review flow"
Alice -> Bob: Review
```
  1. Thêm fence vào repository Markdown hoặc wiki.
  2. Mở preview.
  3. Kiểm tra theme, scale hoặc direction đã được áp dụng.

Tính năng này chỉ hoạt động trên GitLab self-managed đã được cấu hình. Nếu tham số bị bỏ qua, hãy thử directive %%krokup trong phần thân hoặc liên hệ quản trị viên. Quy trình build, upgrade và rollback nằm trong Operations.

Lưu ý bảo mật

  • Không đưa token truy cập vào Markdown, image URL hoặc query string.
  • Không dùng encoded GET nếu mã sơ đồ chứa dữ liệu không được phép xuất hiện trong URL.
  • Với mã dài hoặc nhạy cảm, dùng quy trình CI/backend đã được đội dự án phê duyệt để tạo file kết quả rồi lưu theo quy định của repository.
  • Pydia thực thi Python; chỉ dùng khi quản trị viên xác nhận repository được phép.

Chi tiết route, encoding, ETag và status code nằm trong API Integration.