GitLab MR Browser Extension¶
Extension dành cho reviewer muốn đọc Markdown Before/After và so sánh diagram ngay trong tab Changes của GitLab merge request.
Trước khi bắt đầu¶
Bạn cần:
- Trình duyệt Chromium.
- Package extension do dự án phát hành.
- Quyền mở merge request trên GitLab HTTPS.
- Địa chỉ Krokup và token truy cập.
Nếu dùng package unpacked, giải nén package, mở trang quản lý extension, bật Developer mode rồi chọn Load unpacked.
Mở extension options:
- Nhập địa chỉ HTTPS của Krokup, không kèm endpoint path.
- Nhập token truy cập.
- Chọn Test.
- Lưu khi kiểm tra thành công.
Token được lưu trong vùng dữ liệu riêng của extension và chỉ được dùng khi gọi Krokup. Extension không yêu cầu GitLab personal access token và không chèn token vào trang GitLab.
Review một merge request¶
- Đăng nhập GitLab và mở merge request.
- Chuyển tới tab Changes.
- Bấm biểu tượng Krokup để cho phép extension chạy trên tab hiện tại.
- Chọn View preview before/after để đọc toàn bộ file Markdown ở hai phía.
- Tại diagram thay đổi, chọn View diagram diff.
- Với diagram chỉ có ở một phía, chọn View added hoặc View removed.
- Chọn cách so sánh phù hợp rồi đóng panel khi hoàn tất.
Trong View preview before/after, tùy chọn Sync scroll: On được bật mặc định. Khi
cuộn một phía, phía còn lại bám theo heading và diagram tương ứng. Extension dùng kết quả
ghép cặp diagram hiện có, ưu tiên {id=...}; nếu không có mốc chung thì đồng bộ theo tỷ lệ
cuộn của toàn tài liệu. Chọn Sync scroll: Off khi cần xem hai vị trí độc lập.
Kết quả mong đợi: nút xem xuất hiện gần fence thay đổi; extension chỉ gửi mã sơ đồ tới Krokup khi bạn mở bảng so sánh.
Tab mới hoặc một địa chỉ GitLab khác cần được kích hoạt lại bằng biểu tượng extension. Quyền này là tạm thời cho tab hiện tại.
Chọn cách so sánh¶
| Chế độ | Cách hiển thị | Phù hợp khi |
|---|---|---|
| Before / After | Chỉ xem một phiên bản | Cần kiểm tra nhanh mã đã thêm hoặc xóa |
| Side by side | Hai sơ đồ đặt cạnh nhau | Cần so sánh cấu trúc tổng thể |
| Onion skin | Hai hình chồng lên nhau | Cần thấy vị trí hoặc hình dạng thay đổi nhỏ |
Onion skin hữu ích nhất khi hai sơ đồ có kích thước gần nhau. Nếu hình chênh lệch lớn, dùng Side by side để tránh hiểu nhầm.
Giúp extension ghép đúng diagram¶
Thêm id vào khối {...} trên dòng mở fence để extension nhận ra cùng một sơ
đồ ở hai phiên bản, kể cả khi bạn đổi vị trí, title hoặc loại sơ đồ:
```plantuml {id=checkout-sequence} title="Checkout sequence"
@startuml
Customer -> Checkout: Pay
@enduml
```
ID phải dài từ 1 đến 64 ký tự, bắt đầu bằng chữ hoặc số và chỉ chứa chữ thường,
số, ., _ hoặc -. Mỗi ID chỉ được xuất hiện một lần trong cùng file. Hãy giữ
nguyên ID khi sửa mã, đổi title, di chuyển fence hoặc đổi loại sơ đồ.
Extension hiển thị cảnh báo nếu ID sai định dạng, bị trùng hoặc chỉ có ở một
phía. Tài liệu cũ không có id vẫn được ghép theo title, loại sơ đồ và
thứ tự xuất hiện, nhưng có thể kém chính xác khi nhiều sơ đồ giống nhau bị đổi
vị trí. Hai ID hợp lệ khác nhau không được ghép thành một cặp.
title tiếp tục được dùng làm tên hiển thị. id chỉ giúp review thay đổi;
extension loại riêng id khi so sánh nội dung, còn rendering server bỏ qua nó
và vẫn áp dụng các render param hợp lệ trong cùng {...}.
Cú pháp cũ diagram-id=... ở ngoài {...} không còn được nhận diện.
Dùng options trong diagram¶
Extension áp dụng các tùy chọn trong {...} bằng cách tạo một directive
%%krokup trước khi gửi source. Có thể đặt ID và render param cùng chỗ:
```mermaid {id=checkout-flow theme=dark scale=1.5} title="Checkout flow"
flowchart LR
Cart --> Payment
```
Nếu fence không có {...}, directive %%krokup trong phần thân vẫn được dùng
làm fallback. Xem Diagram Customization để biết chi
tiết.
Quyền truy cập và dữ liệu¶
- Extension chỉ chạy trên tab GitLab mà bạn kích hoạt bằng biểu tượng Krokup.
- Extension dùng phiên đăng nhập GitLab hiện tại để đọc nội dung bạn đã có quyền xem; không yêu cầu personal access token.
- Token Krokup không được chèn vào trang GitLab.
- Mã sơ đồ chỉ được gửi để render khi reviewer mở bảng so sánh.
- Quyền sử dụng Pydia vẫn phụ thuộc vào cấu hình của hệ thống.
Xóa token trong options trước khi bàn giao máy hoặc gỡ extension.
Xử lý sự cố¶
| Hiện tượng | Cách xử lý |
|---|---|
| Không thấy nút xem | Mở tab Changes, bấm lại biểu tượng extension và tải lại trang nếu cần |
| Markdown preview lỗi | Đăng nhập lại GitLab rồi tải lại merge request |
| Hai Markdown preview cuộn không cùng nhau | Kiểm tra Sync scroll đang ở trạng thái On; thêm {id=...} nếu diagram bị di chuyển hoặc đổi loại |
| Diagram không ghép đúng | Thêm {id=...} duy nhất và giữ nguyên ID ở hai phiên bản |
| Cảnh báo ID sai hoặc trùng | Dùng 1–64 ký tự hợp lệ và bảo đảm mỗi ID chỉ xuất hiện một lần trong file |
| Cảnh báo ID chỉ có ở một phía | Thêm cùng {id=...} vào phiên bản còn lại nếu đó là cùng một sơ đồ |
401 từ Krokup |
Mở options, nhập lại token và chạy Test |
| Không kết nối Krokup | Kiểm tra địa chỉ HTTPS; nếu Test vẫn lỗi, liên hệ quản trị viên |
| Fence params không có tác dụng | Kiểm tra cú pháp {key=value} và cảnh báo X-Diagram-Warnings |
| Onion skin khó đọc | Chuyển sang Side by side |
Thông tin build, test, manifest và invariant dành cho contributor nằm trong Developer Guide.