mermaid markdown diagrams flowchart documentation

Mermaid trong Markdown: tạo lưu đồ, sơ đồ tuần tự và nhiều hơn nữa

Tìm hiểu cú pháp Mermaid cho Markdown với các ví dụ về sơ đồ, trình tự, lớp, Gantt, sơ đồ tư duy và sơ đồ ER sẵn sàng sao chép, cùng với hướng dẫn xem trước, xuất, tương thích và trợ năng.

W
WordToMD Đội
·

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:

  • TD có nghĩa là từ trên xuống dưới.
  • LR có 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.
  • participant khai báo một hệ thống hoặc dịch vụ.
  • actor tuyên bố vai trò con người hoặc bên ngoài.
  • autonumber gắ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:

  1. Mở ra. Xem trước sơ đồ Mermaid.
  2. Chỉ dán định nghĩa sơ đồ, không có hàng rào mã bên ngoài.
  3. Hiển thị sơ đồ.
  4. Đọc bất kỳ lỗi cú pháp nào và sửa vùng được tham chiếu.
  5. Sao chép hàng rào Markdown được tạo.
  6. Tải xuống SVG khi đích đến cần nội dung tĩnh.
  7. 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ảngCách tiếp cận được ghi chép hiện tạiLưu ý quan trọng
GitHubSử dụng hàng rào mermaid blockGitHub 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
GitLabSử dụng khối mã Mermaid trong GitLab Flavored MarkdownGitLab ghi lại phiên bản Mermaid được hỗ trợ;cài đặt tự quản lý có thể khác nhau
ObsidianSử 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 MermaidTí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 chungThườ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:

Đố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.