|
| 1 | +--- |
| 2 | +description: LLM Contribution Guidelines for Sentry Documentation |
| 3 | +globs: |
| 4 | +alwaysApply: false |
| 5 | +--- |
| 6 | +# LLM Contribution Guidelines for Sentry Documentation |
| 7 | + |
| 8 | +## Overview |
| 9 | + |
| 10 | +This is a Next.js documentation site using MDX for content management. The codebase serves SDK documentation for multiple platforms and frameworks with a sophisticated shared content system. |
| 11 | + |
| 12 | +## File Structure & Organization |
| 13 | + |
| 14 | +### Core Directories |
| 15 | + |
| 16 | +``` |
| 17 | +docs/ # All documentation content |
| 18 | +├── platforms/ # Platform-specific documentation |
| 19 | +│ ├── javascript/ |
| 20 | +│ │ ├── config.yml # Platform configuration |
| 21 | +│ │ ├── common/ # Shared content for JS platform |
| 22 | +│ │ └── guides/ # Framework-specific guides |
| 23 | +│ │ ├── hono/ |
| 24 | +│ │ ├── express/ |
| 25 | +│ │ └── react/ |
| 26 | +│ ├── python/ |
| 27 | +│ └── ... |
| 28 | +├── product/ # Product documentation |
| 29 | +├── api/ # API documentation |
| 30 | +└── concepts/ # Conceptual documentation |
| 31 | + |
| 32 | +platform-includes/ # Shared content across platforms |
| 33 | +├── getting-started-install/ |
| 34 | +├── getting-started-config/ |
| 35 | +└── getting-started-verify/ |
| 36 | + |
| 37 | +includes/ # General shared content |
| 38 | +src/ # Application source code |
| 39 | +├── components/ # React components |
| 40 | +├── mdx.ts # MDX processing logic |
| 41 | +└── types/ # TypeScript types |
| 42 | +``` |
| 43 | + |
| 44 | +## Content Creation Rules |
| 45 | + |
| 46 | +### 1. MDX File Structure |
| 47 | + |
| 48 | +All documentation files must use MDX format with YAML frontmatter: |
| 49 | + |
| 50 | +```mdx |
| 51 | +--- |
| 52 | +title: "Framework Name" |
| 53 | +description: "Learn how to set up Framework with Sentry." |
| 54 | +sdk: sentry.javascript.framework |
| 55 | +categories: |
| 56 | + - javascript |
| 57 | + - server |
| 58 | +sidebar_order: 10 |
| 59 | +--- |
| 60 | + |
| 61 | +<PlatformContent includePath="getting-started-primer" /> |
| 62 | + |
| 63 | +Content goes here... |
| 64 | +``` |
| 65 | + |
| 66 | +### 2. Required Frontmatter Fields |
| 67 | + |
| 68 | +- `title`: Page title (used in navigation and SEO) |
| 69 | +- `description`: Meta description for SEO |
| 70 | +- `sdk`: SDK identifier (format: `sentry.{platform}.{guide}`) |
| 71 | +- `categories`: Array of category tags |
| 72 | + |
| 73 | +### 3. Optional Frontmatter Fields |
| 74 | + |
| 75 | +- `sidebar_order`: Controls navigation order (lower = higher in list) |
| 76 | +- `sidebar_title`: Override sidebar display name |
| 77 | +- `sidebar_hidden`: Hide from sidebar navigation |
| 78 | +- `draft`: Mark as draft (hidden from navigation) |
| 79 | +- `supported`: Array of platforms/guides this content supports |
| 80 | +- `notSupported`: Array of platforms/guides this content doesn't support |
| 81 | + |
| 82 | +## Component Usage |
| 83 | + |
| 84 | +### Platform-Specific Content |
| 85 | + |
| 86 | +Use `<PlatformContent>` for shared, platform-specific content: |
| 87 | + |
| 88 | +```mdx |
| 89 | +<PlatformContent includePath="getting-started-install" /> |
| 90 | +<PlatformContent includePath="getting-started-config" /> |
| 91 | +``` |
| 92 | + |
| 93 | +### Onboarding Options |
| 94 | + |
| 95 | +For feature selection interfaces: |
| 96 | + |
| 97 | +```mdx |
| 98 | +<OnboardingOptionButtons |
| 99 | + options={["error-monitoring", "performance", "profiling"]} |
| 100 | +/> |
| 101 | +``` |
| 102 | + |
| 103 | +### Code Blocks with Tabs |
| 104 | + |
| 105 | +For package manager instructions: |
| 106 | + |
| 107 | +```mdx |
| 108 | +```bash {tabTitle:npm} |
| 109 | +npm install @sentry/node --save |
| 110 | +``` |
| 111 | + |
| 112 | +```bash {tabTitle:yarn} |
| 113 | +yarn add @sentry/node |
| 114 | +``` |
| 115 | + |
| 116 | +```bash {tabTitle:pnpm} |
| 117 | +pnpm add @sentry/node |
| 118 | +``` |
| 119 | +``` |
| 120 | + |
| 121 | +### Code Highlighting |
| 122 | + |
| 123 | +Use filename annotations and highlighting: |
| 124 | + |
| 125 | +```mdx |
| 126 | +```typescript {filename:index.ts} |
| 127 | +import * as Sentry from "@sentry/node"; |
| 128 | + |
| 129 | +Sentry.init({ |
| 130 | + dsn: "___PUBLIC_DSN___", |
| 131 | +}); |
| 132 | +``` |
| 133 | +``` |
| 134 | + |
| 135 | +### Alerts and Callouts |
| 136 | + |
| 137 | +```mdx |
| 138 | +<Alert level="info" title="Important Note"> |
| 139 | +Content here... |
| 140 | +</Alert> |
| 141 | + |
| 142 | +<Alert level="warning"> |
| 143 | +Warning content... |
| 144 | +</Alert> |
| 145 | +``` |
| 146 | + |
| 147 | +### Links |
| 148 | + |
| 149 | +```mdx |
| 150 | +<PlatformLink to="/configuration/">Configuration</PlatformLink> |
| 151 | +``` |
| 152 | + |
| 153 | +### Expandable Sections |
| 154 | + |
| 155 | +```mdx |
| 156 | +<Expandable title="Optional Section"> |
| 157 | +Additional details... |
| 158 | +</Expandable> |
| 159 | +``` |
| 160 | + |
| 161 | +## Platform-Specific Guidelines |
| 162 | + |
| 163 | +### JavaScript Guides |
| 164 | + |
| 165 | +1. **Location**: Place under `docs/platforms/javascript/guides/{framework}/` |
| 166 | +2. **Naming**: Use lowercase, hyphenated names (e.g., `next-js`, `react-native`) |
| 167 | +3. **Structure**: Most guides should be simple and leverage shared content: |
| 168 | + |
| 169 | +```mdx |
| 170 | +--- |
| 171 | +title: "Framework Name" |
| 172 | +description: "Learn how to set up Framework with Sentry." |
| 173 | +sdk: sentry.javascript.framework |
| 174 | +fallbackGuide: javascript.node # For server-side frameworks |
| 175 | +categories: |
| 176 | + - javascript |
| 177 | + - server # or 'browser' for client-side |
| 178 | +--- |
| 179 | + |
| 180 | +<PlatformContent includePath="getting-started-primer" /> |
| 181 | + |
| 182 | +Brief framework-specific introduction... |
| 183 | + |
| 184 | +<PlatformContent includePath="getting-started-node" /> |
| 185 | +``` |
| 186 | + |
| 187 | +### Shared Content Creation |
| 188 | + |
| 189 | +Create shared content in `platform-includes/` when: |
| 190 | +- Content applies to multiple frameworks within a platform |
| 191 | +- Installation/configuration steps are similar |
| 192 | +- Verification steps are identical |
| 193 | + |
| 194 | +### Content Resolution Priority |
| 195 | + |
| 196 | +The system resolves content in this order: |
| 197 | +1. Guide-specific: `platform-includes/path/{platform}.{guide}.mdx` |
| 198 | +2. Platform-specific: `platform-includes/path/{platform}.mdx` |
| 199 | +3. Default: `platform-includes/path/_default.mdx` |
| 200 | + |
| 201 | +## Content Standards |
| 202 | + |
| 203 | +### Writing Style |
| 204 | + |
| 205 | +1. **Be concise**: Avoid unnecessary explanations |
| 206 | +2. **Use active voice**: "Install the SDK" not "The SDK should be installed" |
| 207 | +3. **Provide working examples**: All code samples must be functional |
| 208 | +4. **Include all imports**: Don't assume imports are obvious |
| 209 | + |
| 210 | +### Code Samples |
| 211 | + |
| 212 | +1. **Complete examples**: Include all necessary imports and setup |
| 213 | +2. **Use placeholders**: Use `___PUBLIC_DSN___` for DSN values |
| 214 | +3. **Add context**: Use filename annotations |
| 215 | +4. **Test functionality**: Ensure examples work as written |
| 216 | + |
| 217 | +### Error Handling |
| 218 | + |
| 219 | +Always include error handling examples: |
| 220 | + |
| 221 | +```typescript |
| 222 | +app.onError((err, c) => { |
| 223 | + Sentry.captureException(err); |
| 224 | + if (err instanceof HTTPException) { |
| 225 | + return err.getResponse() |
| 226 | + } |
| 227 | + return c.json({ error: "Internal server error" }, 500) |
| 228 | +}) |
| 229 | +``` |
| 230 | + |
| 231 | +## File Naming Conventions |
| 232 | + |
| 233 | +- Guide directories: lowercase with hyphens (`react-native`, `next-js`) |
| 234 | +- MDX files: `index.mdx` for main content |
| 235 | +- Versioned files: `index__v{version}.mdx` for version-specific content |
| 236 | +- Images: descriptive names in local `img/` directories |
| 237 | + |
| 238 | +## Navigation & Discovery |
| 239 | + |
| 240 | +### Sidebar Order |
| 241 | + |
| 242 | +Control navigation order with `sidebar_order`: |
| 243 | +- Getting started: 1-10 |
| 244 | +- Configuration: 11-20 |
| 245 | +- Advanced topics: 21-30 |
| 246 | +- Troubleshooting: 90+ |
| 247 | + |
| 248 | +### Page Grids |
| 249 | + |
| 250 | +For overview pages, use `<PageGrid>` to auto-generate child page listings: |
| 251 | + |
| 252 | +```mdx |
| 253 | +<PageGrid /> |
| 254 | +``` |
| 255 | + |
| 256 | +## Validation Checklist |
| 257 | + |
| 258 | +Before submitting content: |
| 259 | + |
| 260 | +- [ ] Frontmatter includes required fields |
| 261 | +- [ ] All code examples are complete and functional |
| 262 | +- [ ] Platform-specific content uses appropriate includes |
| 263 | +- [ ] Links use proper components (`<PlatformLink>` for internal) |
| 264 | +- [ ] Content follows established patterns for similar platforms |
| 265 | +- [ ] Sidebar navigation order is appropriate |
| 266 | +- [ ] All placeholders use standard format (`___PUBLIC_DSN___`) |
| 267 | + |
| 268 | +## Common Anti-Patterns |
| 269 | + |
| 270 | +### ❌ Avoid |
| 271 | + |
| 272 | +```mdx |
| 273 | +# Don't repeat boilerplate content |
| 274 | +Install Sentry by running: npm install @sentry/node |
| 275 | + |
| 276 | +# Don't use hardcoded links |
| 277 | +[Configuration](mdc:https:/docs.sentry.io/platforms/javascript/configuration) |
| 278 | + |
| 279 | +# Don't skip imports in examples |
| 280 | +Sentry.init({ dsn: "..." }); // Missing import |
| 281 | +``` |
| 282 | + |
| 283 | +### ✅ Do |
| 284 | + |
| 285 | +```mdx |
| 286 | +# Use shared content for common steps |
| 287 | +<PlatformContent includePath="getting-started-install" /> |
| 288 | + |
| 289 | +# Use proper link components |
| 290 | +<PlatformLink to="/configuration/">Configuration</PlatformLink> |
| 291 | + |
| 292 | +# Include complete examples |
| 293 | +import * as Sentry from "@sentry/node"; |
| 294 | + |
| 295 | +Sentry.init({ dsn: "___PUBLIC_DSN___" }); |
| 296 | +``` |
| 297 | + |
| 298 | +## Testing Content |
| 299 | + |
| 300 | +1. **Build locally**: Run `npm run dev` to test content rendering |
| 301 | +2. **Check navigation**: Verify sidebar placement and ordering |
| 302 | +3. **Test links**: Ensure all internal links resolve correctly |
| 303 | +4. **Validate components**: Confirm all MDX components render properly |
| 304 | + |
| 305 | +## Version Management |
| 306 | + |
| 307 | +- Use versioned includes for breaking changes: `file__v{version}.mdx` |
| 308 | +- Maintain backward compatibility when possible |
| 309 | +- Document version-specific differences clearly |
| 310 | +- Test across supported SDK versions |
0 commit comments