Optimal Control — Exam Study Site

A static study site for the Optimal Control (ORR) exam, built with MkDocs Material. Features:

• First-class math (MathJax) with custom optimal-control macros.
• Full-text search and tabbed chapter navigation.
• Mermaid diagrams for block diagrams / signal flows.
• Runnable Python plots — numpy/matplotlib/scipy executed in the browser via Pyodide, with editable, re-runnable cells.

Quick start

# One-time: create the environment
uv venv .venv
uv pip install --python .venv -r requirements.txt

# Live preview (rebuilds on save)
.venv/bin/mkdocs serve
# -> http://127.0.0.1:8000

Build a static site

.venv/bin/mkdocs build      # outputs to ./site

The result in site/ is fully static and can be hosted anywhere (GitHub Pages, Netlify, an S3 bucket, …). The interactive Python runs client-side, so no backend is required.

Deploy to GitHub Pages (optional)

.venv/bin/mkdocs gh-deploy

Layout

mkdocs.yml                 # site config + navigation
requirements.txt
docs/
  index.md                 # home
  authoring.md             # how to add pages (math, diagrams, runnable code)
  chapters/
    index.md               # chapter list
    lq-optimal-control.md  # worked example page
  javascripts/
    mathjax.js             # MathJax config + macros
    pyodide-run.js         # in-browser Python runner
  stylesheets/
    extra.css              # styling for runnable blocks

Adding content

See docs/authoring.md. In short: drop a Markdown file in docs/chapters/, add one line to nav: in mkdocs.yml, and use $...$ for math, ```mermaid for diagrams, and ```{.python .pyrun} for runnable plots.