Documentation Site
The documentation site is an optional component that serves the Otavi docs as a browsable website using Express and markdown-it.
Docker Deployment
The docs site is included in the standard docker-compose.yml stack as the docs container. It runs automatically alongside the hub.
No additional configuration is needed beyond setting the FQDN.
Configuration
Set the documentation site FQDN in your .env file:
OTAVI_DOCS_FQDN=docs.birdnet.example.com
Traefik routes HTTPS traffic for this FQDN to the docs container automatically via Docker labels in docker-compose.yml.
Standalone Deployment
The docs site can also be run independently:
cd docs
npm install
node server.js
By default it listens on port 80 (configurable via the PORT environment variable).
Writing pages
Pages are Markdown under guide/, reference/ and deployment/, listed in the sidebar in docs/server.js. The site uses the web app's look: its palettes, fonts and wordmark (docs/static/style.css; the font and the wordmark's o come from pnpm brand:assets), dark by default with a switch for light that each reader's browser remembers.
Badges
A badge labels what a sentence or a table cell applies to. Four kinds, one colour each:
| Write | Shows | For |
|---|---|---|
:level[hub], :level[team], :level[account], :level[satellite] |
Hub Team Account Satellite | the level a setting or rule applies at |
:role[viewer], :role[member], :role[admin], :role[owner], :role[hub admin] |
Member Hub admin | the lowest role that may do it |
:app[web], :app[phone], :app[pi], :app[hub], :app[worker] |
Web app Phone Raspberry Pi | where it runs or shows |
:since[hub 0.76.0], :since[Pi 1.6.5], :since[phone 1.28.0] |
hub 0.76.0 | the release it arrived in, linked to its changelog entry |
Versions need no markup: a release tag (vhub-0.64.0+, vsat-1.6.5, vapk-1.28.0), a pre-0.28 hub version (v0.29+) or a component with its full version (hub 0.76.0, Pi 1.6.5, phone 1.28.0) becomes a version badge by itself. BirdNET's model versions (v2.4) are left alone. A version whose release has no notes links to its minor version's group, or to nothing. The settings and permissions tables in reference/settings-and-permissions.md are generated with level and role badges (pnpm --filter @birdnet-ng/hub settings:docs).
Changelog
The Changelog section (/changelog/hub, /changelog/satellite, /changelog/mobile) is drawn from the repository's CHANGELOG.md at start-up, one page per release stream, grouped by minor version. The docs image copies the file, so a release shows up once the docs container is rebuilt. Releases before hub 0.28, when every component shared one version, are on the hub page.