Task

Diagnose and resolve megadoc documentation issues including build failures, missing documentation, broken links, and integration problems.

Mandatory Requirements

Requirement	Rule	Rationale
Submodule Init	MUST run git submodule update --init --recursive before builds	Ensures all content present
Strict Mode	MUST use mkdocs build --strict for all builds	Catches warnings as errors
Local Testing	MUST test submodule build in isolation first	Identifies source of failure
YAML Validation	MUST validate mkdocs.yml syntax before debugging nav	Eliminates parser errors first
Path Verification	MUST verify file exists before investigating nav references	Confirms actual vs expected state

Prohibited Patterns

Pattern	Prohibition	Alternative
Skipping Submodule Init	NEVER troubleshoot without running git submodule update first	Always init before diagnosis
Non-Strict Builds	NEVER use mkdocs build without --strict flag	Warnings hide real issues
Editing Parent for Submodule Issues	NEVER modify parent mkdocs.yml to fix submodule problems	Fix in submodule repository
Hardcoded Paths	NEVER use absolute paths in mkdocs.yml navigation	Use relative paths only
Ignoring Build Order	NEVER build parent without verifying submodule builds first	Test submodules in isolation

Context

Megadoc issues fall into several categories:

1. Submodule documentation problems - Missing or invalid docs in repository
2. Build failures - Errors during mkdocs build
3. Integration issues - Submodule docs don't appear in megadoc
4. Navigation problems - Broken or incorrect navigation structure
5. Link issues - Broken internal or external links

Troubleshooting Guide

Issue 1: Documentation Doesn't Appear in Megadoc

Symptoms

• Submodule added to megadoc
• Build succeeds
• Documentation doesn't show up in navigation

Diagnosis Steps

Step 1: Verify submodule exists

cd /path/to/ohemr-epic-megadoc
ls submodules/{repository-name}/

Expected: Directory exists with content If missing: Submodule not properly added

Fix:

git submodule add https://github.com/optum-tech-compute/{repo} submodules/{repo}
git submodule update --init --recursive

Step 2: Check mkdocs.yml exists

ls submodules/{repository-name}/mkdocs.yml

Expected: File exists If missing: Repository lacks megadoc configuration

Fix: Run megadoc-stub-generator in the submodule repository

Step 3: Verify docs/index.md exists

ls submodules/{repository-name}/docs/index.md

Expected: Landing page exists If missing: Documentation structure incomplete

Fix: Create docs/index.md with proper front matter

Step 4: Check parent navigation

grep "{repository-name}" mkdocs.yml

Expected: !include directive references this submodule If missing: Navigation doesn't include submodule

Fix (explicit include):

nav:
  - Repository: '!include submodules/{repository-name}/mkdocs.yml'

Fix (wildcard pattern):

nav:
  - Category: '*include submodules/{pattern}-*/mkdocs.yml'

Step 5: Test submodule build in isolation

cd submodules/{repository-name}
mkdocs build

Expected: Build succeeds If fails: Fix errors in submodule first

Common Causes

1. Missing mkdocs.yml: Add stub configuration
2. Missing docs/index.md: Create landing page
3. Invalid YAML: Fix syntax errors in mkdocs.yml
4. Not in navigation: Add !include or adjust wildcard pattern
5. Submodule not updated: Run git submodule update --remote

Issue 2: Build Fails with "File Not Found" Error

Symptoms

Error: File not found: docs/getting-started.md

Diagnosis

Step 1: Check error message

• Note the exact file path mentioned
• Identify which repository it belongs to (parent or submodule)

Step 2: Verify file exists

# For parent megadoc
ls docs/getting-started.md

# For submodule
ls submodules/{repo}/docs/getting-started.md

Step 3: Check navigation references

grep "getting-started.md" mkdocs.yml

Solutions

If file genuinely missing: Create the file with proper front matter

If file exists but path wrong: Update navigation to use correct path

If file referenced in submodule nav but doesn't exist: Fix submodule's mkdocs.yml navigation

Issue 3: Build Fails with YAML Syntax Error

Symptoms

yaml.scanner.ScannerError: mapping values are not allowed here

Diagnosis

Step 1: Identify which file Error message usually indicates file:

• mkdocs.yml (parent)
• submodules/{repo}/mkdocs.yml (submodule)
• Front matter in markdown file

Step 2: Validate YAML syntax

# For mkdocs.yml
python -c "import yaml; yaml.safe_load(open('mkdocs.yml'))"

# For submodule
python -c "import yaml; yaml.safe_load(open('submodules/{repo}/mkdocs.yml'))"

Common YAML Errors

Indentation issues:

❌ Bad:
nav:
- Home: index.md
  - Getting Started: getting-started.md

✅ Good:
nav:
  - Home: index.md
  - Getting Started: getting-started.md

Missing colons:

❌ Bad:
site_name my-repo

✅ Good:
site_name: my-repo

Unquoted special characters:

❌ Bad:
description: This: is a problem

✅ Good:
description: "This: is a problem"

Incorrect list syntax:

❌ Bad:
tags: [tag1, tag2, tag3]  # In front matter

✅ Good:
tags:
  - tag1
  - tag2
  - tag3

Solution

1. Find the syntax error
2. Fix indentation/formatting
3. Re-validate YAML
4. Rebuild

Issue 4: "Edit on GitHub" Links Point to Wrong Place

Symptoms

• Click "Edit on GitHub" button
• Get 404 error or wrong file

Diagnosis

Step 1: Check edit_uri in submodule

grep "edit_uri" submodules/{repo}/mkdocs.yml

Expected: edit_uri: edit/{branch}/docs

Step 2: Verify default branch

cd submodules/{repo}
git symbolic-ref refs/remotes/origin/HEAD

Solutions

If branch name wrong:

# Update edit_uri to match actual default branch
edit_uri: edit/main/docs     # For main branch
edit_uri: edit/develop/docs  # For develop branch
edit_uri: edit/master/docs   # For master branch

If docs folder in different location:

edit_uri: edit/main/documentation  # If docs are in /documentation
edit_uri: edit/main/              # If docs are in root

Issue 5: Wildcard Pattern Matches Wrong Repositories

Symptoms

• Too many or too few repos appear in navigation
• Unexpected repos included in category

Diagnosis

Step 1: Test glob pattern

ls submodules/{pattern}*/mkdocs.yml

Example:

# See which repos match pattern
ls submodules/ohemr-ansible-role-*/mkdocs.yml

# Count matches
ls submodules/ohemr-ansible-role-*/mkdocs.yml | wc -l

Step 2: Examine matched repositories

# List all matching repo names
ls -d submodules/ohemr-ansible-role-*/

Solutions

If pattern too broad:

# Make more specific
❌ Too broad:
  - Repos: '*include submodules/ohemr-*/mkdocs.yml'

✅ More specific:
  - Terraform: '*include submodules/ohemr-terraform-module-*/mkdocs.yml'
  - Ansible: '*include submodules/ohemr-ansible-role-*/mkdocs.yml'

If pattern too narrow:

# Broaden or use multiple patterns
❌ Too narrow:
  - Ansible Roles: '*include submodules/ohemr-ansible-role-auth-*/mkdocs.yml'

✅ Broader:
  - Ansible Roles: '*include submodules/ohemr-ansible-role-*/mkdocs.yml'

If specific repos should be excluded: Use explicit includes instead of wildcard, or adjust naming

Issue 6: Broken Internal Links

Symptoms

• Click link in documentation
• Get 404 error
• Build warning: "Documentation file 'X' not found"

Diagnosis

Step 1: Identify broken link Note the link source and target:

• Source: Where the link appears
• Target: What file it's trying to link to

Step 2: Check if target exists

# If relative link
ls docs/{path/to/target.md}

# If from submodule
ls submodules/{repo}/docs/{path/to/target.md}

Step 3: Check link syntax

# Extract link from markdown

[Link Text](path/to/file.md)

Common Link Issues

Absolute paths in submodule:

❌ Bad (breaks in submodule context):
[Config](/docs/reference/config.md)

✅ Good (relative):
[Config](./reference/config.md)
[Config](../reference/config.md)

Wrong relative path:

# From docs/how-to/deploy.md linking to docs/reference/config.md

❌ Bad:
[Config](reference/config.md)

✅ Good:
[Config](../reference/config.md)

Missing file extension:

❌ Bad:
[Config](config)

✅ Good:
[Config](config.md)

File moved but links not updated:

# Find all references to moved file
grep -r "old-filename.md" docs/

Solutions

1. Fix link paths - Use correct relative paths
2. Create missing files - If target should exist, create it
3. Update references - If file moved, update all links
4. Use link checker:

# Install link checker
pip install mkdocs-htmlproofer-plugin

# Add to mkdocs.yml (parent only)
plugins:
  - htmlproofer

# Build with link checking
mkdocs build

Issue 7: Navigation Structure Is Messy

Symptoms

• Repos appear in wrong order
• Navigation too deep or too shallow
• Section names unclear

Diagnosis

Step 1: Review current navigation

# Check parent mkdocs.yml nav structure
cat mkdocs.yml | grep -A 50 "^nav:"

Step 2: Understand monorepo plugin behavior

• Explicit includes appear in defined order
• Wildcard includes appear alphabetically by site_name
• Nested navigation creates hierarchy

Solutions

Reorder explicit includes:

nav:
  - Home: index.md
  - Getting Started: getting-started.md
  - Infrastructure:
      - Important Module: '!include submodules/important/mkdocs.yml'
      - Other Module: '!include submodules/other/mkdocs.yml'

Control wildcard order via site_name:

# In submodule mkdocs.yml, site_name determines sort order
site_name: "01 - Critical Role"  # Appears first
site_name: "02 - Standard Role"  # Appears second
site_name: "zzz - Deprecated"    # Appears last

Adjust navigation depth:

# Too flat
nav:
  - All Modules: '*include submodules/*/mkdocs.yml'

# Better organized
nav:
  - Terraform:
      - Network: '*include submodules/ohemr-terraform-module-network-*/mkdocs.yml'
      - Compute: '*include submodules/ohemr-terraform-module-compute-*/mkdocs.yml'
  - Ansible:
      - Roles: '*include submodules/ohemr-ansible-role-*/mkdocs.yml'

Issue 8: Submodule Changes Don't Appear

Symptoms

• Updated documentation in submodule repo
• Changes don't show up in megadoc site

Diagnosis

Step 1: Check submodule commit

cd /path/to/ohemr-epic-megadoc
git submodule status submodules/{repo}

Shows: Current commit hash submodule is pinned to

Step 2: Check if updates pushed

cd submodules/{repo}
git log --oneline -5
git remote -v

Solutions

Update submodule to latest:

cd /path/to/ohemr-epic-megadoc

# Update single submodule
git submodule update --remote submodules/{repo}

# Update all submodules
git submodule update --remote

# Commit updated references
git add submodules/
git commit -m "Update submodules to latest"
git push

Wait for auto-update (if configured):

• Megadoc may have scheduled job to update submodules
• Check .github/workflows/build-docs.yml

Issue 9: Fallback Documentation Appears Instead of Real Docs

Symptoms

• Documentation shows placeholder content
• Notice "This is auto-generated fallback documentation"

Diagnosis

Step 1: Check if real docs exist

ls submodules/{repo}/mkdocs.yml
ls submodules/{repo}/docs/index.md

Step 2: Check fallback directory

ls .megadoc/fallbacks/{repo}/

If fallback exists: Megadoc validation detected missing/invalid docs

Solutions

Fix missing documentation:

1. Go to submodule repository
2. Run megadoc-stub-generator
3. Create proper mkdocs.yml and docs/
4. Push changes
5. Update submodule in megadoc
6. Rebuild

Remove fallback after fix:

# Fallback will be automatically ignored once real docs exist
rm -rf .megadoc/fallbacks/{repo}

Check GitHub issues:

• Megadoc auto-creates issues in repos with missing docs
• Check repository issues for "Add megadoc-compliant documentation"

Issue 10: Build Succeeds But Site Looks Wrong

Symptoms

• No build errors
• Site renders but looks incorrect
• Formatting issues
• Missing styling

Diagnosis

Step 1: Check theme configuration

# In parent mkdocs.yml
theme:
  name: material

Step 2: Verify plugins loaded

mkdocs build --verbose

Look for:

• Plugin loading messages
• Theme initialization
• Extension registration

Step 3: Test in browser

mkdocs serve

Visit http://localhost:8000 and check:

• Styles load (check browser console for errors)
• Navigation works
• Search works
• Code highlighting works

Common Causes

Missing dependencies:

pip install mkdocs-material mkdocs-monorepo-plugin

Browser cache:

# Hard refresh in browser
# Chrome/Firefox: Ctrl+Shift+R (Windows/Linux) or Cmd+Shift+R (Mac)

Conflicting styles:

• Check if submodule has extra_css defined (should be removed)
• Verify no custom CSS conflicts

Diagnostic Commands Cheat Sheet

# Validate YAML
python -c "import yaml; yaml.safe_load(open('mkdocs.yml'))"

# Test build
mkdocs build --strict

# Verbose build
mkdocs build --verbose

# Serve locally
mkdocs serve

# Check submodule status
git submodule status

# Update submodules
git submodule update --remote

# List submodule files
ls submodules/{repo}/

# Test glob pattern
ls submodules/{pattern}*/mkdocs.yml

# Find broken links
grep -r "](.*\.md)" docs/

# Check git default branch
git symbolic-ref refs/remotes/origin/HEAD

# Validate front matter in all docs
for file in docs/**/*.md; do
  echo "Checking $file"
  python -c "import yaml, sys; yaml.safe_load(open('$file').read().split('---')[1])" 2>&1 || echo "ERROR in $file"
done

Getting Help

If troubleshooting doesn't resolve the issue:

1. Gather diagnostic information:

   • Full error message
   • Relevant mkdocs.yml content
   • Repository name and structure
   • Build output (mkdocs build --verbose)

2. Check documentation:

   • MkDocs Documentation
   • Material Theme Docs
   • Monorepo Plugin

3. Contact megadoc maintainers:

   • GitHub: @epic-platform-sre
   • Create issue in ohemr-epic-megadoc
   • Provide diagnostic information above

Expected Output

Successful Troubleshooting

✅ **Issue Resolved**

**Problem**: Documentation wasn't appearing in megadoc navigation

**Root Cause**: Submodule mkdocs.yml missing repo_url field

**Solution Applied**:

1. Added repo_url to submodules/{repo}/mkdocs.yml
2. Rebuilt megadoc: `mkdocs build --strict`
3. Verified documentation now appears

**Verification**:

- ✅ Build succeeds
- ✅ Documentation in navigation
- ✅ Links work correctly
- ✅ Edit buttons point to correct repo

Unresolved Issue

⚠️ **Issue Partially Resolved**

**Problem**: Some links still broken after fixes

**What Was Fixed**:

- ✅ Updated 5 broken relative links
- ✅ Created 2 missing files

**Remaining Issues**:

- ❌ 3 links to external repos return 404
- ⚠️ 1 link points to private repository

**Next Steps**:

1. Verify external repositories exist
2. Update links to correct URLs
3. Remove or update private repository links

**Need Help**: Contact repository owners for correct URLs

Notes

• Always test builds locally before pushing changes
• Use --strict flag to catch warnings as errors
• Check submodule updates regularly
• Validate documentation after any structural changes
• Keep diagnostic information for complex issues