Common issues and solutions for documentation development.

Page Not Appearing

Check:

  • File is .md extension
  • Front matter is valid YAML
  • File is in correct directory structure
  • File is in correct folder

Fix: Move file to correct directory position (ordering is automatic based on file structure)

Icons Not Showing

Check:

  • Icon name matches Material Symbols
  • sidebarIcons = true in hugo.toml
  • Icon field is lowercase: icon: "settings"

Build Errors 

hugo server

Look for error messages about:

  • Invalid YAML
  • Missing front matter
  • Broken links

Next Steps