Dev-server features

./run_dev.sh (or python3 docs/_lib/_serve.py) is more than a file server. Everything on this page exists only on the dev server: the published static site has none of it, and none of it changes your pages unless you use it.

Live reload and auto-wrap

The server watches the tree and, on every change, re-bakes the chrome, the nav and the search index, then reloads every open tab. Page additions, removals and renames reach every sidebar while it runs — no restart. Set NO_AUTOWRAP=1 to bake by hand.

Polling adapts: with no browser connected it scans every 30 s; with one connected it slows to every 3 s, 5 s and 15 s after 10 s, 1 min and 5 min without a change. Any change snaps it back to the --interval speed (0.5 s by default), so editing feels the same.

Settings and the LAN password

The server binds 0.0.0.0, so anyone on your LAN can open it. The ⚙ in the header opens the settings panel:

• Password protection — off by default. When on, LAN visitors need the password; optionally one login per IP lasts a day. The connection is plain HTTP: this keeps out casual visitors, not eavesdroppers.
• In-browser page editing — turns the ✏️ button and /__edit on or off.
• Re-bake on save — the auto-wrap above.

Settings are saved to docs/.site.json (gitignored). A password can also come from the DOCSITE_PASS environment variable, which then wins over the panel.

In-browser editing

When editing is on, ✏️ in the header opens the page's authored <main> source. Saving writes it back between the same <main class="doc-body"> markers and is refused if the file changed on disk since you opened it; the auto-wrap then re-bakes and reloads the page.

Mermaid diagrams

Write a <pre class="mermaid"> block and it renders as a diagram that follows the light / dark theme. Mermaid is fetched from a CDN only on pages that contain such a block. (This one works on the published site too.)

<pre class="mermaid">
flowchart LR
  A[Write page] --> B[Bake] --> C[Browse]
</pre>

Copy buttons

Any element with data-copy="<id>" copies the text of the element with that id when clicked — handy for commands and prompts. (Also works on the published site.)

<button data-copy="cmd">Copy</button>
<pre id="cmd">python3 docs/_lib/_wrap_handwritten.py</pre>