Setting up the "Under Construction" placeholder¶

There are two different situations here, and they need two different fixes:

Situation	Example	Fix
A page is listed in your nav but you haven't written the content yet	`Mathematics for Nerds → Slater Determinants`	Stub page with the placeholder message (Part 1 below)
A URL doesn't correspond to any page at all	typo, deleted page, stale external link	Custom 404 page (Part 2 below)

Every link inside your own site (nav menu, "Related Tutorials" links, etc.) falls into the first case — it points at a real, nav-listed .md file. As long as that file exists (even as a stub), the link works and nobody ever sees a 404. The 404 page only matters for links outside your control (someone mistyping a URL, an old bookmark to a page you renamed).

Part 1 — Stub pages for not-yet-written content¶

1a. Add the shared snippet¶

Save the attached under-construction.md as includes/under-construction.md — a new folder at your repo root, next to mkdocs.yml (not inside docs/, so mkdocs doesn't try to build it into its own page).

1b. Enable snippet includes in `mkdocs.yml`¶

You already have pymdownx.snippets in your markdown_extensions: list, but it's unconfigured. Replace this line:

  - pymdownx.snippets

with:

  - pymdownx.snippets:
      base_path: ["includes"]
      check_paths: true

check_paths: true makes the build fail loudly if a snippet reference is ever broken, instead of silently rendering nothing.

1c. Generate the stub pages¶

Attached is generate_stubs.py. It reads your mkdocs.yml nav, and for every page listed there that doesn't yet exist under docs/, creates a minimal stub:

# <Page Title From Nav>

!!! warning "🚧 Documentation Under Construction"
    This section of **Computational Theoretical Chemistry** is currently being written. The page you requested has not yet been published.

**When complete, it will include:**

- Theory
- Mathematical derivation
- Input examples
- Output interpretation
- Practical examples
- References

---

**What you can do:**

- Return to the previous page.
- Browse the documentation using the navigation menu.
- Check back soon as new content is added regularly.

Thank you for your patience!

Run it from your repo root (where mkdocs.yml lives):

pip install pyyaml
python3 generate_stubs.py --dry-run     # preview first — lists what it would create
python3 generate_stubs.py               # actually creates the stub files

I ran this against your actual mkdocs.yml nav as a check: it correctly parsed all 191 pages referenced in nav. Since I don't have access to your repo's docs/ folder, I can't tell you exactly how many of those 191 already have real content — the script figures that out itself by checking which files exist and only creates the ones that are missing, so it's always safe to re-run later as you fill in more pages (it never touches or overwrites a file that already exists).

Once a page is written for real, just delete the --8<-- "under-construction.md" line and write the actual content — the file's already in the right place, nothing else changes.

1d. (Optional) Flag WIP pages in the nav itself¶

If you want visitors to see a page is unfinished before they click it, append a marker to the title in mkdocs.yml, e.g.:

- Slater Determinants 🚧: software/gaussian/energy/mathematics/slater-determinant.md

This is entirely optional and just cosmetic — the stub page works fine without it.

Part 2 — Custom 404 page for genuinely dead links¶

Save the attached 404.html as overrides/404.html (repo root of your custom_dir, i.e. next to overrides/partials/footer.html — as a sibling of the partials/ folder, not inside it).

This uses the same message, styled as a full page using your site's normal main.html layout (so it keeps your header, nav, and footer — including the disclaimer link from before). Most static hosts (GitHub Pages included) automatically serve /404.html for any unmatched URL, so no extra config is needed beyond having the file in the right place.

Test this one after deploying

404 handling depends on your hosting setup (GitHub Pages vs. a custom server), and mkdocs-material's main.html block structure can shift slightly between versions. Build locally with mkdocs serve, visit a nonsense URL like /this-page-does-not-exist/, and confirm it renders cleanly — if the header/nav look broken, the fix is usually removing the {% block content_secondary %}{% endblock %} override or adjusting which blocks you override.

Files in this delivery¶

includes/under-construction.md — the shared message, included via snippet
generate_stubs.py — one-time script to create stub pages for everything in nav that doesn't exist yet
404.html — custom 404 page for genuinely broken links