Agent skill
mkdocs-common-issues
Sub-skill of mkdocs: Common Issues (+1).
Install this agent skill to your Project
npx add-skill https://github.com/vamseeachanta/workspace-hub/tree/main/.claude/skills/_internal/documentation/mkdocs/common-issues
SKILL.md
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
Recommended Agent Skills
Expand your agent's capabilities with these related and highly-rated skills.
vamseeachanta/workspace-hub
gsd-complete-milestone
Archive completed milestone and prepare for next version
vamseeachanta/workspace-hub
gsd-reapply-patches
Reapply local modifications after a GSD update
vamseeachanta/workspace-hub
gsd-verify-work
Validate built features through conversational UAT
vamseeachanta/workspace-hub
gsd-thread
Manage persistent context threads for cross-session work
vamseeachanta/workspace-hub
clinical-trial-protocol
Generate clinical trial protocols for medical devices or drugs through a modular, waypoint-based architecture with research-only and full protocol modes.
vamseeachanta/workspace-hub
single-cell-rna-qc
Performs quality control on single-cell RNA-seq data (.h5ad or .h5 files) using scverse best practices with MAD-based filtering and comprehensive visualizations.
Didn't find tool you were looking for?