Troubleshooting & FAQ

This section provides guidance on getting help, reporting issues, and accessing additional resources when working with the RMC Software Documentation project.

Refer to Earlier Chapters

Most troubleshooting information and detailed instructions are covered in the earlier chapters of this guide. If you encounter issues, please review the relevant chapter first:

• Installation issues: Getting Started
• Project structure questions: Project Structure
• MDX syntax help: Creating and Editing Pages
• Component usage: React Components Reference
• Versioning questions: Versioning System

---

Quick Diagnostic Checklist

Before seeking help, verify these common requirements:

• ✓ Node.js version 18.0 or later installed
• ✓ Ran npm install successfully
• ✓ No red error messages in terminal
• ✓ File is in correct location (docs/ folder)
• ✓ File has .mdx extension
• ✓ Front matter properly formatted
• ✓ All component imports at top of file
• ✓ All components have required props
• ✓ All file paths start with /
• ✓ Cleared cache: rm -rf .docusaurus
• ✓ Restarted dev server
• ✓ Hard refreshed browser (Ctrl+Shift+R)

---

Getting Additional Help

Where to Report Bugs

For Documentation Content Issues:

• Open an issue on the GitHub repository
• Include page URL or file path
• Describe the problem clearly
• Suggest corrections if applicable

For Build/Technical Issues:

• Search existing GitHub issues first
• Review the relevant chapter for guidance
• Create a new issue with:
  • Error message (full text)
  • Steps to reproduce
  • System information (OS, Node version)
  • Screenshots if applicable

---

Who to Contact

Project Administrator:

• Adam Gohs - adam.c.gohs@usace.army.mil

For General Questions:

• Review this documentation guide first
• Search the GitHub repository
• Open an issue for unresolved questions

---

Additional Resources

• Docusaurus - docusaurus.io/docs - Static site generator documentation
• MDX - mdxjs.com/docs - MDX format and syntax guide
• Markdown Guide - markdownguide.org - Markdown syntax reference
• React - react.dev - React component documentation (advanced)
• Git - git-scm.com/doc - Version control documentation
• Node.js - nodejs.org/docs - Node.js runtime documentation

---

Common Issues Quick Reference

Development server won't start:

• See Getting Started for installation troubleshooting
• Clear cache: rm -rf .docusaurus and restart

Changes not appearing:

• Hard refresh browser: Ctrl+Shift+R (Windows/Linux) or Cmd+Shift+R (Mac)
• Check terminal for build errors
• Restart dev server

Component not rendering:

• Verify import statement at top of file: import Component from '@site/src/components/Component';
• Check component props in React Components Reference
• Ensure component is self-closing: <Component ... />

Images not displaying:

• Verify path starts with /: /figures/software/v1.0/image.png
• Check file exists in static/figures/ folder
• Clear browser cache

Figure/table numbers incorrect:

• Restart dev server (counters update automatically on startup)

Cross-references broken:

• Verify keys match exactly between component and reference
• Ensure both are in the same document

---

Need More Help?

1. Review the relevant chapter in this guide
2. Search the GitHub Issues
3. Contact the project administrator with detailed information