Website maintenance
The public site is built from the Markdown in docs/. Generated book drafts and
source excerpts stay outside that tree. GitHub Pages deploys only the strict build
after the lesson, bundled lab, dependency, and local-link checks pass.
Install and preview
Use the exact pins in requirements-docs.txt; the documentation environment does
not require PyTorch or a running inference service.
uv pip install --requirement requirements-docs.txt
uv run python -m mkdocs serve --dev-addr 127.0.0.1:8000
python3 -m venv /tmp/deadwire-docs
/tmp/deadwire-docs/bin/python -m pip install --requirement requirements-docs.txt
/tmp/deadwire-docs/bin/python -m mkdocs serve --dev-addr 127.0.0.1:8000
Open the URL printed by MkDocs; the custom-domain site uses the root path /. Choose a
different loopback port if another preview is already running. Stop with Ctrl-C.
The live site is deadwire.cristianexer.dev.
GitHub Pages redirects the repository's default Pages address there. Keep
site_url aligned with the configured domain so canonical URLs and the sitemap
identify the published pages correctly.
Installed features
| Component | Pin | Role and verification |
|---|---|---|
| MkDocs | 1.6.1 | Markdown compilation and strict configuration/link warnings |
| Material | 9.7.1 | Theme, bundled search plugin and local search worker |
| PyMdown Extensions | 11.0.2 | Fenced code, highlighting, details, tabs and task lists |
| Python Markdown extensions | Supplied by the documentation dependencies | Attributes, tables, admonitions and Markdown inside layout containers |
Search is the only enabled MkDocs plugin; code-copy controls and navigation are Material features, while tabs and admonitions are Markdown extensions. No separate browser extension, hosted search service, remote font, or LM Studio model is needed to read the course. The static repository-link override avoids GitHub API requests for badges and release metadata.
The tab configuration uses Material's supported alternate_style layout. Consult
the official content-tab documentation,
search setup,
and navigation reference
before changing those settings.
Before pushing
uv run python scripts/check_course_contract.py
uv run python -m mkdocs build --strict
uv run python scripts/check_site.py
The site check compares installed documentation packages with the pins, resolves local page/asset links and fragment identifiers, verifies search destinations, and rejects accidentally published theme templates. It reports counts and failures; it does not validate external URLs, scientific claims, accessibility compliance, or learner outcomes. Run the bundled web-lab tests when changing its exercise.
After visual changes, inspect desktop and 390-pixel mobile layouts, dark/light
mode, keyboard focus, the drawer, search results, content tabs, and a code-copy
button. Check a lesson as well as the homepage. Save screenshots outside the
tracked tree. Increment the extra.css?v= suffix when changing theme CSS so
returning Pages visitors receive the update.
Editorial consistency
Keep the 24-week route and 90-minute allocation aligned with the weekly plan. Lesson numbers identify topics; they are not week numbers. Label planned time and observed progress separately. Update processing snapshots together in the README, handoff, and library-status page, including their observation date. Never substitute draft counts for approved notes or practical evidence.
Use the terminal green for navigation and emphasis, amber for annotations, and high-contrast body text. Keep layout borders square, animations restrained, and reduced-motion support intact. All course artwork is local SVG; the small terminal mark is the favicon, and the animated banner retains its own accessible description.