How to use this site¶
working
Conventions, so that pages stay uniform enough to skim and the site stays useful as it grows past the point where any one person remembers all of it.
The note template¶
Every topic page has the same eight parts, in the same order. Skip to the one you need.
In one minute
Five bullets, no more. The irreducible core of the topic — enough to hold a conversation, or to decide whether this is the page you actually wanted.
Key results. The equations, symbols defined, final forms boxed. A derivation appears only when the derivation is the insight; otherwise it is a citation.
Mental model. The physical or geometric picture. Why the mathematics takes the shape it does. This is the part that makes a topic reload quickly years later.
Numerics / practice. How it gets discretized or implemented: stability limits, conditioning, typical resolutions, cost scaling.
Failure modes
What goes wrong, what the symptom looks like, and what causes it.
Mandatory. This section is the point of the site. Textbooks record how a method works when it works; nobody writes down that a scheme destabilizes past a given cell aspect ratio, or that a dataset encodes missing values as plausible numbers. That knowledge is expensive to acquire and the first to decay.
Worked example. A notebook link, or a snippet under twenty lines that actually runs.
Connections. Sibling pages, and where the topic has come up in real work.
Sources. Archive pointers, books, papers, lectures — so the page is a map into the material rather than a replacement for it. Gathered site-wide under Resources.
Section index pages are the exception: they carry a page table, a theme, and Connections, but no Sources of their own — their pages hold those.
Creating a page¶
This writes docs/fluids/compressible.md with the template, front matter and today's
date. Add the page to nav: in mkdocs.yml — the navigation is explicit on purpose, so
that section ordering is a decision rather than an alphabetical accident.
Status badges¶
seed The topic is claimed and its sources listed; the body is not written.
working Usable. Core results are present; failure modes or examples may be thin.
solid Complete enough to rely on without opening the sources.
Declared in front matter as status: and repeated as a badge under the page title.
Labelling a stub honestly is better than leaving it out of the navigation: a visible gap
is information.
Tags¶
Two axes, both flat, both applied in front matter:
Pillar — pillar-1 … pillar-10, from the Skills Map. The
primary competency comes first, and must match the badge under the page title.
A page may carry a second pillar where it genuinely spans two — numerical weather prediction is both domain physics and toolchain; PyTorch patterns is both software engineering and scientific ML. Prefer one; take two when one would be a lie. Section index pages routinely carry several.
The ordering is what the audit script enforces, because a primary pillar that disagrees with the badge is a page filed in two places at once.
Section and concept — drawn from a controlled vocabulary of 35 tags, listed in full on the Tags page. One section tag, then any cross-cutting concepts that genuinely apply.
These exist so a topic is reachable from more than one path — spectral-methods matters
to a fluids reader and an ML reader alike, and the navigation tree can only file it once.
Tags are not for specifics. openfoam, betz and skew-t are not tags; search
handles those far better. The vocabulary is closed and the audit script rejects anything
outside it, because the previous free-form taxonomy grew to 205 tags of which 177
appeared on exactly one page — cross-linking nothing.
---
title: Compressible flow
status: working
tags: [pillar-1, fluids, conservation, discretization]
updated: 2026-09-26
---
Mathematics¶
LaTeX, via MathJax. Inline as \( ... \), display as \[ ... \].
Define every symbol on first use in a page. A page that assumes you remember its own notation fails at exactly the moment it is needed.
Abbreviations¶
Common acronyms resolve on hover automatically — CFL, RANS, MOST, NetCDF — from
docs/snippets/abbreviations.md, which is appended to every page at build time. Add new
ones there rather than defining a glossary per page.
Linking to the archive¶
The course archive lives on external storage and is not published. Cite it by its path relative to the archive root, so the pointer survives the drive being remounted elsewhere:
Source:
Aerospace/AERSP425/Notes/ch4.pdf
The course archive catalog resolves those paths and is searchable.
Building locally¶
CI builds with --strict, where warnings are errors — a broken internal link fails the
build rather than shipping. Run mkdocs build --strict before pushing.