zensical-development

# 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`).

```bash
# 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:**

```gitignore
# Python virtual environment
.venv/
venv/

# Zensical build output
site/

# Cache directories
.cache/

# System files
.DS_Store
```

### Creating a New Project

```bash
# 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

```bash
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)

```python
# 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="""
() => {
  cons