mkdocs-common-issues

vamseeachanta

Обновлено Yesterday

13 просмотров

Другоеgeneral

О программе

Этот навык предоставляет решения для распространённых проблем MkDocs, таких как сбои сборки, отображение диаграмм Mermaid и неполадки поиска. Он предлагает готовые фрагменты конфигурации и шаги по устранению неисправностей для разработчиков. Используйте это руководство при возникновении типичных проблем с развёртыванием или отображением MkDocs.

Быстрая установка

Claude Code

Рекомендуется

Основной

npx skills add vamseeachanta/workspace-hub

Команда плагинаАльтернативный

/plugin add https://github.com/vamseeachanta/workspace-hub

Git клонированиеАльтернативный

git clone https://github.com/vamseeachanta/workspace-hub.git ~/.claude/skills/mkdocs-common-issues

Скопируйте и вставьте эту команду в Claude Code для установки этого навыка

Документация

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 репозиторий

vamseeachanta/workspace-hub

Путь: .claude/skills/_internal/documentation/mkdocs/common-issues