AI Notes for Fumadocs

Objectives

• Avoid Build Errors: "Error evaluating Node.js code" and "Could not parse expression with acorn".
• Write MDX to standard simple, stable for docs system (Fumadocs + Next.js).

Common Errors (and how to avoid)

• Using braces/arrays directly in text makes MDX think it's JS expressions.
  • Wrong: Args: { id, name? } (without backticks) -> will cause parse error.
  • Correct: Args: { id, name? } (wrap in backticks) or put in code block.
• Writing arrays/objects in regular text.
  • Wrong: Returns: [{ ...product, unit }] (without backticks) -> will cause error.
  • Correct: Returns: [{ ...product, unit }] or code block.
• Using JSX/Component not available in theme or not imported.
  • Example: writing <Something/> will be parsed as component. Wrap in backticks.
• Special characters, unusual font/encoding.
  • Limit "smart quotes", special arrows. Use simple ASCII (", ->, -).
  • Vietnamese with accents is OK; errors usually from unescaped braces, not accents.
• Invalid frontmatter (file header between two --- lines).
  • Only put simple key: value string pairs: title, description.
  • Don't embed objects/arrays in frontmatter.

Safe MDX Rules (KISS)

• Wrap any samples with {}, [], <> in inline code with backticks, e.g.: { id }.
• For longer sections, use 3-backtick fenced code blocks and specify language if needed (e.g.: ts, json).
• Use simple bullet lists, don't nest too deeply.
• Don't embed dynamic JS/TS in MDX (e.g.: {items.map(...)}); docs should be static.
• Keep content pure Markdown; only use components available in theme.

Recommended Standard Template

Frontmatter template:

---
title: Page Title
description: Brief description
---

Content template:

• Args: { id, name? }
• Returns: [{ _id, name }]

// Code block example (if needed)
type CreateArgs = { name: string; note?: string };

Pre-commit Checklist

• File has frontmatter opened/closed with --- fully.
• No bare {}, [], <> in text (wrapped with backticks).
• No strange JSX; if used, ensure component exists.
• Use ASCII for special symbols (-> instead of special arrow). Vietnamese with accents is OK.
• Test build locally: run dev server and open the docs page just added/edited.

Quick Fix When Errors Occur

• Identify error line in log (line number + MDX file).
• Check for {, }, [, ], <, > characters outside backticks.
• Temporarily wrap entire section with special characters in code block to eliminate cause.
• If file has many special symbols, replace with ASCII first, then gradually add back.