Code Editor Troubleshooting

Resolve common issues when working with Documentation.AI using code editors, Git workflows, and the publishing process.

Build and Deployment Issues

Documentation.AI Build Failures

Issue: Build fails after pushing changes

Common causes:

• Invalid documentation.json syntax
• Missing files referenced in navigation
• Malformed front matter in MDX files
• Broken internal links

Solutions:

1. Check build logs in Documentation.AI dashboard
2. Validate JSON using online validator or cat documentation.json | jq .
3. Verify navigation paths - ensure all referenced files exist
4. Check front matter format in all MDX files:
   ---
   title: Page Title
   description: Page description
   ---
   

Repository Connection Issues

Issue: Documentation.AI not detecting Git pushes

Solutions:

• Verify repository is correctly connected in dashboard
• Check branch configuration matches your default branch
• Ensure webhooks are properly configured
• Try disconnecting and reconnecting repository

Content and Navigation Issues

Missing Pages in Navigation

Issue: New pages don't appear in published documentation

Solutions:

1. Add to documentation.json:

   {
     "navigation": {
       "groups": [
         {
           "group": "API Reference",
           "pages": [
             {
               "title": "New Endpoint",
               "path": "api/new-endpoint"
             }
           ]
         }
       ]
     }
   }
   

2. Verify file exists at correct path with .mdx extension

3. Check for typos in file paths (paths are case-sensitive)

Broken Internal Links

Issue: Internal links return 404 errors

Solutions:

• Use relative paths: [Link](../section/page) not [Link](/section/page.mdx)
• Remove .mdx extension from links
• Verify target files exist in correct locations

Image and Media Issues

Images Not Displaying

Issue: Images show broken or don't load

Solutions:

1. Use Documentation.AI CDN URLs:

   <Image 
     uid="generated-uid"
     src="https://cdn-url.com/image.png" 
     alt="Description"
   />
   

2. Upload via web editor first to get proper CDN URLs

3. Check external URLs are accessible and properly formatted

4. Verify Image component syntax matches Documentation.AI format

Video Embedding Problems

Issue: Videos don't embed or play correctly

Solutions:

• Use Documentation.AI Video component syntax
• Verify external video URLs are embeddable
• Check video platform supports embedding (YouTube, Vimeo, etc.)

Git and Sync Issues

Merge Conflicts

Issue: Conflicts when merging branches, especially in documentation.json

Solutions:

1. Use your editor's merge tools - VS Code and Cursor have built-in conflict resolution
2. Coordinate navigation changes - Avoid multiple people editing documentation.json simultaneously
3. Keep branches up to date with main branch to reduce conflicts

Changes Not Reflecting

Issue: Pushed changes don't appear in published documentation

Solutions:

1. Check build status in Documentation.AI dashboard
2. Verify correct branch is configured for deployment
3. Wait for build completion - builds may take a few minutes
4. Clear browser cache if changes appear to be cached

Editor and Performance Issues

Slow Editor Performance

Issue: Code editor running slowly with documentation project

Solutions:

• Exclude unnecessary files from search and file watching
• Use workspace settings to optimize for documentation editing
• Close unused files and limit open editor tabs
• Disable heavy extensions when working on documentation

MDX Syntax Issues

Issue: MDX files showing syntax errors or not highlighting properly

Solutions:

1. Install MDX extensions for your editor
2. Configure file associations:
   {
     "files.associations": {
       "*.mdx": "markdown"
     }
   }
   

3. Restart editor after installing extensions

Getting Help

Debug Information to Collect

When reporting issues, include:

System information:

• Operating system and version
• Code editor and version (VS Code, Cursor)
• Git version

Documentation.AI specific:

• Project/repository name
• Build logs from dashboard
• Error messages (full text)
• Steps to reproduce the issue

Files to check:

• documentation.json configuration
• Front matter in problematic MDX files
• Recent Git commits that may have caused issues

Common Solutions

Quick Fixes

Build failing:

1. Check documentation.json for syntax errors
2. Verify all navigation paths reference existing files
3. Ensure front matter is properly formatted in all MDX files

Page not appearing:

1. Add page to documentation.json navigation
2. Check file path matches navigation configuration exactly
3. Verify file has proper front matter

Images not loading:

1. Use Documentation.AI CDN URLs from web editor uploads
2. Verify Image component syntax is correct
3. Check that external image URLs are accessible

Emergency Rollback

If your site is broken:

# Quick rollback to previous working version
git revert HEAD
git push origin main

Support Resources

• Documentation.AI Dashboard - Check build logs and status
• Component Reference - Documentation.AI Components
• Configuration Reference - Site and Page configuration

Next Steps

• Overview: Return to code editor basics
• Publishing: Understand the deployment process
• Git Workflow: Master collaboration workflows