Troubleshooting

Common issues and solutions for EmberDocs.

Build Issues

Error: Cannot find module 'flexsearch'

Solution: Install the missing dependency:

npm install flexsearch
npm install --save-dev @types/flexsearch

Error: Document path not found

Issue: Your markdown files are not being discovered.

Solution:

1. Check file paths are correct
2. Ensure files have .md extension
3. Verify frontmatter is valid YAML

Build timeout

Solution: Increase build timeout in next.config.js:

export default {
  staticPageGenerationTimeout: 300, // seconds
};

Search Issues

Search returns no results

1. Check that search index was built: npm run build:search
2. Verify public/search-index.json exists
3. Ensure documents have proper frontmatter

Search is slow

Solution:

• Reduce maxBodyWords in search config
• Limit number of documents indexed
• Use search debouncing

Theme/Styling

Dark mode not working

1. Check data-theme attribute:
   javascriptCopy

   console.log(document.documentElement.getAttribute('data-theme'));

2. Verify CSS variables are set
3. Clear browser cache

Fonts not loading

Solution:

1. Check Google Fonts links in layout.tsx
2. Verify network requests in browser DevTools
3. Check font-family in CSS

Navigation Issues

Breadcrumbs not showing

Solution:

• Ensure document slug matches file path
• Check that navigation structure is generated
• Verify getBreadcrumbs() function

TOC not updating on scroll

Solution:

• Check IntersectionObserver browser support
• Verify headings have ID attributes
• Ensure JavaScript is enabled

Performance

Page loads slowly

Solutions:

1. Optimize images with Next.js Image
2. Enable code splitting with dynamic()
3. Use @next/bundle-analyzer for bundle size analysis (install separately if needed)

Search is laggy

Solution:

• Debounce search queries
• Reduce search result count
• Implement virtual scrolling for results

Development Server

Port already in use

npm run dev -- -p 3001

Hot reload not working

# Clear cache and restart
rm -rf .next
npm run dev

TypeScript errors

# Type check
npm run typecheck

# Clear TypeScript cache
rm -rf .next
npm run typecheck

Deployment

Build fails on deploy

1. Check Node.js version matches locally
2. Clear build cache
3. Check environment variables

Assets not loading

Ensure assets are in public/ directory and referenced correctly:

![image](/images/my-image.png)

Browser Compatibility

EmberDocs supports:

• Chrome/Edge 90+
• Firefox 88+
• Safari 14+

For older browsers, use a transpiler.

Getting Help

If issues persist:

1. Check GitHub Issues
2. Create a minimal reproduction
3. Include:
   • Node.js version
   • EmberDocs version
   • Steps to reproduce
   • Error message/screenshot