mkdocs-common-issues

vamseeachanta

更新日 Today

12 閲覧

その他general

について

このスキルは、ビルド失敗、Mermaid図のレンダリング、検索機能の問題など、MkDocsでよくある問題に対する解決策を提供します。開発者向けに、すぐに使える設定スニペットとトラブルシューティングの手順を用意しています。典型的な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