majiayu000 MDX Component Patterns
<Pitfall>
Common mistakes that cause bugs. Use for errors readers will likely make.
<Pitfall>
React components must start with a capital letter or they won't work!
</Pitfall>
<Note>
Important clarifications, conventions, or tips. Less severe than Pitfall.
<Note>
The convention is to name state variables like `[something, setSomething]`.
</Note>
<DeepDive>
Optional deep technical content. First child must be #### heading with ID.
<DeepDive>
#### Why does this work? {/* why-does-this-work */}
Technical explanation that's optional for understanding the main concept...
</DeepDive>
<Recipes>
Multiple related examples showing variations. Each recipe needs <Solution />.
<Recipes titleText="Examples of useState" titleId="examples-basic">
#### Counter (number) {/* counter-number */}
Description...
<Sandpack>{/* code */}</Sandpack>
<Solution />
#### Text field (string) {/* text-field-string */}
Description...
<Sandpack>{/* code */}</Sandpack>
<Solution />
</Recipes>
<Challenges>
End-of-page exercises. Learn pages only. Each challenge needs problem + solution Sandpack.
<Challenges>
#### Fix the bug {/* fix-the-bug */}
Problem description...
<Hint>Optional hint text.</Hint>
<Sandpack>{/* problem code */}</Sandpack>
<Solution>
Explanation...
<Sandpack>{/* solution code */}</Sandpack>
</Solution>
</Challenges>
<CodeStep> (Use Sparingly)
Numbered callouts in prose. Pairs with code block annotations.
Important: Use at most 2-3 colors in any given explanation. Excessive highlighting is distracting.
✅ Good use - highlighting key concepts:
React will compare the <CodeStep step={2}>dependencies</CodeStep> with the dependencies you passed...
🚫 Avoid - excessive highlighting:
When an <CodeStep step={1}>Activity</CodeStep> boundary is <CodeStep step={2}>hidden</CodeStep> during its <CodeStep step={3}>initial</CodeStep> render...
Guidelines:
- Maximum 2-3 different colors per explanation
- Don't highlight every keyword - only key concepts
- Use for terms in prose, not entire code blocks
- Maintain consistent usage within a section
Other Available Components
Version/Status: <Canary>, <CanaryBadge />, <Experimental>, <ExperimentalBadge />, <Deprecated>, <RSC>, <RSCBadge />, <NextMajor>, <Wip>
Visuals: <Diagram>, <DiagramGroup>, <Illustration>, <IllustrationBlock>, <CodeDiagram>, <FullWidth>
Console: <ConsoleBlock level="error|warning">, <ConsoleBlockMulti>, <ConsoleLogLine>
Specialized: <TerminalBlock>, <BlogCard>, <TeamMember>, <YouTubeIframe>, <ErrorDecoder />, <LearnMore>, <Math>, <MathI>, <LanguageList>
See existing docs for usage examples of these components.