You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
This guide covers Docusaurus-specific formatting rules for Roo Code documentation. Before applying these conventions, always explore the project structure to understand the actual directory layout.
4
+
</overview>
5
+
6
+
<discovery_first>
7
+
<principle>Always use list_files to discover the actual project structure before making assumptions about paths</principle>
8
+
<principle>Check for existing patterns in similar files before creating new content</principle>
9
+
<principle>Verify directory existence before referencing specific paths</principle>
10
+
</discovery_first>
11
+
12
+
<linking>
13
+
<rulename="internal_links">
14
+
<description>Use paths relative to the documentation root. Do not include the `.md` extension. Discover the documentation structure first.</description>
15
+
<discovery_steps>
16
+
<step>Use list_files to find the documentation root directory</step>
17
+
<step>Identify the path structure used in existing documentation</step>
18
+
<step>Follow the established pattern</step>
19
+
</discovery_steps>
20
+
<good>[Link to Guide](/intro/)</good>
21
+
<bad>[Link to Guide](../intro.md)</bad>
22
+
</rule>
23
+
<rulename="site_alias">
24
+
<description>Use `@site` for code imports or asset references from the project root. Do not use it for Markdown links.</description>
25
+
<good>import Header from '@site/src/components/Header';</good>
26
+
<bad>[Link](@site/docs/intro.md)</bad>
27
+
</rule>
28
+
</linking>
29
+
30
+
<media>
31
+
<rulename="images">
32
+
<description>Discover the image storage location in the project before placing images. Look for existing image references to understand the pattern.</description>
33
+
<discovery_steps>
34
+
<step>Use list_files to find where images are stored (commonly in static/img or similar)</step>
35
+
<step>Check existing documentation for image reference patterns</step>
36
+
<step>Follow the established convention</step>
37
+
</discovery_steps>
38
+
<example>
39
+
<![CDATA[
40
+
<!-- First discover the actual image path structure, then use it -->
41
+
<img src="/img/installing/installing-2.png" alt="VS Code's Install from VSIX dialog" width="600" />
42
+
]]>
43
+
</example>
44
+
</rule>
45
+
</media>
46
+
47
+
<versioning>
48
+
<rulename="no_version_numbers">
49
+
<description>Do not include version numbers or phrases like "as of version X.Y" in general documentation. First discover where version information is stored in the project.</description>
50
+
<discovery_steps>
51
+
<step>Use list_files to find version-related documentation directories</step>
52
+
<step>Check for patterns like update-notes, changelog, or release directories</step>
53
+
<step>Place version-specific information in the appropriate location</step>
54
+
</discovery_steps>
55
+
</rule>
56
+
</versioning>
57
+
58
+
<frontmatter>
59
+
<rulename="metadata">
60
+
<description>Check existing documentation files for frontmatter patterns before adding new ones. The required fields may vary by project.</description>
61
+
<discovery_steps>
62
+
<step>Read several existing documentation files to understand the frontmatter pattern</step>
63
+
<step>Identify which fields are consistently used</step>
64
+
<step>Follow the established pattern</step>
65
+
</discovery_steps>
66
+
<example>
67
+
<![CDATA[
68
+
---
69
+
description: A concise summary of the page content.
70
+
keywords:
71
+
- relevant
72
+
- keywords
73
+
- for
74
+
- search
75
+
image: /img/social-share.jpg
76
+
---
77
+
]]>
78
+
</example>
79
+
</rule>
80
+
</frontmatter>
81
+
82
+
<general_discovery_workflow>
83
+
<stepnumber="1">Use list_files to explore the project structure</step>
84
+
<stepnumber="2">Read existing files similar to what you're creating/editing</step>
85
+
<stepnumber="3">Identify patterns in paths, formatting, and conventions</step>
86
+
<stepnumber="4">Follow the established patterns rather than assuming standard locations</step>
87
+
<stepnumber="5">When in doubt, ask for clarification rather than making assumptions</step>
88
+
</general_discovery_workflow>
89
+
90
+
<redundancy_prevention_workflow>
91
+
<overview>
92
+
Before making any documentation changes, follow this workflow to prevent redundancy and ensure cohesion.
93
+
</overview>
94
+
95
+
<stepnumber="1">
96
+
<title>Content Discovery</title>
97
+
<actions>
98
+
<action>Use codebase_search to find all mentions of the topic or feature</action>
99
+
<action>Search for variations of key terms (e.g., "configuration", "config", "setup")</action>
100
+
<action>Note all locations where related information exists</action>
101
+
</actions>
102
+
<example>
103
+
<![CDATA[
104
+
<!-- Search for existing content about a feature -->
105
+
<codebase_search>
106
+
<query>authentication setup configuration</query>
107
+
<path>docs</path>
108
+
</codebase_search>
109
+
]]>
110
+
</example>
111
+
</step>
112
+
113
+
<stepnumber="2">
114
+
<title>Duplication Analysis</title>
115
+
<actions>
116
+
<action>Read all discovered related content thoroughly</action>
117
+
<action>Identify if the requested change would duplicate existing information</action>
118
+
<action>Determine if consolidation is needed instead of addition</action>
119
+
</actions>
120
+
<decision_matrix>
121
+
<scenariocondition="Content exists and is complete">
122
+
<action>Inform user and suggest updating existing location</action>
123
+
</scenario>
124
+
<scenariocondition="Content exists but is incomplete">
125
+
<action>Enhance existing content rather than creating new</action>
126
+
</scenario>
127
+
<scenariocondition="Content is scattered across multiple files">
128
+
<action>Consider consolidation into a single authoritative location</action>
129
+
</scenario>
130
+
<scenariocondition="Content doesn't exist">
131
+
<action>Proceed with creating new content</action>
132
+
</scenario>
133
+
</decision_matrix>
134
+
</step>
135
+
136
+
<stepnumber="3">
137
+
<title>Cross-Reference Validation</title>
138
+
<actions>
139
+
<action>Check all internal links that might be affected</action>
140
+
<action>Verify that moving or changing content won't break existing references</action>
141
+
<action>Update docusaurus.config.ts redirects if moving content</action>
142
+
</actions>
143
+
</step>
144
+
145
+
<stepnumber="4">
146
+
<title>Terminology Consistency</title>
147
+
<actions>
148
+
<action>Ensure consistent use of technical terms across all documentation</action>
149
+
<action>Check glossary or terminology guide if one exists</action>
150
+
<action>Maintain consistent naming for features, tools, and concepts</action>
151
+
</actions>
152
+
</step>
153
+
</redundancy_prevention_workflow>
154
+
155
+
<cohesion_guidelines>
156
+
<guidelinename="information_architecture">
157
+
<description>Maintain logical information hierarchy and flow</description>
158
+
<checks>
159
+
<check>Does this content belong in the current section?</check>
160
+
<check>Would users expect to find this information here?</check>
161
+
<check>Does it follow the progression from basic to advanced?</check>
162
+
</checks>
163
+
</guideline>
164
+
165
+
<guidelinename="single_source_of_truth">
166
+
<description>Each piece of information should have one authoritative location</description>
167
+
<implementation>
168
+
<step>Core information lives in one place</step>
169
+
<step>Other locations reference the authoritative source</step>
170
+
<step>Use includes or references rather than duplication</step>
171
+
</implementation>
172
+
</guideline>
173
+
174
+
<guidelinename="contextual_linking">
175
+
<description>Connect related content through meaningful links</description>
176
+
<best_practices>
177
+
<practice>Link to prerequisites before advanced topics</practice>
178
+
<practice>Provide "See also" sections for related content</practice>
179
+
<practice>Ensure bidirectional linking where appropriate</practice>
180
+
</best_practices>
181
+
</guideline>
182
+
</cohesion_guidelines>
183
+
<documentation_update_protocol>
184
+
<overview>
185
+
When updating existing documentation, follow this protocol to maintain quality and prevent issues.
186
+
</overview>
187
+
188
+
<pre_update_validation>
189
+
<step>Identify all documents that reference the content being updated</step>
190
+
<step>Check for dependent examples or tutorials that might need updating</step>
191
+
<step>Verify that the update won't invalidate existing instructions</step>
192
+
<step>Consider backward compatibility if documenting changed features</step>
193
+
</pre_update_validation>
194
+
195
+
<update_impact_assessment>
196
+
<question>Will this update require changes to other documents?</question>
197
+
<question>Are there code examples that need to be updated?</question>
198
+
<question>Do any quickstart guides or tutorials reference this content?</question>
199
+
<question>Will this change affect the logical flow of the documentation?</question>
200
+
</update_impact_assessment>
201
+
202
+
<post_update_checklist>
203
+
<item>All cross-references have been updated</item>
204
+
<item>No broken links have been introduced</item>
205
+
<item>Terminology remains consistent across all affected documents</item>
206
+
<item>The update enhances rather than contradicts existing content</item>
207
+
<item>Version-specific information is properly handled</item>
208
+
</post_update_checklist>
209
+
</documentation_update_protocol>
210
+
211
+
<ask_before_proceeding>
212
+
<description>Use ask_followup_question when uncertainty exists about redundancy or impact</description>
213
+
<scenarios>
214
+
<scenario>When similar content exists in multiple locations</scenario>
215
+
<scenario>When the requested change might contradict existing documentation</scenario>
216
+
<scenario>When consolidation might be better than addition</scenario>
217
+
<scenario>When the impact on other documents is unclear</scenario>
218
+
</scenarios>
219
+
<example>
220
+
<
0 commit comments