Zensical Development Best Practices

Comprehensive workflow and best practices for developing zensical (Material for MkDocs) static sites with proper setup, responsive design, image handling, and media embedding.

CRITICAL: Always Use Zensical, Never MkDocs Directly

NEVER use mkdocs serve or mkdocs build commands directly.

Always use the zensical CLI:

zensical serve (NOT mkdocs serve)
zensical build (NOT mkdocs build)

Project Setup & Requirements

Installation & Virtual Environment

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

.gitignore Requirements

MANDATORY entries:

# Python virtual environment
.venv/
venv/

# Zensical build output
site/

# Cache directories
.cache/

# System files
.DS_Store

Creating a New Project

# Bootstrap new project
zensical new .

# This creates:
# - .github/ directory
# - docs/ folder with index.md
# - zensical.toml configuration file

Development Workflow

Step 1: Make Changes

Text-only changes (no visual verification needed):

Fixing typos, updating content

Visual changes (REQUIRES visual verification):

Adding/modifying CSS
Adding/moving images
Embedding videos
Changing layouts

Step 2: Deploy Locally

source .venv/bin/activate
zensical serve
# Site runs at http://localhost:8000

Server Restart Required For:

CSS file changes
Configuration changes (zensical.toml)
JavaScript file changes

Step 3: Verification (MANDATORY for visual changes)

# 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
  }));
}
""")

Best Practices

Responsive Images

img {
    display: block;
    margin: 0 auto;
    max-width: 100%;
    height: auto;
}

YouTube Videos

<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>

Common Issues & Fixes

Images Cropped/Cut Off

Remove max-height from global img selector:

img {
    max-width: 100%;
    height: auto;
}

Images Not Loading (404)

Check path relative to markdown file location.

Horizontal Overflow on Mobile

Use max-width: 100% and test at 375px.

Project Structure

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)

Common Commands

# Setup
python3 -m venv .venv
source .venv/bin/activate
pip install zensical
zensical new .

# Development
zensical serve

# Building
zensical build
zensical build --strict

Summary

Every Zensical project MUST have .venv/
.gitignore MUST include: .venv/, site/, .cache/
Always activate venv before running zensical commands
Visual verification is MANDATORY for CSS/HTML/image changes
CSS changes require server restart
Images use max-width: 100%; height: auto;

zensical-development