Catalog of classes Brandon Harvey teaches at Dallas Makerspace, published at classes.smarthomesellout.com. MkDocs Material on GitHub Pages; pandoc builds docx/PDF versions of each class's materials.
docs/index.md: hub landing page, one card per class.docs/teaching.md: the fork/build/license page for people who want to teach a class. Class pages are written for attendees; anything about forking, pipelines, or repo mechanics belongs on teaching.md or in the README, never on a class page.docs/<class-slug>/: one folder per class (index.mdclass page,outline.mdspeaker outline,handout.mdattendee handout).docs/stylesheets/extra.css: the entire brand restyle. No other styling anywhere.overrides/partials/: Material template overrides (shared header, drawer nav). Markup only; their styles live inextra.css.specs/,plans/: design docs, NOT published (everything underdocs/is).
outline.md and handout.md in each class folder feed BOTH the website and the pandoc docx/PDF builds. They must stay plain portable Markdown:
- No admonitions (
!!! note), no raw HTML, no{ .class }attributes, no grid cards. Pandoc renders all of these as literal garbage in the print versions. - Site-only pages (
docs/index.mdand each class'sindex.md) are never read by pandoc; Material features are fine there.
This site reads as part of smarthomesellout.com. Tokens in extra.css mirror the main site's src/styles/global.css (the 2026-10-21 relaunch); when the main site's palette or header changes, port it here.
- Shared header:
overrides/partials/header.html(viacustom_dir: overrides) copies the main site's header from itssrc/layouts/BaseLayout.astro: logo plus "smarthomesellout" wordmark linking to smarthomesellout.com, Buying Guides / Reviews / Blog / Classes (Classes is this site, underlined as the current section), YouTube icon, round theme toggle, 3px#39c5cfrule. It adds a round search button (Material search) and a Menu button that opens Material's drawer below 1220px. Sizes are px to match the main site at 1366px; styles are under "Shared header" inextra.css. The header is not sticky, like the main site. Header URLs are absolute or root-relative because instant navigation keeps the header across page loads. overrides/partials/nav.htmlis Material's nav plus the main site's links at the top of the drawer, shown at phone widths (880px and below) where the header folds them away.- Light default (listed first in
mkdocs.yml), dark toggle. Light: paper#f9fbfb, ink#0a0f10, muted#485557, rules#d6dedf. Dark: paper#0e1517, ink#ecf2f2, rules#263639. ONE brand accent: teal#39c5cffor fills and the header rule,#0c7d87for text links in light,#62d4dcin dark. docs/assets/logo-light.svg(header, light scheme) anddocs/assets/logo.svg(header in dark, drawer, favicon) are the shared SmartHomeSellout brand mark (broadcasting house, RJ45 door, $ tag). The masters live in the blog repo atpublic/brand/logo-light.svgandpublic/brand/logo.svg; if the mark changes there, copy the new version here rather than editing these copies.- Each class additionally has an identity color, used ONLY for its card top border and icon: HA uses the official Home Assistant blue
#18bcf2(#0d84aclight scheme, since 2026-07-07; Brandon wants real project brand colors, not invented tints), ESPHome teal, WLED violet, soldering green (--shs-c-*in extra.css, both schemes). Known issue: ESPHome's identity teal now matches the site accent; give ESPHome a new hue before its class goes live (check ESPHome's real brand color). - The hub features the live class in a full-width
.feature-card(raw<img class="feature-photo">+.feature-bodydiv; markdown wraps the img in a<p>, which the CSS relies on). Coming-soon classes stay as compact muted grid cards. - Class cards carry a photo (
.card-photo) and the class page a hero image (.page-hero). Real photos preferred; flat SVG placeholders live indocs/assets/placeholders/until Brandon supplies them. Swap a placeholder by replacing the image link on the hub and class page (or overwriting the file if the format matches). - Flat 1px borders, 0.75rem radius. Never add box shadows, gradients, glow, or extra accent colors beyond the class identity colors above.
- Headings and the header wordmark: Zilla Slab. Body: Schibsted Grotesk. Code: JetBrains Mono. All three load from Google Fonts in
extra.css(theme.fontisfalse). - Voice: terse, concrete, plain headings. No em dashes anywhere, in any file, ever: use commas, colons, parentheses, or sentence breaks.
- Keep bold for product names, giveaway cues, and real warnings. No bold-stuffing.
- Create
docs/<class-slug>/withindex.md,outline.md,handout.md. - Promote its coming-soon card on
docs/index.mdto a live card linking the class page (keep its icon and--shs-c-*identity color; add a.card-photoimage). - Add a nav section in
mkdocs.yml(first child is the bareindex.mdpath sonavigation.indexesmakes it the section landing). - In
.github/workflows/build.yml: addbuildlines for the new files and a "Refresh rolling release" step with a new tag (pattern: short class slug, e.g.esphome).
- Edit Markdown, push to
main. Pages deploys the site; build.yml refreshes the touched class's rolling release. There is no staging. - Releases are rolling, one per class (
intro-ha, ...). Never create version tags for class materials; download URLs underreleases/download/<tag>/must stay permanent. - Local preview:
python3 -m venv .venv && .venv/bin/pip install "mkdocs-material==9.*" mkdocs-redirects && .venv/bin/mkdocs serve. - Verify before pushing:
.venv/bin/mkdocs build --strictmust pass with zero warnings. - Moving or renaming a page requires a
redirect_mapsentry inmkdocs.yml.