PythonFieldGuide.com

Table of Contents

• What this is
• Content
• Site generator
• Client-side rendering
• Theme
• Content conventions
• Running locally
• Testing
• Deploying
• Analytics
• License

What this is

Quick cheatsheet for basic Python.

This is a casual and unpolished personal project, started in Aug '26.

I wrote and built this from scratch — it started as a few quick-reference explanations on loops and lists for high-school intro-Python students working on their first projects, and evolved from there. I couldn't find a resource my students would consistently use that had:

• simple explanations for beginners without technical jargon
• no advanced topics that intimidate or overwhelm beginners
• quick-reference code samples, to browse what functions they could apply to solve their problem
• at-a-glance reminders for students who already knew a concept but needed a refresher on the specifics or syntax
• quick intuitive navigation, see everything in one place
• clean, minimal UI — some sites were visually dated, and less enjoyable for beginners

Content

Pages are hand-written by me (very much a work in progress).

On the homepage there is a compacted quick reference cheatsheet that includes most python keywords that are covered on that page. As this content evolved so did the structure, it was an immense amount of technical writing and information architecture.

Core Python

• Get started — Workspace setup, Foundations
• Data types — Scalars (int, float, str, bool, None), Collections (list, dict, tuple, set)
• Control flow — Conditionals, Loops
• Code organization — Functions, Classes
• External files and resources — Modules & imports, Reading & writing files
• Robust programming practices — Style, Errors

Add-on libraries

• Utilities — collections, datetime, random
• Data analysis — csv, matplotlib, NumPy, pandas
• APIs — json, requests
• Image editing — Pillow
• Computer vision — OpenCV
• Desktop UIs — Tkinter

Site generator

MkDocs

A static-site generator, which turns a tree of Markdown files into a documentation website. For bonus points it's written in Python.

Material for MkDocs

A theme and feature layer for MkDocs. When I found myself overriding too much of the default theme's formatting, I transitioned to this to rewrite less — though I still maintain some custom CSS.

PyMdown Extensions:

• tabbed — tabbed content blocks
• details — collapsible admonitions
• keys — keyboard-key styling
• caret — superscript for exponent notation
• emoji — :emoji: shortcodes rendered as Twemoji SVGs
• tasklist — styled task-list checkboxes
• superfences — nested fences, and handing Mermaid code blocks off to the renderer
• snippets — auto-appends includes/glossary.md to every page, a list of *[term]: definition entries that the abbr extension (plus Material's content.tooltips) turns into the hover tooltips on keywords
• highlight — set to use_pygments: false, so client-side highlight.js does the syntax highlighting instead of build-time Pygments

Python-Markdown extensions:

• footnotes
• abbr — the glossary tooltips (fed by snippets above)
• admonition — the note/tip/warning callout boxes that can be collapsible
• attr_list — { .class #id } attributes on elements, e.g. the homepage buttons
• md_in_html — Markdown parsed inside raw HTML blocks, e.g. the card grids on the homepage
• tables — pipe tables, in use at the top of some pages to compare components

Client-side rendering

Things MkDocs doesn't produce at build time — JavaScript turns them into their final form in the reader's browser.

Pyodide

CPython compiled to WebAssembly, which runs Python in the browser with no download or install. It powers the runnable blocks, so readers can execute and tweak an example inline. The runtime is pulled from a CDN on demand the first time someone clicks Run.

CodeJar

A ~2KB code editor, which makes an element editable in place with live syntax highlighting. It wraps each Pyodide block so you can change a value and rerun without leaving the page.

highlight.js

A syntax highlighter, which colors code in the browser. It handles both the static examples and whatever a reader types into a CodeJar block. Pygments, MkDocs's usual build-time highlighter, is switched off in favor of it.

Mermaid

A diagram renderer, which draws flowcharts and diagrams from a plain-text description. Fenced mermaid blocks in the Markdown are rendered to SVG on page load.

Theme

Custom CSS

Styling, primarily centered on making the homepage a compact all-in-one dashboard view.

Google Fonts

Serves font files to the page. It provides the two typefaces — Source Serif 4 for text, JetBrains Mono for code — wired in through Material's native font config.

Content conventions

I found myself writing so much content for this, and needing to jump between different pages so frequently while I was editing, that I created a structure guide to help the site stay consistent as it grows over time. STRUCTURE.md is the reference for authoring or editing pages. It covers:

• Runnable code blocks — how the Pyodide/CodeJar feature is wired (detection of ```python fences, lazy CDN load, stdout capture, editable re-highlighting), and the python-ref fence used for the non-runnable cheat-sheet preview at the top of each concept section.
• Page shape — every content page is an intro paragraph, then one ## per concept (each with an intro sentence and a single combined runnable block), then optional ??? collapsible subsections for specific operations.
• Text style — "Python" always capitalized in prose, sentence-case headings, full sentences end with a period, numbered walkthroughs start at 0., short (1–2 word) subheadings because toc.integrate mirrors them verbatim into the sidebar.
• Where information goes — the decision rules for heading level vs. admonition vs. glossary entry vs. footnote, with a table of which ??? type to use for what, plus how the homepage keyword deep-links in index.md have to cover every heading.

The mechanically-checkable subset of these rules (heading case, list-start number, admonition types, python-ref comment format, homepage link coverage, clean mkdocs build) is enforced by tests/test_structure.py; the rest need editorial judgment.

Running locally

Create the virtualenv, install the dependencies, and start the dev server:

python3 -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt

mkdocs serve   # live-reloading dev server at http://127.0.0.1:8000

Testing

The site's main features are integrations of client-side libraries, plus a custom CSS layered over Material. This test suite covers the invariants nothing else checks: the runnable code blocks still execute in a browser, the palette clears WCAG AA contrast in light and dark mode, the custom CSS doesn't trap keyboard focus or swallow clicks, and every content page keeps the structure the homepage cards link to.

pytest

The standard Python test runner, which discovers test_* functions across the repo and reports what passed. It's the single entry point for the whole suite:

• tests/test_structure.py checks docs/*.md against the mechanically-verifiable rules in STRUCTURE.md. See its docstring/comments for what's covered and what's deliberately left out because it needs editorial judgment a text-only check can't make.
• tests/test_accessibility.py is a static (no-browser) regression check for a specific accessibility bug pattern (an outline: none with no :focus-visible replacement).
• The browser-based accessibility tier (test_accessibility_browser.py, test_accessibility_runnable.py, test_accessibility_keyboard.py) renders real pages with Playwright and checks: axe-core over representative pages in light/dark mode and at mobile/tablet widths; the hand-wired Pyodide runnable blocks (accessible names, keyboard focus order, the output live region); and keyboard navigation (skip link, a visible focus ring on every tab stop, no positive tabindex, palette toggle reachable). It's the heaviest part of the suite — needs playwright install chromium above and launches a real browser.

Playwright

A browser-automation library, which drives a real browser from code to load pages and read back the rendered result. Here it launches a headless Chromium so the accessibility pass sees each page exactly as a browser builds it.

axe-core

An accessibility rule engine, which scans a rendered page's DOM for WCAG violations. It runs inside the Playwright browser against every fully rendered page.

Continuous integration

1. Work is done on the development branch.
2. A development -> main pull request is opened.
3. test.yml runs the full pytest suite in GitHub Actions against the pull request.
4. Merging into main publishes the site: deploy.yml builds it and pushes the output to GitHub Pages.

Running the tests locally

source .venv/bin/activate
playwright install chromium   # one-time, downloads a browser binary for the accessibility tests
pytest

Deploying

GitHub Actions

GitHub's built-in CI/CD runner, which executes a workflow of commands on their servers in response to repo events like a push. Here, .github/workflows/deploy.yml runs on every push to main. It installs requirements.txt and runs mkdocs gh-deploy --force, which builds the site and pushes the static output to the gh-pages branch. No manual deploy step is needed — just push to main. A push is usually live within a few minutes.

GitHub Pages

GitHub's free static-site host, which serves the files on a chosen branch of a repo as a website. Here it serves the built site from the gh-pages branch at my custom domain.

Purchased .com domain

The domain is set up via the docs/CNAME file, which MkDocs copies into every build so Pages keeps serving there. On my registrar I then added apex A records pointing at GitHub's Pages IPs.

Analytics

Google Analytics (GA4) is wired in through Material's built-in support. I immediately noticed the library pages drawing more traffic than the rest of the site, so I built those out further.

License

The content and code in this repo are not licensed for reuse — see LICENSE.