From zensical-development
Best practices for developing zensical/Material for MkDocs static sites. Covers installation, virtual environments, project structure, responsive images, CSS, media embedding, and verification. Use for ANY Material for MkDocs project development beyond basic text editing.
How this skill is triggered — by the user, by Claude, or both
Slash command
/zensical-development:zensical-developmentThe summary Claude sees in its skill listing — used to decide when to auto-load this skill
Comprehensive workflow and best practices for developing zensical (Material for MkDocs) static sites with proper setup, responsive design, image handling, and media embedding.
Comprehensive workflow and best practices for developing zensical (Material for MkDocs) static sites with proper setup, responsive design, image handling, and media embedding.
NEVER use mkdocs serve or mkdocs build commands directly.
Always use the zensical CLI:
zensical serve (NOT mkdocs serve)zensical build (NOT mkdocs build)CRITICAL: Every Zensical project MUST have a Python virtual environment (.venv).
# Create virtual environment
python3 -m venv .venv
# Activate virtual environment
source .venv/bin/activate # macOS/Linux
# Install zensical
pip install zensical
MANDATORY entries:
# Python virtual environment
.venv/
venv/
# Zensical build output
site/
# Cache directories
.cache/
# System files
.DS_Store
# Bootstrap new project
zensical new .
# This creates:
# - .github/ directory
# - docs/ folder with index.md
# - zensical.toml configuration file
Text-only changes (no visual verification needed):
Visual changes (REQUIRES visual verification):
source .venv/bin/activate
zensical serve
# Site runs at http://localhost:8000
Server Restart Required For:
zensical.toml)# Navigate to page
mcp__chrome-devtools__navigate_page(url="http://127.0.0.1:8000/page/")
# Take screenshot
mcp__chrome-devtools__take_screenshot()
# Verify image dimensions
mcp__chrome-devtools__evaluate_script(function="""
() => {
const images = document.querySelectorAll('img');
return Array.from(images).map(img => ({
src: img.src.split('/').pop(),
maxWidth: window.getComputedStyle(img).maxWidth,
displayWidth: img.offsetWidth
}));
}
""")
img {
display: block;
margin: 0 auto;
max-width: 100%;
height: auto;
}
<div style="position: relative; padding-bottom: 56.25%; height: 0; overflow: hidden; max-width: 100%; margin: 20px 0;">
<iframe
src="https://www.youtube.com/embed/VIDEO_ID"
style="position: absolute; top: 0; left: 0; width: 100%; height: 100%;"
frameborder="0"
allowfullscreen>
</iframe>
</div>
Remove max-height from global img selector:
img {
max-width: 100%;
height: auto;
}
Check path relative to markdown file location.
Use max-width: 100% and test at 375px.
project-root/
├── .venv/ # Virtual environment (in .gitignore)
├── docs/ # Content directory
│ ├── index.md
│ ├── stylesheets/
│ │ └── extra.css
│ └── img/
├── zensical.toml # Configuration
├── .gitignore
└── site/ # Built output (in .gitignore)
# Setup
python3 -m venv .venv
source .venv/bin/activate
pip install zensical
zensical new .
# Development
zensical serve
# Building
zensical build
zensical build --strict
.venv/.gitignore MUST include: .venv/, site/, .cache/max-width: 100%; height: auto;npx claudepluginhub zeulewan/zeul-claude-plugins --plugin zensical-developmentReferences MkDocs CLI commands, mkdocs.yml settings, Material theme customization, and plugins for building static documentation sites from Markdown files.
Guides MkDocs Material setup with Diataxis framework, mkdocstrings and Griffe for API reference pages, Google-style docstrings, nav structure, code example testing, and deployment to GitHub Pages or ReadTheDocs.
Generates API docs, README files, user guides, developer guides, and changelogs by analyzing code context. Activates on mentions of documentation, README, API docs, guides, or changelogs.