mkdocs-common-issues

vamseeachanta

Aktualisiert Yesterday

10 Ansichten

Anderegeneral

Über

Diese Fähigkeit bietet Lösungen für häufige MkDocs-Probleme wie Build-Fehler, Mermaid-Diagramm-Rendering und Suchfunktionsstörungen. Sie stellt einsatzbereite Konfigurationssnippets und Schritte zur Fehlerbehebung für Entwickler bereit. Nutzen Sie diese Referenz bei typischen MkDocs-Bereitstellungs- oder Renderproblemen.

Schnellinstallation

Claude Code

Dokumentation

Common Issues (+1)

Common Issues

Build Fails with "Page not in nav"

# mkdocs.yml - Allow pages not in nav
validation:
  nav:
    omitted_files: info
    not_found: warn
    absolute_links: info

Mermaid Diagrams Not Rendering

# Ensure superfences is configured correctly
markdown_extensions:
  - pymdownx.superfences:
      custom_fences:
        - name: mermaid
          class: mermaid
          format: !!python/name:pymdownx.superfences.fence_code_format

Search Not Working

# Check search configuration
plugins:
  - search:
      lang: en
      prebuild_index: true  # Build search index at build time

Git Revision Plugin Fails

# Ensure git history is available
git fetch --unshallow  # In CI environments

# Or disable in mkdocs.yml for local testing
plugins:
  - git-revision-date-localized:
      fallback_to_build_date: true

Social Cards Generation Fails

# Install required dependencies
pip install pillow cairosvg

# On Ubuntu
apt-get install libcairo2-dev libffi-dev

# On macOS
brew install cairo

Debug Mode

# Verbose build output
mkdocs build --verbose

# Serve with debug info
mkdocs serve --verbose --dev-addr 0.0.0.0:8000

# Strict mode catches warnings as errors
mkdocs build --strict

GitHub Repository

vamseeachanta/workspace-hub

Pfad: .claude/skills/_internal/documentation/mkdocs/common-issues