2. Apply Deepthink Protocol (reason about dependencies
risks
These rules MUST be applied whenever creating, modifying, or generating any documentation in the docs/ directory
Sign in to like and favorite skills
IMPORTANT: These rules MUST be applied whenever creating, modifying, or generating any documentation in the
docs/ directory.
When generating or editing documentation, always:
\{id\}, \{value\}, \{placeholder\}python, typescript, ```bash)Framework: We use Nextra for documentation, which processes MDX (Markdown + JSX) files.
Critical: MDX interprets anything inside curly braces
{...} as a JSX expression. Always escape curly braces when you want to display them as literal text:
✅ GOOD: API PUT /test_results/\{id\} ❌ BAD: API PUT /test_results/{id} ← This causes "ReferenceError: id is not defined"
Rule: Any placeholder, variable, or example value in curly braces must be escaped:
\{value\}
Common scenarios requiring escaping:
/api/users/\{userId\}/profile, /posts/\{postId\}/comments/\{commentId\}"Hello \{name\}", "User \{username\} logged in"### Using \{variable\} in templates\{"key": "value"\}, \{"status": "success"\}/files/\{filename\}, /images/\{imageId\}.jpg\{count\} items, \{total\} usersWhen NOT to escape:
`{id}` - backticks make it literalAccessibility and Consistency:
Follow Existing Style:
Code Examples:
python`, typescript, ````bash# apps/backend/src/...Structure:
Problem: MDX files cannot directly import Material-UI icons due to module resolution issues.
Solution: Always create a separate JSX component to handle icon imports, then use that component in MDX files.
Create a JSX component in
/docs/src/components/ that imports the MUI icons:
'use client' import React from 'react' import IconName from '@mui/icons-material/IconName' import { InfoCardHorizontal } from './InfoCardHorizontal' export const MyComponent = () => { return ( <InfoCardHorizontal icon={IconName} title="..." description="..." /> ) }
Register the component in
/docs/src/mdx-components.js:
import { MyComponent } from './components/MyComponent' export function useMDXComponents(components) { return { ...themeComponents, ...components, MyComponent, } }
Use in MDX files without any imports:
<MyComponent />
FeatureOverview.jsx - Imports MUI icons, exports componentArchitectureOverview.jsx - Imports MUI icons, exports componentPlatformFeatures.jsx - Imports MUI icons, exports componentNever try to import
@mui/icons-material/* directly in .mdx files.
docs/ ├── src/ # Documentation site source │ ├── components/ # Reusable JSX components for MDX │ ├── app/ # Next.js app directory │ └── mdx-components.js # MDX component registry ├── content/ # All documentation content (MDX files) │ ├── _meta.tsx # Root navigation config │ ├── index.mdx # Home page │ ├── getting-started/ # Getting started guides │ ├── platform/ # Platform feature documentation │ ├── development/ # Development guides │ │ ├── backend/ # Backend development │ │ ├── frontend/ # Frontend development │ │ └── worker/ # Worker service │ └── sdk/ # SDK documentation └── README.md # Documentation overview
Each directory should have a
_meta.tsx file to configure navigation:
import type { MetaRecord } from 'nextra' const meta: MetaRecord = { index: 'Overview', 'getting-started': 'Getting Started', 'api-reference': 'API Reference', } export default meta
Or for more complex configurations:
export default { index: { title: "Overview", theme: { layout: "full", }, }, "feature-name": { title: "Feature Name", }, }
test-result-status.mdxIMPORTANT: These rules MUST be applied whenever creating, modifying, or generating any documentation in the
docs/ directory.
When generating or editing documentation, always:
\{id\}, \{value\}, \{placeholder\}python, typescript, ```bash)Framework: We use Nextra for documentation, which processes MDX (Markdown + JSX) files.
Critical: MDX interprets anything inside curly braces
{...} as a JSX expression. Always escape curly braces when you want to display them as literal text:
✅ GOOD: API PUT /test_results/\{id\} ❌ BAD: API PUT /test_results/{id} ← This causes "ReferenceError: id is not defined"
Rule: Any placeholder, variable, or example value in curly braces must be escaped:
\{value\}
Common scenarios requiring escaping:
/api/users/\{userId\}/profile, /posts/\{postId\}/comments/\{commentId\}"Hello \{name\}", "User \{username\} logged in"### Using \{variable\} in templates\{"key": "value"\}, \{"status": "success"\}/files/\{filename\}, /images/\{imageId\}.jpg\{count\} items, \{total\} usersWhen NOT to escape:
`{id}` - backticks make it literalAccessibility and Consistency:
Follow Existing Style:
Code Examples:
python`, typescript, ````bash# apps/backend/src/...Structure:
Problem: MDX files cannot directly import Material-UI icons due to module resolution issues.
Solution: Always create a separate JSX component to handle icon imports, then use that component in MDX files.
Create a JSX component in
/docs/src/components/ that imports the MUI icons:
'use client' import React from 'react' import IconName from '@mui/icons-material/IconName' import { InfoCardHorizontal } from './InfoCardHorizontal' export const MyComponent = () => { return ( <InfoCardHorizontal icon={IconName} title="..." description="..." /> ) }
Register the component in
/docs/src/mdx-components.js:
import { MyComponent } from './components/MyComponent' export function useMDXComponents(components) { return { ...themeComponents, ...components, MyComponent, } }
Use in MDX files without any imports:
<MyComponent />
FeatureOverview.jsx - Imports MUI icons, exports componentArchitectureOverview.jsx - Imports MUI icons, exports componentPlatformFeatures.jsx - Imports MUI icons, exports componentNever try to import
@mui/icons-material/* directly in .mdx files.
docs/ ├── src/ # Documentation site source │ ├── components/ # Reusable JSX components for MDX │ ├── app/ # Next.js app directory │ └── mdx-components.js # MDX component registry ├── content/ # All documentation content (MDX files) │ ├── _meta.tsx # Root navigation config │ ├── index.mdx # Home page │ ├── getting-started/ # Getting started guides │ ├── platform/ # Platform feature documentation │ ├── development/ # Development guides │ │ ├── backend/ # Backend development │ │ ├── frontend/ # Frontend development │ │ └── worker/ # Worker service │ └── sdk/ # SDK documentation └── README.md # Documentation overview
Each directory should have a
_meta.tsx file to configure navigation:
import type { MetaRecord } from 'nextra' const meta: MetaRecord = { index: 'Overview', 'getting-started': 'Getting Started', 'api-reference': 'API Reference', } export default meta
Or for more complex configurations:
export default { index: { title: "Overview", theme: { layout: "full", }, }, "feature-name": { title: "Feature Name", }, }
test-result-status.mdx