Troubleshooting

Common issues and solutions when building portfolio documentation sites.

Setup issues

Python command not found

Problem: python: command not found or python3: command not found

Solutions:

1. Check if Python is installed:

   which python3
   python3 --version
   

2. Install Python:

3. macOS: brew install python3
4. Ubuntu or Debian: sudo apt-get install python3

5. Windows: Download from python.org

6. Use full path:

   /usr/bin/python3 -m pip install mkdocs
   

Virtual environment activation fails

Problem (Windows): cannot be loaded because running scripts is disabled

Solution:

# Run PowerShell as Administrator
Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser

Problem (macOS or Linux): source: command not found

Solution:

# Use correct shell activation
source venv/bin/activate  # bash or zsh
. venv/bin/activate       # alternative

MkDocs not found after installation

Problem: mkdocs: command not found after pip install mkdocs

Solutions:

1. Verify virtual environment is activated:

   which python
   # Should show path ending in /venv/bin/python
   

2. Reinstall in active environment:

   pip install --upgrade pip
   pip install mkdocs mkdocs-material
   

3. Check Python scripts directory in PATH:

   echo $PATH | grep venv
   

Material theme not loading

Problem: Site displays but theme does not apply

Solutions:

1. Verify Material is installed:

   pip list | grep mkdocs-material
   

2. Check mkdocs.yml theme configuration:

   theme:
     name: material  # Must be exactly "material"
   

3. Reinstall Material theme:

   pip uninstall mkdocs-material
   pip install mkdocs-material
   

4. Clear MkDocs build cache:

   rm -rf site/
   mkdocs build
   

MkDocs server issues

Port already in use

Problem: [Errno 48] Address already in use

Solutions:

1. Kill existing MkDocs processes:

   # macOS or Linux
   pkill -f mkdocs
   
   # Windows
   taskkill /F /IM python.exe
   

2. Use different port:

   mkdocs serve -a localhost:8001
   

3. Find and kill process using port:

   # macOS or Linux
   lsof -ti:8000 | xargs kill -9
   
   # Windows
   netstat -ano | findstr :8000
   taskkill /PID <process_id> /F
   

Changes not appearing in browser

Problem: Edits not reflected when viewing local site

Solutions:

1. Force refresh browser:
2. Chrome or Firefox: Ctrl+Shift+R (Windows or Linux)
3. Chrome or Firefox: Cmd+Shift+R (macOS)

4. Safari: Cmd+Option+R

5. Restart MkDocs server:

   # Stop with Ctrl+C
   mkdocs serve
   

6. Clear browser cache completely

7. Check file was actually saved in editor

Build errors in terminal

Problem: mkdocs build or mkdocs serve shows errors

Common causes and solutions:

Broken link error:

WARNING - Doc file 'page.md' contains a link to 'other.md', 
          but the target 'other.md' is not found

Solution: Fix the link or create the missing file

YAML syntax error:

ERROR   - Config file 'mkdocs.yml' is invalid.
          Error: ...

Solution: Check YAML indentation and syntax. Use YAML validator.

Markdown parsing error:

ERROR   - Error reading page 'file.md'

Solution: Check for invalid Markdown syntax in the file

GitHub Pages deployment issues

gh-deploy command fails

Problem: mkdocs gh-deploy shows errors

Solutions:

1. Verify Git repository is initialized:

   git status
   # Should show "On branch main"
   

2. Check remote is configured:

   git remote -v
   # Should show origin with GitHub URL
   

3. Verify credentials:

   git config user.name
   git config user.email
   

4. Push access issues:

5. Use personal access token instead of password
6. Check repository permissions
7. Verify you own the repository

Site not updating after deployment

Problem: Changes deployed but site shows old content

Solutions:

1. Wait 2-3 minutes for GitHub Pages to rebuild

2. Force refresh browser (clear cache):

3. Ctrl+Shift+R or Cmd+Shift+R

4. Check GitHub Actions:

5. Go to repository Actions tab
6. Look for "pages build and deployment" workflow

7. Check for errors

8. Verify gh-pages branch updated:

9. Go to repository on GitHub
10. Switch to gh-pages branch

11. Check commit timestamp

12. Clear DNS cache:

    # macOS
    sudo dscacheutil -flushcache; sudo killall -HUP mDNSResponder
    
    # Windows
    ipconfig /flushdns
    
    # Linux
    sudo systemd-resolve --flush-caches
    

404 error on GitHub Pages

Problem: Site shows "404 There is not a GitHub Pages site here."

Solutions:

1. Verify repository is public:
2. Go to repository Settings
3. Check visibility under "Danger Zone"

4. Change to Public if needed

5. Check GitHub Pages settings:

6. Go to Settings → Pages
7. Source should be "Deploy from a branch"
8. Branch should be gh-pages / / (root)

9. Click Save

10. Verify gh-pages branch exists:

    git branch -a
    # Should list remotes/origin/gh-pages
    

11. Run deployment again:

    mkdocs gh-deploy --force
    

Custom domain not working

Problem: Custom domain shows error or does not connect

Solutions:

1. Wait for DNS propagation (24-48 hours after setup)

2. Check DNS configuration:

   dig yourname.dev
   # Should show GitHub Pages IP addresses
   

3. Verify GitHub Pages custom domain setting:

4. Go to Settings → Pages
5. Custom domain field shows your domain

6. "Enforce HTTPS" should be enabled

7. Check domain registrar settings:

8. A records point to GitHub Pages IPs

9. CNAME record for www points to username.github.io

10. Remove and re-add custom domain:

11. Delete custom domain in GitHub settings
12. Wait 5 minutes
13. Add it back and save

AI and API issues

API rate limit exceeded

Problem: AI provider shows rate limit errors

Solutions:

1. Wait for rate limit to reset:
2. Check provider dashboard for reset time

3. Anthropic and OpenAI show limits in console

4. Reduce frequency of requests:

5. Generate content section by section
6. Save prompts and reuse outputs

7. Use smaller content chunks

8. Upgrade to paid tier:

9. Free tiers have strict rate limits
10. Paid tiers offer higher limits

Invalid API key error

Problem: 401 Unauthorized or Invalid API key

Solutions:

1. Check for extra spaces:

   # Bad: "sk-ant-123 " (trailing space)
   # Good: "sk-ant-123"
   

2. Verify correct provider:

3. Anthropic keys start with sk-ant-

4. OpenAI keys start with sk-

5. Check key is active:

6. Log into provider console
7. Verify key has not been revoked

8. Check billing is set up

9. Regenerate key:

10. Create new API key
11. Update your .env file
12. Try again

AI generates incorrect technical information

Problem: AI output contains technical errors

Solutions:

This is expected behavior. Always:

1. Verify technical accuracy manually
2. Test all code examples
3. Check API specifications
4. Research unfamiliar concepts
5. Consult official documentation

AI is a drafting tool requiring human verification.

AI output too generic or vague

Problem: Generated content lacks specific details

Solutions:

1. Provide more detailed prompts:
2. Include specific technical requirements
3. Give concrete examples

4. Specify exact format needed

5. Generate section by section:

6. Break documentation into smaller pieces

7. Provide detailed context for each section

8. Add specifics manually:

9. Use AI for structure
10. Add technical details yourself
11. Incorporate domain knowledge

Content and writing issues

Documentation reads as AI-generated

Problem: Content feels generic or lacks authentic voice

Solutions:

1. Edit heavily for voice:
2. Remove generic phrases
3. Add specific examples
4. Include personality

5. Use authentic language

6. Add domain expertise:

7. Include insider knowledge
8. Reference real-world scenarios
9. Explain trade-offs

10. Share experiences

11. Review and rewrite:

12. Use AI as first draft only
13. Rewrite in your own voice
14. Add unique perspective

Code examples do not work

Problem: Code samples generate errors

Solutions:

1. Test all examples:
2. Run every code sample
3. Fix syntax errors
4. Verify imports

5. Check versions

6. Include necessary context:

   # Add all required imports
   import requests
   
   # Show complete working example
   response = requests.get('https://api.example.com')
   

7. Add error handling:

   try:
       response = requests.get('https://api.example.com')
       response.raise_for_status()
   except requests.exceptions.RequestException as e:
       print(f"Error: {e}")
   

Navigation structure confusing

Problem: Site organization unclear or illogical

Solutions:

1. Review information architecture:
2. Group related content
3. Use clear categories

4. Limit nesting depth (3 levels maximum)

5. Test with fresh eyes:

6. Ask someone to review
7. Observe where they get confused

8. Simplify structure

9. Add navigation aids:

10. Breadcrumbs (enabled by default in Material)
11. Cross-references between pages
12. Clear page titles

Markdown formatting broken

Problem: Content does not display correctly

Common issues:

Headings not rendering:

# Bad: #No space after hash
# Good: # Space after hash

Lists not formatting:

Bad:
-No space after dash
- Inconsistent indentation
  - Two spaces
    - Four spaces

Good:
- Space after dash
- Consistent indentation
  - Two spaces for nesting
    - Two more spaces

Code blocks not highlighting:

Bad:
```
code without language
```

Good:
```python
code with language specified
```

Links not working:

Bad: [Link](page.md)  # Wrong extension
Good: [Link](page.md)  # Use .md not .html

Performance and optimization issues

Site builds slowly

Problem: mkdocs build takes long time

Solutions:

1. Remove large files from docs:
2. Move images to external hosting
3. Compress images before including

4. Limit PDF file sizes

5. Simplify navigation:

6. Reduce number of pages
7. Flatten deep nesting

8. Remove unused plugins

9. Use .gitignore to exclude build artifacts:

   site/
   __pycache__/
   

Site loads slowly

Problem: Pages take long time to display

Solutions:

1. Optimize images:
2. Compress images (use TinyPNG, ImageOptim)
3. Use appropriate formats (WebP for modern browsers)

4. Limit image dimensions

5. Minimize custom CSS:

6. Remove unused styles
7. Avoid large font files

8. Use system fonts

9. Enable Material theme optimization:

   theme:
     name: material
     features:
       - navigation.instant  # Faster page loading
   

Get help

If you are still stuck:

1. Check documentation

• MkDocs documentation
• Material for MkDocs
• GitHub Pages documentation

2. Search for similar issues

• MkDocs GitHub issues
• Material GitHub issues
• Stack Overflow with mkdocs tag

3. Ask for help

Create new issue with:

• Error message (full text)
• Steps to reproduce
• Your environment (OS, Python version, MkDocs version)
• Relevant configuration (with sensitive data removed)

Do not share: - API keys - Personal access tokens - Private repository details

---

Open an issue if you encounter problems not covered here.