|
| 1 | +# CLAUDE.md |
| 2 | + |
| 3 | +This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository. |
| 4 | + |
| 5 | +## Project Overview |
| 6 | + |
| 7 | +KubernetesLabs is a hands-on Kubernetes learning repository with 33+ numbered labs and 7 task collections. Content is published as an MkDocs Material site at https://nirgeier.github.io/KubernetesLabs/. |
| 8 | + |
| 9 | +## Build & Serve Commands |
| 10 | + |
| 11 | +```bash |
| 12 | +# Install dependencies |
| 13 | +pip install -r mkdocs/requirements.txt |
| 14 | + |
| 15 | +# Local development server (http://localhost:8000) |
| 16 | +mkdocs serve --config-file mkdocs.yml |
| 17 | + |
| 18 | +# Build static site (output: mkdocs-site/) |
| 19 | +mkdocs build --config-file mkdocs.yml |
| 20 | + |
| 21 | +# Deploy to GitHub Pages (done automatically by CI on push to main/master) |
| 22 | +mkdocs gh-deploy --force --clean --config-file mkdocs.yml --no-history |
| 23 | +``` |
| 24 | + |
| 25 | +## Architecture |
| 26 | + |
| 27 | +### MkDocs Configuration |
| 28 | + |
| 29 | +The single `mkdocs.yml` at root is a merged file containing all config sections. The modular source files live in `mkdocs/`: |
| 30 | + |
| 31 | +- `01-mkdocs-site.yml` - Site metadata (name, URL, author) |
| 32 | +- `02-mkdocs-theme.yml` - Material theme settings |
| 33 | +- `03-mkdocs-extra.yml` - Social links, extra CSS/JS |
| 34 | +- `04-mkdocs-plugins.yml` - Plugins (git-committers, search, minify, print-site, include-markdown) |
| 35 | +- `05-mkdocs-extensions.yml` - Markdown extensions (pymdownx, mermaid, admonitions, tabs) |
| 36 | +- `06-mkdocs-nav.yml` - Navigation structure |
| 37 | + |
| 38 | +**Important:** `docs_dir` is set to `Labs` - all content lives under `Labs/`. |
| 39 | + |
| 40 | +### Lab Structure |
| 41 | + |
| 42 | +Each lab follows this pattern: |
| 43 | +``` |
| 44 | +Labs/XX-TopicName/ |
| 45 | +├── README.md # Main lab content (this is the MkDocs page) |
| 46 | +├── manifests/ # Kubernetes YAML files |
| 47 | +├── scripts/ # Shell automation scripts |
| 48 | +└── [Dockerfile, etc.] |
| 49 | +``` |
| 50 | + |
| 51 | +Tasks live in `Labs/Tasks/Kubernetes-*-Tasks/README.md`. |
| 52 | + |
| 53 | +### Navigation |
| 54 | + |
| 55 | +When adding a new lab, update the nav in both: |
| 56 | +- `mkdocs.yml` (the merged config) |
| 57 | +- `mkdocs/06-mkdocs-nav.yml` (the source file) |
| 58 | + |
| 59 | +## Lab README Conventions |
| 60 | + |
| 61 | +- Start with optional YAML frontmatter |
| 62 | +- Include sections: description, "What will we learn?", "Official Documentation & References" (table format), "Prerequisites", then numbered content sections (01, 01.01, etc.) |
| 63 | +- Use `=== "macOS"` / `=== "Linux"` tab syntax for platform-specific instructions |
| 64 | +- Use admonitions (`!!! note`, `!!! warning`, `!!! tip`) for callouts |
| 65 | +- Use mermaid fenced blocks for architecture diagrams |
| 66 | +- Code blocks use language hints: `bash`, `yaml`, `go`, `dockerfile` |
| 67 | + |
| 68 | +## CI/CD |
| 69 | + |
| 70 | +GitHub Actions (`.github/workflows/deploy-mkdocs.yml`) deploys on push to `main` or `master`. Requires Python 3.11, full git history (`fetch-depth: 0`), and `mkdocs/requirements.txt`. |
| 71 | + |
| 72 | +## Commit Message Convention |
| 73 | + |
| 74 | +Follow the pattern: `labXX: <description>` (e.g., `lab32: Add EFK stack`). |
0 commit comments