Skip to content

Troubleshooting

This section documents the most common issues encountered while maintaining the EPMware MkDocs documentation sites, along with their causes and solutions. These are drawn from real issues that arose during the development and maintenance of the guides.

Troubleshooting Topics

  • Broken Links & 404 Errors — The most frequent category of issues; covers relative path problems, HTML vs markdown link differences, and cross-section navigation
  • Build & Deployment Errors — YAML parse errors, missing plugins, GitHub Actions failures, and deprecation warnings
  • Formatting & Display Issues — Icons not rendering, admonitions not displaying, image caption problems, and dark mode styling issues

Quick Diagnostic Checklist

When something goes wrong, work through this checklist:

  1. Does mkdocs serve start without errors? If not, you have a YAML or configuration issue — see Build Errors.

  2. Does the page load but links give 404? This is a link path issue — see Broken Links.

  3. Does the content load but look wrong? This is a formatting issue — see Formatting Issues.

  4. Does it work locally but not on the live site? Check that you pushed all changes and the GitHub Actions build succeeded. See the deployment section of Build Errors.

Check the Browser URL

When a link produces a 404, always look at the URL in the browser address bar. Compare it to what you expected. The difference between the actual and expected URL tells you exactly how to fix the link path.