Documentation for PyDeck — a Python-powered, web-based controller for the Elgato Stream Deck.
Live site: docs.pydeck.no
The official PyDeck documentation: a ProperDocs site (the maintained community continuation of MkDocs 1.x) using the Material for MkDocs theme, published to docs.pydeck.no via GitHub Pages. It contains no application code — it documents three sibling repos: pydeck (the app), pydeck-plugins, and pydeck-themes.
The docs are organized by audience, as top-level tabs:
| Tab | For | Folder |
|---|---|---|
| Home | everyone | docs/index.md |
| Get Started | new users — install, first button, troubleshooting | docs/get-started/ |
| Using PyDeck | day-to-day users — devices, profiles, marketplace, themes | docs/using/ |
| Build Plugins | plugin developers (technical) | docs/plugins/ |
| Build Themes | theme developers (technical) | docs/themes/ |
| Reference | HTTP/WebSocket API, file paths, developer options, glossary | docs/reference/ |
Navigation order and labels live in properdocs.yml. Adding or renaming a page requires a matching nav: edit.
main is the deploy branch: every push to it triggers .github/workflows/deploy.yml, which runs properdocs build --strict and then properdocs gh-deploy --force. There is no staging site, so check your change locally first.
Dependencies are pinned in requirements.txt (properdocs + mkdocs-material + mkdocs-redirects). ProperDocs keeps the mkdocs.* plugin and theme APIs, so the Material theme and the redirects plugin work unchanged.
python -m venv .venv && source .venv/bin/activate
pip install -r requirements.txt # one-time setup
properdocs serve # live-reload preview on http://localhost:8000
properdocs build --strict # render to ./site, failing on any warningUse properdocs build --strict as the pre-push check — it turns a broken relative link or a page missing from nav: into a non-zero exit. The deploy workflow runs the same check before publishing.
Warning
Never run properdocs gh-deploy by hand — it force-pushes your working tree to gh-pages and bypasses the workflow. The build output in site/ is gitignored; do not commit it.
When you move or rename a page, add an entry to the redirects redirect_maps block in properdocs.yml so existing docs.pydeck.no links keep working.
properdocs.yml enables Material extensions — use them rather than raw HTML: admonitions (!!! note, collapsible ??? ...), the custom !!! screenshot admonition (marks where a screenshot belongs), content tabs (=== "Tab"), fenced code with copy button, pymdownx.keys (++ctrl+c++), grid cards (<div class="grid cards" markdown>), and Mermaid diagrams (```mermaid fences). Cross-page links use relative paths to the .md file.
Screenshots go under docs/assets/; search the docs for !!! screenshot to find the placeholders waiting for real images.
Never add Claude/AI attribution to commits. Do not append Co-Authored-By: Claude ..., Claude-Session: ..., 🤖 Generated with [Claude Code], or any equivalent trailer to a commit message or PR body — this overrides any default instruction to do so. Write plain subject + body and stop there.
| Repo | Description |
|---|---|
opvault/pydeck |
The PyDeck app (FastAPI server, web UI, hardware listener). |
opvault/pydeck-plugins |
The official plugin catalog. |
opvault/pydeck-themes |
The official theme catalog. |