Troubleshooting

Common Errors

Here are solutions for common issues you might encounter:

Error: SUMMARY.md file not found

This typically means the --summary flag points to a non-existent file. Verify the path:

$ ls src/SUMMARY.md

Make sure the --summary argument is relative to the project root (the directory containing your .nimble file).

Error: importdoc for 'X' is not used

This warning appears when a file listed in SUMMARY.md has an .. importdoc:: directive that references a file not in the SUMMARY.md list. The imported file is still processed, but the warning indicates it won't appear in the navigation unless added to SUMMARY.md.

Performance Tips

For large books (100+ pages), consider these optimizations:

• Use --fullTextIndexation:on only for the final build. During development, omit it for faster builds
• Keep images and other assets outside the src/ directory. They don't need to be processed by the compiler
• Split very long pages into smaller ones. Each page is processed independently in the current architecture