तकनीकी आरेख अक्सर पुराने हो जाते हैं क्योंकि उन्हें संपादित करने के लिए मूल डिज़ाइन फ़ाइल ढूंढने, एक अलग एप्लिकेशन खोलने और दूसरी छवि निर्यात करने की आवश्यकता होती है।Mermaid एक अलग दृष्टिकोण अपनाता है: आरेख को पाठ के रूप में परिभाषित किया जाता है और दस्तावेज़ के बगल में संग्रहीत किया जाता है।
Mermaid को Markdown में जोड़ने के लिए, आरेख परिभाषा को एक बाड़े वाले कोड ब्लॉक के अंदर रखें mermaid भाषा पहचानकर्ता.का प्रयोग करें Mermaid डायग्राम पूर्वावलोकन सिंटैक्स को स्थानीय रूप से प्रस्तुत करने, त्रुटियों को ठीक करने, संपूर्ण Markdown बाड़ की प्रतिलिपि बनाने, या एक एसवीजी डाउनलोड करने के लिए।
यह मार्गदर्शिका एक छोटे फ़्लोचार्ट से शुरू होती है और अनुक्रम, वर्ग, गैंट, माइंड मैप और इकाई-संबंध आरेखों की ओर बढ़ती है।
Mermaid 30 सेकंड में
एक बुनियादी Mermaid ब्लॉक इस तरह दिखता है:
```mermaid
flowchart LR
Draft --> Review
Review --> Publish
```
प्रारंभिक बाड़ एक संगत रेंडरर को बताता है कि सामग्री Mermaid सिंटैक्स है। flowchart LR बाएँ से दाएँ व्यवस्थित फ़्लोचार्ट का चयन करता है।शेष पंक्तियाँ नोड्स और कनेक्शन को परिभाषित करती हैं।
यदि गंतव्य Mermaid का समर्थन नहीं करता है, तो पाठकों को आमतौर पर आरेख के बजाय एक कोड ब्लॉक दिखाई देगा।वह फ़ॉलबैक स्रोत को सुरक्षित रखता है, लेकिन यह प्रकाशन से पहले संगतता की जाँच के लिए प्रतिस्थापन नहीं है।
टेक्स्ट-आधारित आरेखों का उपयोग क्यों करें?
Mermaid विशेष रूप से उपयोगी है जब एक आरेख:
- संस्करण-नियंत्रित दस्तावेज़ से संबंधित है;
- कोड या प्रक्रियाओं के साथ परिवर्तन;
- को सार्थक पुल-अनुरोध अंतर की आवश्यकता है;
- मानक आकृतियों और संबंधों का उपयोग करता है;
- मालिकाना डिज़ाइन फ़ाइल के बिना संपादन योग्य होना चाहिए;
- को प्रकाश और अंधेरे विषयों में पुनर्जीवित किया जाना चाहिए।
यह विस्तृत चित्रण, पिक्सेल-परिपूर्ण लेआउट, फ्रीहैंड एनोटेशन, या सटीक मैन्युअल प्लेसमेंट की आवश्यकता वाले दृश्य डिज़ाइन के लिए कम उपयुक्त है।उन मामलों में, एक ड्राइंग टूल का उपयोग करें और एक सुलभ एसवीजी या छवि निर्यात करें।
उदाहरण 1: एक फ़्लोचार्ट
फ़्लोचार्ट एक प्रक्रिया, निर्णय या रूटिंग नियम का वर्णन करते हैं।
```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]
```
मुख्य सिंटैक्स:
TDका अर्थ है ऊपर से नीचे तक।LRका अर्थ है बाएँ से दाएँ।[Text]एक आयताकार प्रक्रिया नोड बनाता है।{Text}एक निर्णय नोड बनाता है।-->एक दिशात्मक संबंध बनाता है.-->|Label|कनेक्शन में टेक्स्ट जोड़ता है।
जैसे स्थिर, लघु नोड आईडी का उपयोग करें A or validate.दृश्यमान लेबल को कोष्ठक के अंदर रखें ताकि शब्दों को बदलने के लिए हर कनेक्शन को बदलने की आवश्यकता न हो।
एक सबग्राफ जोड़ें
सबग्राफ़ समूह संबंधित चरण:
```mermaid
flowchart LR
subgraph Browser
Upload[Choose file] --> Convert[Convert locally]
end
subgraph Output
Preview[Preview Markdown] --> Save[Download file]
end
Convert --> Preview
```
जब समूह स्वामित्व, सिस्टम सीमाओं या चरणों का संचार करता है तो सबग्राफ का उपयोग करें।केवल सजावट के लिए एक बॉक्स न जोड़ें।
उदाहरण 2: एक अनुक्रम आरेख
अनुक्रम आरेख समय क्रम में इंटरैक्शन दिखाते हैं।वे API कॉल, प्रमाणीकरण, ब्राउज़र वर्कफ़्लो और इवेंट-संचालित सिस्टम के लिए अच्छा काम करते हैं।
```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
```
सामान्य तीर:
->>एक ठोस संदेश भेजता है।-->>एक धराशायी प्रतिक्रिया भेजता है।participantएक सिस्टम या सेवा की घोषणा करता है।actorएक मानवीय या बाहरी भूमिका की घोषणा करता है।autonumberइंटरैक्शन को क्रम में लेबल करता है।
एक परिदृश्य पर ध्यान दें.एक अनुक्रम आरेख जो प्रत्येक विकल्प और प्रत्येक आंतरिक फ़ंक्शन को दिखाने का प्रयास करता है, कोड की तुलना में समझना कठिन हो जाता है।
कोई वैकल्पिक मार्ग दिखाएँ
```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
```
उपयोग alt, else, और end ।यदि शाखा को स्पष्टीकरण के कई पृष्ठों की आवश्यकता है, तो आरेख के नीचे गद्य का लिंक दें।
उदाहरण 3: एक वर्ग आरेख
वर्ग आरेख प्रकार, गुण, संचालन, वंशानुक्रम और संबंधों का वर्णन करते हैं।
```mermaid
classDiagram
class Document {
+String name
+String content
+convert()
}
class MarkdownDocument {
+String frontmatter
+render()
}
Document <|-- MarkdownDocument
```
यह उदाहरण बताता है कि MarkdownDocument से विरासत में मिला है Document.एक वैचारिक मॉडल के लिए वर्ग आरेख का उपयोग करें, न कि संपूर्ण API संदर्भ दस्तावेज़ के स्वचालित प्रतिस्थापन के रूप में।
अच्छे वर्ग आरेख विवरण छोड़ देते हैं जो पाठक को डिज़ाइन को समझने में मदद नहीं करते हैं।प्रत्येक निजी फ़ील्ड को दिखाने से आरेख स्रोत कोड के कम खोजने योग्य संस्करण में बदल सकता है।
उदाहरण 4: एक गैंट चार्ट
गैंट चार्ट समय-समय पर कार्य दिखाते हैं।वे रिलीज़ योजनाओं, माइग्रेशन और दस्तावेज़ीकरण परियोजनाओं के लिए उपयोगी हैं।
```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
```
तारीखें स्पष्ट रखें और जब एक कार्य दूसरे पर निर्भर हो तो कार्य आईडी का उपयोग करें।याद रखें कि वास्तविक प्रोजेक्ट शेड्यूल में बदलाव होने पर दस्तावेज़ में संग्रहीत आरेख स्वयं अपडेट नहीं होगा।इसे चालू रखने के लिए स्वामित्व सौंपें।
उदाहरण 5: एक माइंड मैप
माइंड मैप एक केंद्रीय विषय के आसपास विचारों को व्यवस्थित करते हैं।
```mermaid
mindmap
root((Markdown quality))
Structure
Headings
Lists
Tables
Accessibility
Alt text
Link text
Reading order
Publishing
GitHub
Obsidian
Documentation site
```
योजना बनाते समय या उच्च-स्तरीय अवलोकन के रूप में माइंड मैप सबसे प्रभावी होते हैं।वे सटीक संबंधों के लिए कम उपयोगी हैं क्योंकि वृक्ष संरचना पदानुक्रम का संकेत दे सकती है जहां वास्तविक अवधारणाएं ओवरलैप होती हैं।
उदाहरण 6: एक इकाई-संबंध आरेख
ईआर आरेख डेटा इकाइयों और उनके संबंधों का वर्णन करते हैं।
```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
}
```
मॉडल को समझाने के लिए एक ईआर आरेख और कार्यान्वयन को परिभाषित करने के लिए एक स्कीमा या माइग्रेशन फ़ाइल का उपयोग करें।एक आरेख उन अनुक्रमणिकाओं, बाधाओं और फ़ील्ड को छोड़ सकता है जो वर्तमान स्पष्टीकरण के लिए प्रासंगिक नहीं हैं।
प्रकाशन से पहले पूर्वावलोकन Mermaid
लंबे Markdown दस्तावेज़ में सीधे आरेख लिखने से वाक्यविन्यास त्रुटियों को अलग करना मुश्किल हो जाता है।एक केंद्रित पूर्वावलोकन लूप तेज़ है:
- खोलें Mermaid डायग्राम पूर्वावलोकन.
- बाहरी कोड बाड़ के बिना, केवल आरेख परिभाषा चिपकाएँ।
- आरेख प्रस्तुत करें.
- किसी भी सिंटैक्स त्रुटि को पढ़ें और संदर्भित क्षेत्र को ठीक करें।
- जनरेट की गई बाड़ Markdown की प्रतिलिपि बनाएँ।
- जब गंतव्य को स्थिर संपत्ति की आवश्यकता हो तो एसवीजी डाउनलोड करें।
- अंतिम Markdown का उसके वास्तविक प्लेटफ़ॉर्म में परीक्षण करें।
पूर्वावलोकन आपके ब्राउज़र में सख्त सुरक्षा कॉन्फ़िगरेशन के साथ प्रस्तुत होता है।आरेख कॉलबैक और अन्य इंटरैक्टिव व्यवहार अक्षम किए जा सकते हैं, भले ही कोई अन्य Mermaid इंस्टॉलेशन उन्हें अनुमति देता हो।वह रूढ़िवादी व्यवहार सामान्य पूर्वावलोकन उपकरण के लिए उपयुक्त है।
सामान्य Mermaid त्रुटियाँ
आरेख प्रकार गुम है
गलत:
A --> B
सही:
flowchart LR
A --> B
पहली पंक्ति आरेख व्याकरण की पहचान करती है।
लेबल में विराम चिह्न पार्सिंग को तोड़ता है
जटिल लेबल उद्धृत करें:
flowchart LR
A["Parse input: DOCX, HTML, or text"] --> B["Create Markdown"]
यह विशेष रूप से कोष्ठक, विराम चिह्न और वाक्यविन्यास से मिलते जुलते लेबल के लिए उपयोगी है।
एक आरक्षित Word का उपयोग अप्रत्याशित रूप से किया जाता है
Mermaid व्याकरण में कीवर्ड होते हैं।आधिकारिक फ़्लोचार्ट दस्तावेज़ विशेष रूप से उस लोअरकेस को चेतावनी देता है end फ़्लोचार्ट को तोड़ सकता है।इसे बड़े अक्षरों में लिखें या दृश्यमान पाठ को उद्धृत नोड लेबल के अंदर रखें:
flowchart LR
Start --> Finish["End"]
कोड बाड़ गलत है
भाषा पहचानकर्ता शुरुआती बैकटिक्स के तुरंत बाद का है:
```mermaid
flowchart LR
A --> B
```
पूरी बाड़ को इंडेंट न करें जब तक कि आसपास के Markdown सिंटैक्स की आवश्यकता न हो।
यह एक प्लेटफ़ॉर्म पर काम करता है लेकिन दूसरे में नहीं
Mermaid विकसित होता है, और प्लेटफ़ॉर्म विभिन्न रेंडरर, संस्करण, सुरक्षा सेटिंग्स और सक्षम आरेख प्रकारों का उपयोग कर सकते हैं।नवीनतम Mermaid रिलीज़ द्वारा समर्थित एक सिंटैक्स सुविधा किसी अन्य कार्यान्वयन या पुराने संस्करण का उपयोग करने वाले प्लेटफ़ॉर्म में विफल हो सकती है।
प्लेटफ़ॉर्म के बीच चलने वाले दस्तावेज़ों के लिए व्यापक रूप से समर्थित सिंटैक्स को प्राथमिकता दें।प्रत्येक आवश्यक गंतव्य में उन्नत आकृतियों, विषयों, निर्देशों और नए आरेख प्रकारों का परीक्षण करें।
प्लेटफ़ॉर्म संगतता
अनुकूलता को मानने के बजाय उसका परीक्षण किया जाना चाहिए:
| मंच | वर्तमान प्रलेखित दृष्टिकोण | महत्वपूर्ण नोट |
|---|---|---|
| GitHub | बाड़ का उपयोग करें mermaid block | GitHub दस्तावेज़ Markdown फ़ाइलों, मुद्दों, चर्चाओं, पुल अनुरोधों और विकी में प्रस्तुत होते हैं |
| GitLab | GitLab फ्लेवर्ड Markdown में Mermaid कोड ब्लॉक का उपयोग करें | GitLab अपने समर्थित Mermaid संस्करण का दस्तावेजीकरण करता है;स्व-प्रबंधित संस्थापन भिन्न हो सकते हैं |
| Obsidian | बाड़ का उपयोग करें mermaid नोट में ब्लॉक करें | Obsidian का रेंडरर और समर्थित सुविधाएँ रिलीज़ के बीच बदल सकती हैं |
| MkDocs के लिए सामग्री | एक Mermaid कस्टम बाड़ कॉन्फ़िगर करें | मूल विषय एकीकरण के लिए दस्तावेजीकरण की आवश्यकता है pymdownx.superfences configuration |
| जेनेरिक Markdown पार्सर | अक्सर केवल कोड प्रदर्शित करता है | Mermaid रेंडरिंग के लिए आमतौर पर JavaScript एकीकरण या बिल्ड प्लगइन की आवश्यकता होती है |
किसी नई सुविधा पर भरोसा करने से पहले वर्तमान आधिकारिक दस्तावेज़ की जाँच करें:
- GitHub: आरेख बनाना
- GitLab फ्लेवर्ड Markdown
- Obsidian: उन्नत स्वरूपण सिंटैक्स
- MkDocs के लिए सामग्री: आरेख
- Mermaid सिंटैक्स संदर्भ
आपके द्वारा नियंत्रित दस्तावेज़ीकरण साइट के लिए, Mermaid निर्भरता संस्करण को पिन करें और अपग्रेड का परीक्षण करें।अन्यथा, एक मामूली वाक्यविन्यास परिवर्तन पूरी साइट पर आरेखों को बदल सकता है।
Mermaid और अभिगम्यता
एक प्रस्तुत एसवीजी स्वचालित रूप से प्रत्येक पाठक को अपना अर्थ नहीं बताता है।आरेख को एक दृश्य सारांश के रूप में मानें और निकटवर्ती गद्य में समकक्ष स्पष्टीकरण प्रदान करें।
पिछले रूपांतरण फ़्लोचार्ट के लिए, जैसे पाठ जोड़ें:
उपयोगकर्ता एक DOCX फ़ाइल का चयन करता है।वैध फ़ाइलें स्थानीय रूप से परिवर्तित की जाती हैं और समीक्षा के लिए प्रदर्शित की जाती हैं;अमान्य फ़ाइलें त्रुटि उत्पन्न करती हैं.इसके बाद उपयोगकर्ता समीक्षा की गई Markdown को कॉपी या डाउनलोड कर सकता है।
अभिगम्यता प्रथाएँ:
- आरेख क्या समझाता है उसका परिचय दें;
- जटिल आरेखों के बाद निष्कर्ष को संक्षेप में प्रस्तुत करें;
- केवल रंग के साथ अर्थ को कूटबद्ध न करें;
- आंतरिक संक्षिप्ताक्षरों के बजाय पठनीय लेबल का उपयोग करें;
- प्रकाश और अंधेरे विषयों में पर्याप्त कंट्रास्ट बनाए रखें;
- उन आरेखों से बचें जिनके लिए सटीक माउस इंटरैक्शन की आवश्यकता होती है;
- आवश्यक जानकारी के लिए एक पाठ या तालिका विकल्प प्रदान करें;
- एसवीजी को सावधानी से निर्यात करें जब स्थिर फ़ाइल में एक सुलभ नाम होना चाहिए।
स्रोत कोड लेखकों के लिए उपयोगी है, लेकिन जरूरी नहीं कि यह पाठकों के लिए एक अच्छा पाठ विकल्प हो।
ऐसे आरेख डिज़ाइन करना जो पढ़ने योग्य रहें
प्रति आरेख एक उद्देश्य रखें
एक आरेख को एक प्रश्न का उत्तर देना चाहिए जैसे "अनुरोध विफल होने के बाद क्या होता है?"या "कौन सी सेवा प्रत्येक डेटा स्टोर का मालिक है?"यदि यह संपूर्ण प्रणाली को समझाने का प्रयास करता है, तो इसे विभाजित करें।
छोटे लेबल को प्राथमिकता दें
गद्य में विस्तृत व्याख्याएँ रखें।लंबे लेबल मोबाइल स्क्रीन पर संकीर्ण नोड्स, अजीब लाइन रैपिंग और बड़े आरेखों को बाध्य करते हैं।
जानबूझकर दिशा का प्रयोग करें
बाएँ से दाएँ प्रवाह छोटी प्रक्रियाओं और अनुरोध पथों के लिए अच्छा काम करता है।ऊपर से नीचे का प्रवाह अक्सर संकीर्ण स्क्रीन पर बेहतर फिट बैठता है।प्रतिबद्ध होने से पहले दोनों का पूर्वावलोकन करें।
दृश्य शैली को सीमित करें
कस्टम रंग डार्क मोड या प्लेटफ़ॉर्म थीम के साथ विरोध कर सकते हैं।रेंडरर की डिफ़ॉल्ट से शुरुआत करें।शैलियाँ तभी जोड़ें जब वे अर्थ संप्रेषित करें और सभी आवश्यक विषयों में पठनीय रहें।
स्रोत को इसके स्पष्टीकरण के पास रखें
जब संभव हो तो Mermaid ब्लॉक को उसी Markdown फ़ाइल में संग्रहीत करें।इससे गद्य और रेखाचित्र एक ही समीक्षा में एक साथ बदल जाते हैं।
Mermaid बनाम एक स्थिर छवि
Mermaid चुनें जब:
- आरेख बार-बार बदलता है;
- स्रोत अंतर मूल्यवान हैं;
- लेआउट मानक आरेख प्रकारों का उपयोग करता है;
- प्रकाशन मंच Mermaid को विश्वसनीय रूप से प्रस्तुत करता है।
एसवीजी या पीएनजी चुनें जब:
- डिज़ाइन के लिए सटीक मैन्युअल लेआउट की आवश्यकता होती है;
- गंतव्य Mermaid प्रस्तुत नहीं करता है;
- सटीक स्वरूप निश्चित रहना चाहिए;
- बाहरी साझाकरण के लिए एक स्टैंडअलोन संपत्ति की आवश्यकता होती है।
एक उपयोगी हाइब्रिड Mermaid स्रोत को बनाए रखना और उन गंतव्यों के लिए एक एसवीजी निर्यात करना है जो इसे प्रस्तुत नहीं कर सकते हैं।स्रोत को निर्यातित संपत्ति के पास रखें और इसे पुन: उत्पन्न करने के तरीके का दस्तावेजीकरण करें।
उपयोग Markdown से छवि , या सीधे एसवीजी डाउनलोड करें Mermaid डायग्राम पूर्वावलोकन जब आरेख ही संपत्ति है।
FAQ
क्या Mermaid मानक Markdown का हिस्सा है?
नं. एक बाड़बंदी mermaid ब्लॉक संगत अनुप्रयोगों और बिल्ड सिस्टम द्वारा मान्यता प्राप्त एक एक्सटेंशन है।एक बुनियादी Markdown पार्सर इसे सामान्य कोड के रूप में प्रस्तुत कर सकता है।
क्या GitHub Mermaid आरेख प्रस्तुत करता है?
हाँ.GitHub के दस्तावेज़ में Markdown फ़ाइलों और कई सहयोग सतहों में Mermaid प्रतिपादन का वर्णन किया गया है।नए सिंटैक्स का परीक्षण करें क्योंकि GitHub तैनात रेंडरर और सुरक्षा सेटिंग्स को नियंत्रित करता है।
क्या मैं Obsidian में Mermaid का उपयोग कर सकता हूँ?
Obsidian के आधिकारिक सहायता दस्तावेज़ Mermaid-शैली के बाड़ वाले आरेख ब्लॉक नोट्स में।फ़ीचर समर्थन एप्लिकेशन के रेंडरर के साथ बदल सकता है, इसलिए अपने इंस्टॉल किए गए संस्करण में जटिल या नए पेश किए गए आरेख प्रकारों को सत्यापित करें।
क्या Mermaid आर्किटेक्चर दस्तावेज़ की जगह ले सकता है?
नहीं। आरेख एक प्रणाली का एक दृश्य है।इसे निर्णयों, स्वामित्व, बाधाओं, विफलता व्यवहार और आधिकारिक इंटरफेस या स्कीमा के लिंक के साथ जोड़ें।
मेरा आरेख डार्क मोड में अलग ढंग से प्रस्तुत क्यों होता है?
प्लेटफ़ॉर्म अलग-अलग Mermaid थीम, सीएसएस वेरिएबल, फ़ॉन्ट और पृष्ठभूमि लागू कर सकते हैं।जब तक आपने दोनों विषयों का परीक्षण नहीं कर लिया है तब तक हार्ड-कोडित रंगों से बचें।
क्या मुझे निर्यातित एसवीजी फ़ाइलें प्रतिबद्ध करनी चाहिए?
एक एसवीजी प्रतिबद्ध करें जब प्रकाशन गंतव्य को स्थिर संपत्ति की आवश्यकता हो या प्रस्तुत परिणाम स्थिर रहना चाहिए।दोनों संस्करणों को बहने से रोकने के लिए Mermaid स्रोत और एक दस्तावेजी पुनर्जनन प्रक्रिया भी रखें।
क्या Mermaid गोपनीय आरेखों के लिए सुरक्षित है?
गोपनीयता संपादक और प्रकाशन वर्कफ़्लो पर निर्भर करती है।WordToMD का पूर्वावलोकन आपके ब्राउज़र में आरेख प्रस्तुत करता है, लेकिन Markdown या SVG को किसी रिपॉजिटरी या साइट पर प्रकाशित करना उस गंतव्य के पहुंच नियंत्रण का पालन करता है।
निष्कर्ष
Mermaid आरेखों को बनाए रखने योग्य बनाता है क्योंकि स्रोत Markdown के साथ रहता है।एक छोटे बाड़ वाले ब्लॉक से शुरू करें, प्रश्न से मेल खाने वाले आरेख प्रकार को चुनें, वाक्यविन्यास का पूर्वावलोकन करें, और अंतिम रेंडरर में इसका परीक्षण करें।आवश्यक अर्थ समझाने के लिए गद्य का उपयोग करें और जब किसी गंतव्य को स्थिर संपत्ति की आवश्यकता हो तो एसवीजी निर्यात करें।
में उदाहरण आज़माएं Mermaid डायग्राम पूर्वावलोकन, इसमें आसपास के दस्तावेज़ संपादित करें Markdown संपादक, और आरेख को इतना केंद्रित रखें कि भविष्य का योगदानकर्ता पूरे पृष्ठ को दोबारा बनाए बिना इसे समझ सके और अपडेट कर सके।