Cursor rule

1---
2description: 
3globs: *.md,/doc
4alwaysApply: false
5---
6# Documentation Styling Guidelines
7 
8This document outlines the styling and content guidelines for creating documentation within the Vrooli project. Adhering to these guidelines will ensure consistency, clarity, and maintainability across all project documentation.
9 
10## 🎯 Guiding Principles
11 
12-   **Visually Stunning**: Documentation should be engaging and easy to navigate. Utilize Markdown's full capabilities, including emojis and Mermaid diagrams, to enhance visual appeal.
13-   **Comprehensive yet Concise**: Provide thorough information, but avoid unnecessary length. Prefer linking to other relevant documents or sections for deeper dives.
14-   **Clarity and Accessibility**: Write clearly and make documentation accessible to a diverse audience, including those with varying technical backgrounds.
15-   **Actionable and Practical**: Focus on providing practical examples, real-world context, and actionable guidance.
16 
17## 📝 Content Structure & Organization
18 
19-   **Table of Contents (TOC)**:
20    -   Always include a comprehensive TOC for documents longer than approximately 100 lines.
21    -   Ensure the TOC is easy to navigate and accurately reflects the document structure.
22-   **Logical Hierarchy**:
23    -   Use proper heading structure (H1 → H2 → H3, etc.).
24    -   Ensure a clear and logical progression of sections.
25    -   Use emojis in headings to add visual cues and improve readability (e.g., `## 🚀 Section Title`).
26-   **Introduction & TL;DR**:
27    -   Start with a brief introduction explaining the document's purpose.
28    -   Include a "Too Long; Didn't Read" (TL;DR) summary at the beginning for quick insights, especially for longer documents.
29-   **Cross-References**:
30    -   Link to related documentation files using relative paths (e.g., `[Link Text](mdc:../path/to/document.md)`).
31    -   Use descriptive link text that clearly indicates the target content.
32    -   Encourage linking to minimize redundancy and keep documents focused.
33-   **Practical Examples**:
34    -   Include real code examples, command snippets, and practical scenarios—not just theory.
35    -   Clearly explain what each example does and how it relates to the Vrooli project.
36 
37## ✨ Visual Enhancement & Formatting
38 
39-   **Mermaid Diagrams**:
40    -   Use [Mermaid diagrams](mdc:https:/mermaid.js.org/intro) to illustrate complex workflows, architectures, system relationships, and decision trees.
41    -   Ensure diagrams are clear, well-labeled, and contribute to understanding.
42    -   Example:
43```mermaid
44        graph TD
45            A[Start] --> B{Decision?};
46            B -- Yes --> C[Option 1];
47            B -- No --> D[Option 2];
48```
49-   **Emojis**:
50    -   Use emojis appropriately in headings and text to add visual interest and context (e.g., ✨, 🚀, 💡, ⚠️, 🎯, ⚙️, 📚).
51    -   Don't overuse emojis to the point of distraction.
52-   **Code Blocks**:
53    -   Always specify the language for syntax highlighting (e.g., ` ```typescript`, ` ```bash`, ` ```sql`, ` ```mermaid`).
54    -   Ensure code is well-formatted and easy to read.
55-   **Consistent Formatting**:
56    -   Use **bold** for important concepts, tool names, and key terms.
57    -   Use *italics* for emphasis and file/directory names when inline (e.g., *README.md*, */docs/architecture*).
58    -   Use `backticks` for inline code snippets, commands, technical terms, and file extensions (e.g., `npm install`, `API_KEY`, `.ts` files).
59    -   Use `>` blockquotes for important notes, warnings, or direct quotations.
60        > **Note**: This is an important piece of information.
61 
62## 💎 Content Quality Standards
63 
64-   **Up-to-Date Information**:
65    -   Ensure documentation reflects the current state of the project.
66    -   Research current best practices and include modern approaches where relevant.
67-   **Actionable Guidance**:
68    -   Provide step-by-step instructions where applicable.
69    -   Focus on enabling users to accomplish tasks.
70-   **Troubleshooting**:
71    -   Include common issues, error scenarios, and practical solutions or workarounds.
72-   **Real-World Context**:
73    -   Show how concepts apply specifically to the Vrooli project and its goals.
74-   **Audience Awareness**:
75    -   Write for the intended audience, explaining technical concepts clearly.
76 
77## 📄 Documentation Patterns
78 
79-   **Error Scenarios**: Document what can go wrong and how to fix it.
80-   **Command Examples**: Show actual commands with expected outputs (if applicable).
81-   **Configuration Snippets**: Include real configuration examples with explanations.
82-   **Integration Points**: Clearly explain how components connect and interact.
83-   **Decision Rationale**: For architectural or significant technical decisions, briefly explain the "why" behind them.
84 
85## 🛠️ Maintenance Principles
86 
87-   **Accuracy First**: Validate information against the actual codebase and project implementation.
88-   **Comprehensive Coverage**: Address both "happy path" scenarios and potential edge cases or problems.
89-   **Future-Proof**: Structure content to remain relevant as the project evolves, or clearly mark version-specific information.
90-   **Review and Update**: Periodically review documentation for outdated information or areas needing improvement.
91 
92## 🎨 Mermaid Diagram Guidelines
93 
94### **Text Formatting and Line Breaks**
95 
96#### **Newlines and Line Breaks**
97- **Use `<br>` tags** for manual line breaks within node text:
98```mermaid
99  A["First line<br>Second line<br>Third line"]
100```
101 
102#### **Automatic Text Wrapping (Recommended)**
103- **Use markdown strings** with backticks and double quotes for automatic text wrapping:
104```mermaid
105  A["`This text will automatically wrap when it becomes too long and you can
106     start a new line by simply using a newline character`"]
107```
108 
109#### **Text Formatting**
110- **Bold text**: Use double asterisks within markdown strings: `**bold text**`
111- **Italics**: Use single asterisks within markdown strings: `*italic text*`
112- **Example**:
113```mermaid
114  A["`**Bold text** and *italic text* with automatic wrapping`"]
115```
116 
117### **Character Restrictions and Escaping**
118 
119#### **Reserved Words That Break Diagrams**
120- **The word "end"** (case-sensitive): Must be wrapped in quotes
121```mermaid
122  A["End"] --> B["START"]  // ✅ Correct
123  A[End] --> B[START]      // ❌ Will break
124```
125 
126#### **Problematic Character Sequences**
127- **Avoid starting connecting nodes with "o" or "x"**: Add space or capitalize
128```mermaid
129  A --- ops    // ✅ Correct (space added)
130  A --- Ops    // ✅ Correct (capitalized)
131  A ---ops     // ❌ Will create unexpected edge types
132```
133 
134#### **Special Character Escaping**
135- **Use HTML entity codes** for special characters:
136```mermaid
137  A["Hash symbol: &#35;"]     // For #
138  A["Semicolon: &#59;"]       // For ;
139  A["Less than: &lt;"]       // For <
140  A["Greater than: &gt;"]    // For >
141```
142 
143#### **Comments and Directives**
144- **Avoid curly braces `{}` in comments** using `%%`:
145```mermaid
146  %% This is a good comment
147  %% Avoid: This comment has {braces} - may confuse renderer
148```
149 
150#### **Unicode and Emojis**
151- **Fully supported** within quoted text and markdown strings:
152```mermaid
153  A["`🚀 Unicode works: शान्तिः سلام 和平`"]
154```
155 
156#### **Quotes and Special Text**
157- **Use double quotes** to safely include problematic characters:
158```mermaid
159  A["Text with (parentheses) and {braces} and [brackets]"]
160```
161 
162### **Best Practices for Mermaid Text**
1631. **Use markdown strings** `"` for text that needs formatting or automatic wrapping
1642. **Quote any text** that contains special characters, punctuation, or reserved words
1653. **Use entity codes** for symbols that might interfere with Mermaid syntax
166 
167By following these guidelines, we can create a high-quality, engaging, and useful documentation suite that supports the Vrooli project and its community.