Jeremy's Lab Notes

Static site built with MkDocs + Material and published to GitHub Pages.

Purpose

This repo is the source of truth for:

• how-tos
• references
• notes
• project write-ups
• screenshots and diagrams

Local setup

Windows PowerShell

py -m venv venv
.\venv\Scripts\Activate.ps1
pip install -r requirements.txt

Linux/macOS

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

Run locally

mkdocs serve

Browse to:

http://127.0.0.1:8000

Source sync vs publishing

These are separate on purpose.

1. Sync source content

Use this whenever you want to save and sync your markdown, images, and config.

git add .
git commit -m "add proxmox ceph notes"
git push

This updates your source repo only.

2. Publish the website

Use this when you want the live site updated.

mkdocs gh-deploy

This builds the static site and pushes the generated output to the gh-pages branch.

Recommended workflow

1. Edit markdown in docs/
2. Add images under docs/images/<topic>/
3. Preview locally with mkdocs serve
4. Run image compression before commit:
   • python scripts/compress-images.py
   • or ./scripts/compress-images.sh
   • or ./scripts/compress-images.ps1
5. Commit and push source changes
6. Run mkdocs gh-deploy when you want the live site updated

Templates

• docs/_templates/post-template.md
• docs/_templates/project-template.md
• docs/_templates/how-to-template.md

Analytics

Analytics is configured in mkdocs.yml with a placeholder:

extra:
  analytics:
    provider: google
    property: G-XXXXXXXXXX

Replace the value with your GA4 Measurement ID.

Custom domain and HTTPS checklist

See:

• docs/references/custom-domain-and-https.md

Later: GitHub Actions

A reference workflow is included here but not enabled:

.github/workflows/deploy.yml.example

When you are ready to switch away from local gh-deploy, rename it to:

.github/workflows/deploy.yml

and then stop running mkdocs gh-deploy locally.