Skip to content

CLAUDE.md

Latest commit

 

History

History
49 lines (35 loc) · 2.29 KB

CLAUDE.md

File metadata and controls

49 lines (35 loc) · 2.29 KB

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Project Overview

Bilingual (English/Spanish) Python textbook built with MkDocs Material, deployed to GitHub Pages. Content organized as 12 modules: Foundations (M1-M9, beginner) and Beyond the Basics (M10-M12, intermediate). Selected chapters have in-browser Python execution via Pyodide.

Commands

# Setup
python -m venv .venv && source .venv/bin/activate
pip install -r requirements.txt

# Local dev server (http://127.0.0.1:8000)
mkdocs serve

# Build static site (outputs to site/)
mkdocs build

# Deploy to GitHub Pages (CI does this automatically on push to main)
mkdocs gh-deploy --force

Architecture

  • mkdocs.yml — Central config: navigation, theme, plugins, i18n settings, markdown extensions
  • docs/ — All content as Markdown files
    • Bilingual via suffix convention: file.md (English), file.es.md (Spanish) — handled by mkdocs-static-i18n plugin
    • modules/ — All chapters with numbered prefixes (m01- through m12-) matching curriculum modules
    • exercises/foundations/ — Exercises for Modules 1-9
    • exercises/beyond/ — Exercises for Modules 10-12
    • authoring/chapter-template.md — Canonical chapter structure (What you'll learn → Explanation → Example → Common mistakes → Exercises → Further reading)
    • assets/js/pyodide-runner.js — In-browser Python execution engine (Pyodide v0.27.2)
    • assets/js/language-switcher.js — EN/ES toggle
  • site/ — Generated output (gitignored in deployment, present locally)

Content Conventions

  • Chapters follow the template in docs/authoring/chapter-template.md
  • Interactive code blocks use <div class="py-run" markdown="1"> wrapper
  • Exercises use ??? tip for hints and ??? success for solutions (pymdownx.details collapsibles)
  • Every English content file should have a corresponding .es.md Spanish translation
  • Navigation translations for Spanish UI strings are defined in mkdocs.yml under plugins.i18n.languages.es.nav_translations

Contribution Policy

All contributions require explicit maintainer authorization before starting work. See CONTRIBUTING.md for the full process. All changes require review from @enaguero (defined in .github/CODEOWNERS).