feat(pages): sidebar, search, and a compatibility page

Compared the site against the two best-documented projects in this space,
Tasmota and Zigbee2MQTT. Both do three things this site did not: a
persistent sidebar, client-side search, and a prominent "which devices
does this work on" destination.

The sidebar is the one that mattered. Under the primer theme an inner
page rendered with NO navigation at all, so anyone arriving from a search
engine on, say, the OTA page could reach nothing else and had no way
back. Search traffic lands on inner pages by definition, which made it
the worst possible gap for a site whose entire purpose is being found.

Switches to just-the-docs (sidebar + Ctrl+K search, no server), adds
section landing pages, and teaches the assembler to inject `parent` and
`nav_order` so pages nest correctly. Guide pages are ordered by reading
sequence rather than alphabetically: wiring, then flashing, then
commissioning, since that is the order a newcomer needs them.

Adds a compatibility page, the equivalent of the "supported devices" page
both comparables lead with, and the thing someone types a model number
into a search engine looking for. It separates what is confirmed on real
hardware from what merely shares the bus protocol, and says plainly that
"should work" is not "does work".

Also builds the site on pull requests, deploying only from main. The site
previously built only after merge, which is exactly how the broken path
filter reached main: nothing could fail before it was too late.

Assisted-by: AI

Author: AndrewDemsDS

.github/scripts/assemble_docs_site.py

@@ -16,10 +16,26 @@
 SITE = "_site_src"
 
 # (source dir, destination subdir, label used only in log output)
+# (source dir, destination subdir, log label, sidebar parent title)
+# The parent title MUST match the `title:` of docs-site/<subdir>/index.md, which is how
+# just-the-docs nests a page under a section in the sidebar.
 SOURCES = [
-    ("firmware/docs", "firmware", "firmware docs"),
-    ("reverse-engineering/docs", "internals", "reverse engineering"),
-    ("docs/guide", "guide", "guide"),
+    ("firmware/docs", "firmware", "firmware docs", "Firmware"),
+    ("reverse-engineering/docs", "internals", "reverse engineering", "Reverse engineering"),
+    ("docs/guide", "guide", "guide", "Guide"),
+]
+
+# Guide pages read in a deliberate order rather than alphabetically: a newcomer needs wiring before
+# flashing before commissioning. Anything unlisted sorts after these, alphabetically.
+GUIDE_ORDER = [
+    "Hardware-and-Wiring",
+    "Installing-Custom-Firmware",
+    "Commissioning-and-HA-Setup",
+    "Everyday-Control",
+    "OTA-Updates",
+    "Recovery-and-Reflash",
+    "ESP32-Replacement-Build",
+    "FAQ-Gotchas",
 ]
 
 # Wiki pages that are navigation fragments, plus its own linter. Not content.
@@ -100,7 +116,7 @@ def sub(m):
     return re.sub(r"\[([^\]]*)\]\(([A-Za-z][A-Za-z0-9._-]*)(#[^)]*)?\)", sub, text)
 
 
-def convert(src, dst, pages=None):
+def convert(src, dst, pages=None, parent=None, order=None):
     with open(src, encoding="utf-8") as fh:
         lines = fh.readlines()
 
@@ -118,6 +134,10 @@ def convert(src, dst, pages=None):
     fm = ["---", f"title: {yaml_quote(title)}"]
     if desc:
         fm.append(f"description: {yaml_quote(desc)}")
+    if parent:
+        fm.append(f"parent: {yaml_quote(parent)}")
+    if order is not None:
+        fm.append(f"nav_order: {order}")
     fm += ["---", ""]
 
     body = "".join(lines)
@@ -135,7 +155,7 @@ def main():
     shutil.copytree("docs-site", SITE)
 
     total = 0
-    for src_dir, sub, label in SOURCES:
+    for src_dir, sub, label, parent in SOURCES:
         if not os.path.isdir(src_dir):
             print(f"  skip {label}: {src_dir} absent")
             continue
@@ -144,12 +164,21 @@ def main():
         # Page-name set for the link rewrite above (wiki only; repo docs link by filename).
         pages = {os.path.splitext(f)[0] for f in os.listdir(src_dir) if f.endswith(".md")} \
             if src_dir == "docs/guide" else None
+        # Sidebar order: guide pages follow the reading order above; the numbered docs sort by
+        # their own filename prefix, which is already meaningful.
+        def sort_key(fn):
+            stem = os.path.splitext(fn)[0]
+            if sub == "guide":
+                return (GUIDE_ORDER.index(stem) if stem in GUIDE_ORDER else len(GUIDE_ORDER), stem)
+            return (0, stem)
+
         n = 0
-        for name in sorted(os.listdir(src_dir)):
+        for name in sorted(os.listdir(src_dir), key=sort_key):
             # Leading underscore = nav fragment or repo-facing note, never site content.
             if name in SKIP or name.startswith("_") or not name.endswith(".md"):
                 continue
-            convert(os.path.join(src_dir, name), os.path.join(out_dir, name), pages)
+            convert(os.path.join(src_dir, name), os.path.join(out_dir, name), pages,
+                    parent=parent, order=n + 1)
             n += 1
         # Copy assets too. Pages reference them RELATIVELY (![](images/foo.png)), so they have to
         # land beside the markdown that points at them or every image 404s -- which is exactly

.github/workflows/pages.yaml

@@ -18,6 +18,14 @@ on:
       - README.md
       - .github/workflows/pages.yaml
       - .github/scripts/assemble_docs_site.py   # the assembler IS the build; changing it must rebuild
+  pull_request:        # build-only on PRs: catches a broken site config BEFORE it reaches main
+    paths:
+      - docs-site/**
+      - docs/guide/**
+      - firmware/docs/**
+      - reverse-engineering/docs/**
+      - .github/workflows/pages.yaml
+      - .github/scripts/assemble_docs_site.py
   workflow_dispatch:
 
 permissions:
@@ -50,6 +58,7 @@ jobs:
 
   deploy:
     needs: build
+    if: github.event_name != 'pull_request'
     runs-on: ubuntu-latest
     environment:
       name: github-pages

docs-site/_config.yml

@@ -16,7 +16,31 @@ description: >-
 url: https://andrewdemsds.github.io
 baseurl: /hisense-w41h1
 
-theme: jekyll-theme-primer
+# just-the-docs, not primer: primer renders a bare page with NO navigation, so anyone arriving
+# from a search engine on an inner page has no way to reach anything else. Every leading project
+# in this space (Tasmota, Zigbee2MQTT) uses a persistent sidebar plus search for exactly that
+# reason. remote_theme works on GitHub Pages via jekyll-remote-theme.
+remote_theme: just-the-docs/just-the-docs
+
+# Client-side search over every page. No server, no external service.
+search_enabled: true
+search:
+  heading_level: 3
+  previews: 3
+  tokenizer_separator: /[\s/]+/
+
+aux_links:
+  "Source on GitHub":
+    - "https://github.com/AndrewDemsDS/hisense-w41h1"
+aux_links_new_tab: true
+
+heading_anchors: true
+back_to_top: true
+back_to_top_text: "Back to top"
+
+nav_external_links:
+  - title: "Releases (firmware downloads)"
+    url: "https://github.com/AndrewDemsDS/hisense-w41h1/releases"
 
 plugins:
   - jekyll-seo-tag     # per-page <title>, meta description, canonical, Open Graph, JSON-LD

docs-site/compatibility.md

@@ -0,0 +1,71 @@
+---
+title: Will this work on my A/C?
+nav_order: 5
+description: >-
+  Which Hisense air conditioners and Wi-Fi modules this de-cloud firmware works on: confirmed
+  hardware, the AEH-W41H1 and AEH-W4A1 modules, and how to check your own unit before buying
+  anything.
+---
+
+# Will this work on my A/C?
+
+Short version: **if your A/C uses a ConnectLife Wi-Fi module, the odds are good, and you can find
+out for certain in about a minute without opening anything.**
+
+Two things have to be true. The bus protocol has to match, and the module has to be one you can
+either reflash or replace.
+
+## Confirmed working
+
+| | |
+|---|---|
+| **Wi-Fi module** | `AEH-W41H1` (Realtek RTL8710C / AmebaZ2), secure boot off |
+| **App it came with** | ConnectLife |
+| **Bus** | RS-485, 9600 8N1, on the 4-pin module connector (5 V · GND · A · B) |
+| **Verified on** | two units, running continuously |
+
+Both the protocol and the flashing route are proven on this hardware. Everything on this site was
+written from those units.
+
+## Very likely, not personally verified
+
+**Other Hisense units using the same module family.** The `AEH-W4A1` appears throughout the
+reference material this project built on and speaks the same bus. The protocol work should carry
+over; the flashing details may differ.
+
+**Other brands on the same bus.** This A/C bus is not Hisense-only. The community
+[`esphome_airconintl`](https://github.com/pslawinski/esphome_airconintl) project drives the identical
+protocol on AirconIntl hardware, which is why the codec here could be cross-checked against its
+sample frames before it ever touched an A/C. Hisense manufactures for several brands, so a
+rebadged unit may well be the same machine underneath.
+
+Being honest about the boundary: "should work" is not "does work". If you try it on something not
+listed above, [open an issue](https://github.com/AndrewDemsDS/hisense-w41h1/issues) with what you
+find, working or not.
+
+## How to check your own unit
+
+**1. Does it use ConnectLife?** If your A/C pairs with the ConnectLife app, it is in the right
+family. Some regions ship the same hardware under a different app name.
+
+**2. Look at the module bay.** The Wi-Fi module is a small plastic dongle in a slot on the indoor
+unit, usually behind the front panel and reachable without tools. The part number is printed on it.
+
+**3. Count the pins.** Four pins (5 V, GND, and an RS-485 A/B pair) is the signature this project
+targets.
+
+## If your module is not supported, or is dead
+
+You do not need the original module. The [ESP32 route](guide/ESP32-Replacement-Build.html) puts an
+ESP32 plus an RS-485 transceiver in the module bay instead, speaking the same bus bytes. It costs
+about €5, needs no CH341A clip, and is the recommended path if you do not already have a working
+`AEH-W41H1` — those modules are fragile and increasingly hard to buy.
+
+The [path comparison](firmware/13-path-comparison.html) covers the tradeoffs with figures measured
+on real hardware.
+
+## What you get either way
+
+Local Matter control in Home Assistant with no cloud: mode, setpoint, six fan speeds, swing, and
+the Eco / Quiet / Turbo / Sleep special modes, plus temperature and energy telemetry. See
+[everyday control](guide/Everyday-Control.html).

docs-site/firmware/index.md

@@ -0,0 +1,11 @@
+---
+title: Firmware
+nav_order: 3
+has_children: true
+description: Build, OTA procedure, Matter clusters, attestation, QA strategy and energy monitoring for the custom firmware.
+---
+
+# Firmware
+
+How the firmware is built, versioned and shipped, what it exposes over Matter, and how it is tested
+without hardware.

docs-site/guide/index.md

@@ -0,0 +1,12 @@
+---
+title: Guide
+nav_order: 2
+has_children: true
+description: Wiring, flashing, commissioning, everyday control, OTA updates and recovery for a de-clouded Hisense A/C.
+---
+
+# Guide
+
+Everything needed to take a Hisense A/C off the ConnectLife cloud and run it locally, in the order
+you will need it: wiring, flashing, commissioning into Home Assistant, day-to-day control, OTA
+updates, and getting back out of trouble.

docs-site/index.md

@@ -1,5 +1,6 @@
 ---
 title: Hisense AEH-W41H1 de-cloud with custom Matter firmware
+nav_order: 1
 description: >-
   Replace the ConnectLife cloud on a Hisense AEH-W41H1 (Realtek RTL8710C / AmebaZ2) air-conditioner
   Wi-Fi module with custom Matter firmware for local Home Assistant control. Zero cloud.
@@ -20,21 +21,26 @@ Two hardware paths are documented and both are running on real units:
 Everything below is written from a working system, not a plan. The RS-485 protocol was
 reverse-engineered from the stock firmware and validated against live hardware.
 
+## Not sure if your A/C is supported?
+
+**[Check compatibility](compatibility.html)** — which units are confirmed, and how to tell in a minute
+without opening anything.
+
 ## Start here
 
 | | |
 |---|---|
-| [Hardware and wiring](guide/Hardware-and-Wiring) | pinout, the 4-pin module port, RS-485 A/B |
-| [Installing the custom firmware](guide/Installing-Custom-Firmware) | CH341A clip, or convert a stock unit over the air |
-| [Commissioning and Home Assistant](guide/Commissioning-and-HA-Setup) | pairing into python-matter-server and HA |
-| [Everyday control](guide/Everyday-Control) | modes, fan, swing, Eco / Quiet / Turbo / Sleep |
-| [OTA updates](guide/OTA-Updates) | Matter OTA, the break-glass HTTP path, and the serial trap |
-| [Recovery and reflash](guide/Recovery-and-Reflash) | getting back from a bad flash |
-| [FAQ and gotchas](guide/FAQ-Gotchas) | the things that actually bite |
+| [Hardware and wiring](guide/Hardware-and-Wiring.html) | pinout, the 4-pin module port, RS-485 A/B |
+| [Installing the custom firmware](guide/Installing-Custom-Firmware.html) | CH341A clip, or convert a stock unit over the air |
+| [Commissioning and Home Assistant](guide/Commissioning-and-HA-Setup.html) | pairing into python-matter-server and HA |
+| [Everyday control](guide/Everyday-Control.html) | modes, fan, swing, Eco / Quiet / Turbo / Sleep |
+| [OTA updates](guide/OTA-Updates.html) | Matter OTA, the break-glass HTTP path, and the serial trap |
+| [Recovery and reflash](guide/Recovery-and-Reflash.html) | getting back from a bad flash |
+| [FAQ and gotchas](guide/FAQ-Gotchas.html) | the things that actually bite |
 
 ## Choosing a path
 
-[ESP32 vs AmebaZ2](firmware/13-path-comparison) compares the two on cost, toolchain,
+[ESP32 vs AmebaZ2](firmware/13-path-comparison.html) compares the two on cost, toolchain,
 reproducibility, OTA mechanics, flash headroom and diagnostics, with figures measured on this
 project's own hardware rather than taken from datasheets.
 
@@ -43,17 +49,17 @@ project's own hardware rather than taken from datasheets.
 The protocol and firmware analysis, if you want to port this to another Hisense unit or verify the
 claims:
 
-- [RS-485 A/C protocol](internals/03-rs485-ac-protocol) — framing, checksum, every byte offset
-- [Stock firmware init and comms](internals/10-stock-fw-init-and-comms) — disassembly of the stock dongle
-- [Device-type to capability map](internals/11-model-capability-map) — how the A/C advertises its own features
-- [Hardware](internals/01-hardware) · [Cloud and firewall](internals/04-cloud-and-firewall) · [ESP32 replacement](internals/05-esp32-replacement)
+- [RS-485 A/C protocol](internals/03-rs485-ac-protocol.html) — framing, checksum, every byte offset
+- [Stock firmware init and comms](internals/10-stock-fw-init-and-comms.html) — disassembly of the stock dongle
+- [Device-type to capability map](internals/11-model-capability-map.html) — how the A/C advertises its own features
+- [Hardware](internals/01-hardware.html) · [Cloud and firewall](internals/04-cloud-and-firewall.html) · [ESP32 replacement](internals/05-esp32-replacement.html)
 
 ## Firmware and build
 
-- [Firmware build and OTA procedure](firmware/10-firmware-ota-procedure) — the canonical reference
-- [Matter clusters exposed](firmware/01-expose-all-clusters) · [Attestation](firmware/02-fix-attestation)
-- [QA strategy](firmware/04-qa-strategy) · [Energy monitoring](firmware/09-energy-monitoring)
-- [Stock parity gaps](firmware/07-stock-parity-gaps) — what the stock firmware does that this does not, yet
+- [Firmware build and OTA procedure](firmware/10-firmware-ota-procedure.html) — the canonical reference
+- [Matter clusters exposed](firmware/01-expose-all-clusters.html) · [Attestation](firmware/02-fix-attestation.html)
+- [QA strategy](firmware/04-qa-strategy.html) · [Energy monitoring](firmware/09-energy-monitoring.html)
+- [Stock parity gaps](firmware/07-stock-parity-gaps.html) — what the stock firmware does that this does not, yet
 
 ## Source
 

docs-site/internals/index.md

@@ -0,0 +1,12 @@
+---
+title: Reverse engineering
+nav_order: 4
+has_children: true
+description: The RS-485 protocol, stock firmware disassembly, and the device-type capability map behind this project.
+---
+
+# Reverse engineering
+
+The analysis this project is built on: the A/C's RS-485 protocol, the stock dongle's firmware, and
+how an A/C advertises which features it has. Read this if you want to port the work to another
+Hisense unit, or to check the claims rather than take them on trust.