Lab Notes (this site)

At a glance

Status	Live
Stack	Python, MkDocs, Material for MkDocs, GitHub Actions, GitHub Pages
Source	jakeumm/lab-notes
Site	lab-notes.jakescloud.net

Overview

A static portfolio site where I write up the projects I build. Pages are plain Markdown in docs/, Material for MkDocs turns them into a searchable site, and every push to main deploys it to GitHub Pages.

How it works

flowchart LR
    A[Markdown in docs/] --> B[mkdocs build --strict]
    C[mkdocs.yml] --> B
    B --> D[site/ artifact]
    D --> E[GitHub Pages]
    F[git push main] -.triggers.-> B

Repo layout

lab-notes/
├── .github/workflows/deploy.yml   # build + deploy to Pages
├── docs/
│   ├── index.md                   # home page with featured cards
│   ├── about.md
│   ├── tags.md                    # auto-generated tag index
│   ├── projects/
│   │   ├── index.md               # project list
│   │   └── lab-notes.md           # this page
│   ├── assets/                    # screenshots/images
│   └── stylesheets/extra.css
├── mkdocs.yml                     # site config, theme, nav
└── requirements.txt               # mkdocs<2, mkdocs-material 9.x

Setup steps

1. Scaffolded the site. I wrote mkdocs.yml by hand instead of running mkdocs new, so the theme, features, and Markdown extensions were set up in one go:
   • Light/dark palette toggle (follows the OS preference)
   • Navigation tabs, sections, index pages, back-to-top, instant loading
   • Search with suggestions and highlighting, copy buttons on code blocks, "edit this page" links
   • Extensions: admonitions, content tabs, task lists, emoji/icons, card grids (attr_list + md_in_html), and Mermaid diagrams through pymdownx.superfences
   • tags plugin with a tags.md index page
2. Wrote the content pages. A home page with a hero section and "featured" cards, a projects index, an about page, and a reusable project page layout (an at-a-glance table, overview, how it works, what I learned, and a roadmap).
3. Pinned dependencies. Material prints a warning that MkDocs 2.0 drops the plugin system and theme overrides, so requirements.txt limits mkdocs to >=1.6,<2 along with mkdocs-material>=9.5,<10.
4. Verified locally.

   python -m venv .venv
   .venv\Scripts\pip install -r requirements.txt
   .venv\Scripts\mkdocs build --strict   # fails on broken links/nav
   .venv\Scripts\mkdocs serve            # http://127.0.0.1:8000/
   

5. Added CI/CD. .github/workflows/deploy.yml runs on every push to main. It installs dependencies, runs mkdocs build --strict, uploads site/ with actions/upload-pages-artifact, and deploys with actions/deploy-pages.
6. Turned on Pages. Repo Settings → Pages → Source: GitHub Actions. Don't pick the suggested Jekyll or static HTML starter workflows; the repo already has its own.

Gotchas

Local preview path follows site_url

The dev server serves the site under site_url's path. With the default GitHub Pages URL (jakeumm.github.io/lab-notes/) that was http://127.0.0.1:8000/lab-notes/. After switching to the custom domain lab-notes.jakescloud.net, it's served at the root, http://127.0.0.1:8000/.

Strict builds

--strict turns warnings (broken links, pages missing from nav) into errors, so CI catches them before deploy.

Adding a new project

1. Create docs/projects/<name>.md (copy this page's structure).
2. Add it under Projects in nav in mkdocs.yml.
3. Add a card to docs/projects/index.md (and docs/index.md if it's featured).
4. Put images in docs/assets/ and reference them with ![alt](../assets/image.png).

Roadmap

• Scaffold Material for MkDocs site
• GitHub Actions deploy to Pages
• Add real projects
• Add screenshots and a custom favicon/logo