GitLab Documents¶
GitLab Markdown Integration cho phép viết và duy trì diagram ngay trong file Markdown hoặc wiki trên GitLab self-managed. Người dùng chỉ cần thêm code fence; GitLab tự tạo image URL và hiển thị kết quả từ Krokup.
Trước khi bắt đầu, hãy xác nhận với quản trị viên rằng repository đang dùng GitLab Markdown Integration và renderer bạn cần đã được bật.
Thêm diagram vào tài liệu GitLab¶
1. Thêm code fence¶
Mở file Markdown hoặc wiki page rồi thêm source vào fence mang tên renderer:
```plantuml
@startuml
Author -> Reviewer: Request review
Reviewer --> Author: Approved
@enduml
```
Có thể dùng các renderer khác đã được quản trị viên bật, chẳng hạn mermaid,
d2 hoặc graphviz.
2. Mở preview¶
- Chọn Preview khi chỉnh sửa file hoặc wiki page.
- Xác nhận diagram xuất hiện đúng vị trí.
- Sửa source nếu GitLab hiển thị lỗi cú pháp.
- Commit file hoặc lưu wiki page khi kết quả đã đúng.
GitLab Markdown Integration xử lý fence trước Markdown renderer. GitLab tạo encoded image URL trong HTML, sau đó browser tải diagram từ Krokup. Người dùng không cần tạo URL hoặc nhập rendering token.
Tùy chỉnh diagram¶
Đặt các tùy chọn trong {...} trên dòng mở fence:
```plantuml {theme=corporate scale=1.5 direction=lr} title="Review flow"
Alice -> Bob: Review
```
Sau khi đổi source hoặc tùy chọn, mở lại preview rồi commit thay đổi. Xem Diagram Customization để biết các tùy chọn và thứ tự ưu tiên.
Sửa lỗi khi diagram không hiển thị¶
| Hiện tượng | Cách xử lý |
|---|---|
| Fence vẫn hiển thị như code | Kiểm tra tên renderer rồi liên hệ quản trị viên để xác nhận integration và renderer đã được bật |
Tùy chọn trong {...} bị bỏ qua |
Kiểm tra cú pháp fence; nếu source có directive cũ, fence params được ưu tiên |
| Diagram báo lỗi | Mở source trong Playground hoặc VS Code để tìm lỗi cú pháp |
| Browser không tải được ảnh | Gửi URL trang và thời điểm xảy ra lỗi cho quản trị viên kiểm tra Gateway và GitLab CSP |
| Người khác không xem được diagram | Xác nhận họ truy cập được trang GitLab và hostname Krokup |
Quy trình kiểm tra, upgrade và rollback integration nằm trong Operations.
Lưu ý bảo mật¶
- Không đưa token truy cập vào fence, Markdown, image URL hoặc query string.
- 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.