| Dimension | Shared | Only in A | Only in B | Overlap |
|---|---|---|---|---|
| Sections | 0 | 0 | 11 | 0% |
| Commands | 0 | 0 | 1 | 0% |
| Section tags | 0 | 0 | 6 | 0% |
What each file covers
Sections
0 shared · 0 only in A · 11 only in B- + Documentation Styling Guidelines
- + 🎯 Guiding Principles
- + 📝 Content Structure & Organization
- + ✨ Visual Enhancement & Formatting
- + 💎 Content Quality Standards
- + 📄 Documentation Patterns
- + 🛠️ Maintenance Principles
- + 🎨 Mermaid Diagram Guidelines
- + **Text Formatting and Line Breaks**
- + **Character Restrictions and Escaping**
- + **Best Practices for Mermaid Text**
Commands
0 shared · 0 only in A · 1 only in B- + npm install
Section tags
0 shared · 0 only in A · 6 only in B- + setup
- + lint-format
- + code-style
- + architecture
- + ui
- + docs
Line diff
Vrooli/Vrooli · .cursor/rules/server.mdc
@@ −1 @@
1---
2description:
3globs: packages/server/src,packages/jobs/src
4alwaysApply: false
5---
6- This is a TypeScript NodeJS server running through ExpressJS.
7- Ensure that the code adheres to our styling rules [.eslintrc](mdc:.eslintrc) [.eslintrc](mdc:packages/server/.eslintrc).
8- See [README.md](mdc:docs/server/README.md) for more information and guidelines
Vrooli/Vrooli · .cursor/rules/doc.mdc
@@ +1 @@
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: #"] // For #
138 A["Semicolon: ;"] // For ;
139 A["Less than: <"] // For <
140 A["Greater than: >"] // 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.
@@ −1 +1 @@
11 ---
22 description:
3−globs: packages/server/src,packages/jobs/src
3+globs: *.md,/doc
44 alwaysApply: false
55 ---
6−- This is a TypeScript NodeJS server running through ExpressJS.
7−- Ensure that the code adheres to our styling rules [.eslintrc](mdc:.eslintrc) [.eslintrc](mdc:packages/server/.eslintrc).
8−- See [README.md](mdc:docs/server/README.md) for more information and guidelines
6+# Documentation Styling Guidelines
7+
8+This 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: #"] // For #
138+ A["Semicolon: ;"] // For ;
139+ A["Less than: <"] // For <
140+ A["Greater than: >"] // 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**
163+1. **Use markdown strings** `"` for text that needs formatting or automatic wrapping
164+2. **Quote any text** that contains special characters, punctuation, or reserved words
165+3. **Use entity codes** for symbols that might interfere with Mermaid syntax
166+
167+By following these guidelines, we can create a high-quality, engaging, and useful documentation suite that supports the Vrooli project and its community.
