Các sơ đồ kỹ thuật thường trở nên cũ kỹ vì việc chỉnh sửa chúng đòi hỏi phải tìm tệp thiết kế gốc, mở một ứng dụng riêng và xuất một hình ảnh khác.Mermaid có cách tiếp cận khác: sơ đồ được xác định dưới dạng văn bản và được lưu trữ bên cạnh tài liệu.
Để thêm Mermaid vào Markdown, hãy đặt định nghĩa sơ đồ bên trong khối mã có rào chắn với mermaid định danh ngôn ngữ.Sử dụng Xem trước sơ đồ Mermaid để hiển thị cú pháp cục bộ, sửa lỗi, sao chép hàng rào Markdown hoàn chỉnh hoặc tải xuống SVG.
Hướng dẫn này bắt đầu bằng một sơ đồ nhỏ và xây dựng theo trình tự, lớp, Gantt, sơ đồ tư duy và sơ đồ mối quan hệ thực thể.
Mermaid trong 30 giây
Khối Mermaid cơ bản trông như thế này:
```mermaid
flowchart LR
Draft --> Review
Review --> Publish
```
Hàng rào mở cho trình kết xuất tương thích biết rằng nội dung là cú pháp Mermaid. flowchart LR chọn sơ đồ được sắp xếp từ trái sang phải.Các dòng còn lại xác định các nút và kết nối.
Nếu đích không hỗ trợ Mermaid, người đọc thường sẽ thấy một khối mã thay vì sơ đồ.Dự phòng đó bảo tồn nguồn nhưng không thay thế cho việc kiểm tra tính tương thích trước khi xuất bản.
Tại sao nên sử dụng sơ đồ dựa trên văn bản?
Mermaid đặc biệt hữu ích khi sơ đồ:
- thuộc về tài liệu được kiểm soát theo phiên bản;
- thay đổi cùng với mã hoặc thủ tục;
- cần các khác biệt về yêu cầu kéo có ý nghĩa;
- sử dụng các hình dạng và mối quan hệ tiêu chuẩn;
- có thể chỉnh sửa được mà không cần tệp thiết kế độc quyền;
- phải được tạo lại theo chủ đề sáng và tối.
Nó ít phù hợp hơn với hình minh họa chi tiết, bố cục hoàn hảo đến từng pixel, chú thích tự do hoặc thiết kế trực quan yêu cầu vị trí thủ công chính xác.Trong những trường hợp đó, hãy sử dụng công cụ vẽ và xuất SVG hoặc hình ảnh có thể truy cập được.
Ví dụ 1: Lưu đồ
Sơ đồ mô tả một quy trình, quyết định hoặc quy tắc định tuyến.
```mermaid
flowchart TD
A[Choose a DOCX file] --> B{File valid?}
B -->|Yes| C[Convert to Markdown]
B -->|No| D[Show an error]
C --> E[Review the output]
E --> F[Copy or download]
```
Cú pháp chính:
TDcó nghĩa là từ trên xuống dưới.LRcó nghĩa là từ trái sang phải.[Text]tạo nút quy trình hình chữ nhật.{Text}tạo nút quyết định.-->tạo kết nối định hướng.-->|Label|thêm văn bản vào kết nối.
Sử dụng ID nút ngắn, ổn định như A or validate.Giữ nhãn hiển thị bên trong dấu ngoặc để việc thay đổi từ ngữ không yêu cầu thay đổi mọi kết nối.
Thêm đồ thị con
Các bước liên quan đến nhóm đồ thị con:
```mermaid
flowchart LR
subgraph Browser
Upload[Choose file] --> Convert[Convert locally]
end
subgraph Output
Preview[Preview Markdown] --> Save[Download file]
end
Convert --> Preview
```
Sử dụng sơ đồ con khi nhóm truyền đạt quyền sở hữu, ranh giới hệ thống hoặc giai đoạn.Đừng thêm một hộp chỉ để trang trí.
Ví dụ 2: Sơ đồ trình tự
Sơ đồ trình tự hiển thị các tương tác theo thứ tự thời gian.Chúng hoạt động tốt cho các cuộc gọi API, xác thực, quy trình làm việc của trình duyệt và hệ thống hướng sự kiện.
```mermaid
sequenceDiagram
autonumber
actor User
participant Browser
participant Converter
User->>Browser: Select DOCX file
Browser->>Converter: Pass local file data
Converter-->>Browser: Return Markdown
Browser-->>User: Show editable preview
```
Mũi tên thông thường:
->>gửi một tin nhắn chắc chắn.-->>gửi phản hồi nét đứt.participantkhai báo một hệ thống hoặc dịch vụ.actortuyên bố vai trò con người hoặc bên ngoài.autonumbergắn nhãn các tương tác theo thứ tự.
Tập trung vào một kịch bản.Một sơ đồ trình tự cố gắng hiển thị mọi phương án thay thế và mọi chức năng bên trong trở nên khó hiểu hơn mã.
Hiển thị đường dẫn thay thế
```mermaid
sequenceDiagram
participant Client
participant API
Client->>API: POST /documents
alt Valid request
API-->>Client: 201 Created
else Invalid request
API-->>Client: 400 Bad Request
end
```
Sử dụng alt, elsevà end cho các nhánh có ý nghĩa.Nếu ngành yêu cầu nhiều trang giải thích, hãy liên kết đến văn xuôi bên dưới sơ đồ.
Ví dụ 3: Sơ đồ lớp
Sơ đồ lớp mô tả các loại, thuộc tính, hoạt động, kế thừa và các mối quan hệ.
```mermaid
classDiagram
class Document {
+String name
+String content
+convert()
}
class MarkdownDocument {
+String frontmatter
+render()
}
Document <|-- MarkdownDocument
```
Ví dụ này nói rằng MarkdownDocument kế thừa từ Document.Sử dụng sơ đồ lớp cho mô hình khái niệm chứ không phải để thay thế tự động cho tài liệu tham khảo API hoàn chỉnh.
Sơ đồ lớp tốt loại bỏ những chi tiết không giúp người đọc hiểu được thiết kế.Hiển thị mọi trường riêng tư có thể biến sơ đồ thành một phiên bản mã nguồn khó tìm kiếm hơn.
Ví dụ 4: Biểu đồ Gantt
Biểu đồ Gantt hiển thị các nhiệm vụ theo thời gian.Chúng rất hữu ích cho các kế hoạch phát hành, di chuyển và các dự án tài liệu.
```mermaid
gantt
title Documentation migration
dateFormat YYYY-MM-DD
section Preparation
Inventory content :done, inventory, 2026-11-03, 3d
Define templates :done, templates, after inventory, 2d
section Migration
Convert documents :active, convert, 2026-11-08, 7d
Editorial review :review, after convert, 5d
section Publish
Final validation :validate, after review, 2d
```
Giữ ngày tháng rõ ràng và sử dụng ID nhiệm vụ khi một nhiệm vụ phụ thuộc vào một nhiệm vụ khác.Hãy nhớ rằng sơ đồ được lưu trữ trong tài liệu sẽ không tự cập nhật khi tiến độ dự án thực tế thay đổi.Chỉ định quyền sở hữu để giữ cho nó hiện tại.
Ví dụ 5: Sơ đồ tư duy
Bản đồ tư duy sắp xếp các ý tưởng xung quanh một chủ đề trung tâm.
```mermaid
mindmap
root((Markdown quality))
Structure
Headings
Lists
Tables
Accessibility
Alt text
Link text
Reading order
Publishing
GitHub
Obsidian
Documentation site
```
Bản đồ tư duy có hiệu quả nhất trong quá trình lập kế hoạch hoặc dưới dạng tổng quan cấp cao.Chúng ít hữu ích hơn cho các mối quan hệ chính xác vì cấu trúc cây có thể hàm ý thứ bậc trong đó các khái niệm thực tế chồng chéo lên nhau.
Ví dụ 6: Sơ đồ mối quan hệ thực thể
Sơ đồ ER mô tả các thực thể dữ liệu và mối quan hệ của chúng.
```mermaid
erDiagram
AUTHOR ||--o{ DOCUMENT : writes
DOCUMENT ||--o{ REVISION : contains
DOCUMENT }o--o{ TAG : uses
AUTHOR {
string id
string name
}
DOCUMENT {
string id
string title
datetime published_at
}
```
Sử dụng sơ đồ ER để giải thích mô hình và lược đồ hoặc tệp di chuyển để xác định việc triển khai.Sơ đồ có thể bỏ qua các chỉ mục, ràng buộc và các trường không liên quan đến phần giải thích hiện tại.
Xem trước Mermaid Trước khi xuất bản
Viết sơ đồ trực tiếp trong tài liệu Markdown dài khiến khó phân biệt được lỗi cú pháp.Vòng lặp xem trước tập trung nhanh hơn:
- Mở ra. Xem trước sơ đồ Mermaid.
- Chỉ dán định nghĩa sơ đồ, không có hàng rào mã bên ngoài.
- Hiển thị sơ đồ.
- Đọc bất kỳ lỗi cú pháp nào và sửa vùng được tham chiếu.
- Sao chép hàng rào Markdown được tạo.
- Tải xuống SVG khi đích đến cần nội dung tĩnh.
- Kiểm tra Markdown cuối cùng trên nền tảng thực của nó.
Bản xem trước hiển thị trong trình duyệt của bạn với cấu hình bảo mật nghiêm ngặt.Lệnh gọi lại sơ đồ và các hành vi tương tác khác có thể bị tắt ngay cả khi bản cài đặt Mermaid khác cho phép chúng.Hành vi bảo thủ đó phù hợp với một công cụ xem trước chung.
Các lỗi Mermaid thường gặp
Loại sơ đồ bị thiếu
Không chính xác:
A --> B
Đúng:
flowchart LR
A --> B
Dòng đầu tiên xác định ngữ pháp sơ đồ.
Dấu câu trong phân tích cú pháp ngắt nhãn
Trích dẫn các nhãn phức tạp:
flowchart LR
A["Parse input: DOCX, HTML, or text"] --> B["Create Markdown"]
Điều này đặc biệt hữu ích cho các dấu ngoặc đơn, dấu câu và nhãn giống với cú pháp.
Một Word dành riêng được sử dụng bất ngờ
Mermaid ngữ pháp có từ khóa.Tài liệu lưu đồ chính thức đặc biệt cảnh báo rằng chữ thường end có thể phá vỡ sơ đồ.Viết hoa hoặc đặt văn bản hiển thị bên trong nhãn nút được trích dẫn:
flowchart LR
Start --> Finish["End"]
Hàng rào mã không chính xác
Mã định danh ngôn ngữ thuộc về ngay sau dấu backticks mở đầu:
```mermaid
flowchart LR
A --> B
```
Không thụt lề hàng rào hoàn chỉnh trừ khi cú pháp Markdown xung quanh yêu cầu điều đó.
Nó hoạt động trên một nền tảng nhưng không hoạt động trên nền tảng khác
Mermaid phát triển và các nền tảng có thể sử dụng các trình kết xuất, phiên bản, cài đặt bảo mật và loại sơ đồ được bật khác nhau.Tính năng cú pháp được bản phát hành Mermaid mới nhất hỗ trợ có thể bị lỗi trên nền tảng sử dụng cách triển khai khác hoặc phiên bản cũ hơn.
Ưu tiên cú pháp được hỗ trợ rộng rãi cho các tài liệu di chuyển giữa các nền tảng.Kiểm tra các hình dạng, chủ đề, chỉ thị nâng cao và các loại sơ đồ mới hơn ở mọi đích đến được yêu cầu.
Khả năng tương thích nền tảng
Khả năng tương thích nên được kiểm tra thay vì giả định:
| Nền tảng | Cách tiếp cận được ghi chép hiện tại | Lưu ý quan trọng |
|---|---|---|
| GitHub | Sử dụng hàng rào mermaid block | GitHub hiển thị tài liệu trong tệp Markdown, sự cố, thảo luận, yêu cầu kéo và wiki |
| GitLab | Sử dụng khối mã Mermaid trong GitLab Flavored Markdown | GitLab ghi lại phiên bản Mermaid được hỗ trợ;cài đặt tự quản lý có thể khác nhau |
| Obsidian | Sử dụng hàng rào mermaid trong ghi chú | Obsidian có thể thay đổi giữa các bản phát hành |
| Chất liệu cho MkDocs | Định cấu hình hàng rào tùy chỉnh Mermaid | Tích hợp chủ đề gốc yêu cầu phải có tài liệu pymdownx.superfences configuration |
| Trình phân tích cú pháp Markdown chung | Thường chỉ hiển thị mã | Mermaid thường yêu cầu plugin xây dựng hoặc tích hợp JavaScript |
Kiểm tra tài liệu chính thức hiện tại trước khi dựa vào tính năng mới hơn:
- GitHub: Tạo sơ đồ
- Hương vị GitLab Markdown
- Obsidian: Cú pháp định dạng nâng cao
- Tài liệu cho MkDocs: Sơ đồ
- Mermaid
Đối với trang tài liệu mà bạn kiểm soát, hãy ghim phiên bản phụ thuộc Mermaid và kiểm tra các bản nâng cấp.Nếu không, một thay đổi nhỏ về cú pháp có thể làm thay đổi sơ đồ trên toàn bộ trang web.
Mermaid và Khả năng truy cập
SVG được hiển thị không tự động truyền đạt ý nghĩa của nó tới mọi người đọc.Hãy coi sơ đồ như một bản tóm tắt trực quan và đưa ra lời giải thích tương đương bằng văn xuôi gần đó.
Đối với sơ đồ chuyển đổi trước đó, hãy thêm văn bản như:
Người dùng chọn tệp DOCX.Các tệp hợp lệ được chuyển đổi cục bộ và hiển thị để xem xét;tập tin không hợp lệ tạo ra một lỗi.Sau đó, người dùng có thể sao chép hoặc tải xuống Markdown đã được đánh giá.
Thực tiễn về khả năng tiếp cận:
- giới thiệu những gì sơ đồ giải thích;
- tóm tắt kết luận sau các sơ đồ phức tạp;
- không mã hóa ý nghĩa chỉ bằng màu sắc;
- sử dụng nhãn có thể đọc được thay vì viết tắt nội bộ;
- duy trì đủ độ tương phản trong các chủ đề sáng và tối;
- tránh các sơ đồ yêu cầu tương tác chuột chính xác;
- cung cấp văn bản hoặc bảng thay thế cho thông tin cần thiết;
- xuất SVG một cách cẩn thận khi tệp tĩnh phải mang tên có thể truy cập được.
Mã nguồn hữu ích cho tác giả nhưng không nhất thiết phải là văn bản thay thế tốt cho người đọc.
Thiết kế sơ đồ dễ đọc
Giữ một mục đích cho mỗi sơ đồ
Sơ đồ phải trả lời câu hỏi như “Điều gì xảy ra sau khi yêu cầu không thành công?”hoặc “Dịch vụ nào sở hữu từng kho dữ liệu?”Nếu nó cố gắng giải thích toàn bộ hệ thống, hãy tách nó ra.
Thích nhãn ngắn
Đưa ra lời giải thích chi tiết bằng văn xuôi.Nhãn dài buộc các nút hẹp, ngắt dòng khó xử và sơ đồ lớn trên màn hình thiết bị di động.
Sử dụng hướng dẫn có chủ ý
Luồng từ trái sang phải hoạt động tốt đối với các quy trình ngắn và đường dẫn yêu cầu.Luồng từ trên xuống dưới thường phù hợp với màn hình hẹp hơn.Xem trước cả hai trước khi cam kết.
Giới hạn kiểu dáng trực quan
Màu tùy chỉnh có thể xung đột với chế độ tối hoặc chủ đề nền tảng.Bắt đầu với các giá trị mặc định của trình kết xuất.Chỉ thêm kiểu khi chúng truyền đạt ý nghĩa và vẫn có thể đọc được trong tất cả các chủ đề được yêu cầu.
Giữ nguồn gần lời giải thích của nó
Lưu trữ khối Mermaid trong cùng một tệp Markdown khi có thể.Điều đó làm cho văn xuôi và sơ đồ thay đổi cùng nhau trong một lần ôn lại.
Mermaid so với hình ảnh tĩnh
Chọn Mermaid khi:
- sơ đồ thay đổi thường xuyên;
- khác biệt về nguồn có giá trị;
- bố cục sử dụng các loại sơ đồ tiêu chuẩn;
- nền tảng xuất bản hiển thị Mermaid một cách đáng tin cậy.
Chọn SVG hoặc PNG khi:
- thiết kế yêu cầu bố cục thủ công chính xác;
- đích không hiển thị Mermaid;
- hình thức chính xác phải được cố định;
- chia sẻ bên ngoài yêu cầu một nội dung độc lập.
Một kết hợp hữu ích là duy trì nguồn Mermaid và xuất SVG cho các đích không thể hiển thị nó.Giữ nguồn bên cạnh nội dung đã xuất và ghi lại cách tạo lại nó.
Sử dụng Markdown sang hình ảnh dành cho nội dung Markdown được hiển thị có thể chia sẻ hoặc tải xuống SVG trực tiếp từ Xem trước sơ đồ Mermaid khi bản thân sơ đồ là nội dung.
FAQ
Mermaid có phải là một phần của tiêu chuẩn Markdown không?
Không. Có hàng rào mermaid là một phần mở rộng được các ứng dụng và hệ thống xây dựng tương thích công nhận.Trình phân tích cú pháp Markdown cơ bản có thể hiển thị nó dưới dạng mã thông thường.
GitHub có hiển thị sơ đồ Mermaid không?
Có.Tài liệu của GitHub mô tả kết xuất Mermaid trong tệp Markdown và một số nền tảng cộng tác.Kiểm tra cú pháp mới hơn vì GitHub kiểm soát cài đặt bảo mật và trình kết xuất được triển khai.
Tôi có thể sử dụng Mermaid trong Obsidian không?
Obsidian Các khối sơ đồ có hàng rào kiểu Mermaid trong ghi chú.Hỗ trợ tính năng có thể thay đổi với trình kết xuất của ứng dụng, vì vậy hãy xác minh các loại sơ đồ phức tạp hoặc mới được giới thiệu trong phiên bản đã cài đặt của bạn.
Mermaid có thể thay thế tài liệu kiến trúc không?
Không. Sơ đồ là một góc nhìn của hệ thống.Ghép nối nó với các quyết định, quyền sở hữu, ràng buộc, hành vi lỗi và liên kết đến các giao diện hoặc lược đồ có thẩm quyền.
Tại sao sơ đồ của tôi hiển thị khác ở chế độ tối?
Nền tảng có thể áp dụng các chủ đề Mermaid, biến CSS, phông chữ và hình nền khác nhau.Tránh các màu được mã hóa cứng cho đến khi bạn đã thử nghiệm cả hai chủ đề.
Tôi có nên cam kết các tệp SVG đã xuất không?
Cam kết SVG khi đích xuất bản cần nội dung tĩnh hoặc kết quả được hiển thị phải ổn định.Đồng thời giữ lại nguồn Mermaid và quy trình tái tạo được ghi lại để ngăn hai phiên bản bị trôi.
Mermaid có an toàn cho các sơ đồ bí mật không?
Tính bảo mật phụ thuộc vào quy trình biên tập và xuất bản.Bản xem trước của WordToMD hiển thị sơ đồ trong trình duyệt của bạn, nhưng việc xuất bản Markdown hoặc SVG lên kho lưu trữ hoặc trang web phải tuân theo các biện pháp kiểm soát truy cập của đích đó.
Kết luận
Mermaid giúp duy trì sơ đồ vì nguồn tồn tại với Markdown.Bắt đầu với một khối có hàng rào nhỏ, chọn loại sơ đồ phù hợp với câu hỏi, xem trước cú pháp và kiểm tra nó trong trình kết xuất cuối cùng.Sử dụng văn xuôi để giải thích ý nghĩa thiết yếu và xuất SVG khi đích đến cần nội dung tĩnh.
Hãy thử các ví dụ trong Xem trước sơ đồ Mermaid, hãy chỉnh sửa tài liệu xung quanh trong Markdown Trình soạn thảovà giữ cho sơ đồ đủ tập trung để người đóng góp trong tương lai có thể hiểu và cập nhật nó mà không cần vẽ lại toàn bộ trang.