mkdocs.yml

# PiHerder user + developer wiki
# Build:  pip install -r requirements-docs.txt && mkdocs serve
# Deploy: GitHub Actions → Pages (Settings → Pages → Source: GitHub Actions)
# Workflow: .github/workflows/docs.yml · validate: mkdocs build --strict

site_name: PiHerder Docs
site_description: Operator and developer documentation for PiHerder — fleet management for Raspberry Pi and Linux hosts.
site_author: Bjorn Gluck
site_url: https://piherder-docs.hacknow.info/
repo_url: https://github.com/bjorngluck/piherder
repo_name: bjorngluck/piherder
edit_uri: edit/main/wiki/
docs_dir: wiki
site_dir: site
copyright: Copyright © 2026 Bjorn Gluck · MIT License

# Do not treat repo notes as site pages (README conflicts with index.md in strict mode)
exclude_docs: |
  README.md
  assets/screenshots/README.md

theme:
  name: material
  custom_dir: wiki/overrides
  # Official PiHerder mark (black-ink light variant; same family as app header)
  logo: assets/piherder-logo-header.png
  favicon: assets/favicon.png
  language: en
  features:
    - navigation.instant
    - navigation.tracking
    - navigation.tabs
    - navigation.tabs.sticky
    - navigation.sections
    - navigation.expand
    - navigation.path
    - navigation.top
    - navigation.footer
    - search.suggest
    - search.highlight
    - search.share
    - content.code.copy
    - content.code.annotate
    - content.tabs.link
    - content.tooltips
    - toc.follow
  palette:
    - media: "(prefers-color-scheme)"
      scheme: default
      primary: red
      accent: green
      toggle:
        icon: material/brightness-auto
        name: System theme
    - media: "(prefers-color-scheme: light)"
      scheme: default
      primary: red
      accent: green
      toggle:
        icon: material/weather-sunny
        name: Light mode
    - media: "(prefers-color-scheme: dark)"
      scheme: slate
      primary: red
      accent: green
      toggle:
        icon: material/weather-night
        name: Dark mode
  font:
    text: Roboto
    code: Roboto Mono
  icon:
    repo: fontawesome/brands/github
    admonition:
      note: material/information-outline
      tip: material/lightbulb-outline
      warning: material/alert-outline
      danger: material/lightning-bolt
      success: material/check-circle-outline

extra_css:
  - stylesheets/extra.css

plugins:
  - search:
      lang: en
  - tags
  - minify:
      minify_html: true

markdown_extensions:
  - abbr
  - admonition
  - attr_list
  - def_list
  - footnotes
  - md_in_html
  - tables
  - toc:
      permalink: true
      toc_depth: 3
  - pymdownx.details
  - pymdownx.superfences:
      custom_fences:
        - name: mermaid
          class: mermaid
          format: !!python/name:pymdownx.superfences.fence_code_format
  - pymdownx.highlight:
      anchor_linenums: true
      line_spans: __span
      pygments_lang_class: true
  - pymdownx.inlinehilite
  - pymdownx.snippets:
      base_path:
        - .
        - wiki
      check_paths: true
  - pymdownx.tabbed:
      alternate_style: true
  - pymdownx.tasklist:
      custom_checkbox: true
  - pymdownx.emoji:
      emoji_index: !!python/name:material.extensions.emoji.twemoji
      emoji_generator: !!python/name:material.extensions.emoji.to_svg
  - pymdownx.keys
  - pymdownx.caret
  - pymdownx.mark
  - pymdownx.tilde

extra:
  social:
    - icon: fontawesome/brands/github
      link: https://github.com/bjorngluck/piherder
      name: GitHub
  generator: false


nav:
  - Home: index.md
  - Getting started:
      - Overview: getting-started/index.md
      - Requirements: getting-started/requirements.md
      - Install (Docker Compose): getting-started/install.md
      - First login: getting-started/first-login.md
      - Trusted HTTPS & TLS: getting-started/https-tls.md
      - Appearance (light / dark): getting-started/appearance.md
      - Operator scenarios: getting-started/operator-scenarios.md
  - Day to day:
      - Dashboard & Services: day-to-day/dashboard-and-services.md
      - Pins & host jump: day-to-day/navigation-pins.md
      - Add a server: day-to-day/add-server.md
      - HAOS hosts: day-to-day/haos-hosts.md
      - Backups & restore: day-to-day/backups.md
      - Updates & patching: day-to-day/updates-and-patching.md
      - Jobs, audit & notifications: day-to-day/jobs-audit-notifications.md
      - Remove a server: day-to-day/remove-server.md
  - Docker on hosts:
      - Overview: docker/overview.md
      - Inventory cache: docker/inventory.md
      - Compose edit & deploy: docker/compose-edit.md
  - Service templates:
      - Overview: service-templates/overview.md
      - Deploy a template: service-templates/deploy.md
      - From host: service-templates/from-host.md
      - Secrets model: service-templates/secrets.md
  - Integrations:
      - Overview (Catalog): integrations/overview.md
      - Uptime Kuma: integrations/uptime-kuma.md
      - Grafana: integrations/grafana.md
      - Pi-hole: integrations/pihole.md
      - Network maps: integrations/dns-fabric.md
      - LAN Discovery (nmap): integrations/lan-discovery.md
      - Nginx Proxy Manager: integrations/npm.md
      - Generic links (HA / Frigate / n8n): integrations/generic-links.md
      - Certificates: integrations/certificates.md
      - Obtain a cert (ACME): integrations/certificates-obtain-acme.md
  - Account & security:
      - Roles (RBAC): account-security/roles.md
      - Users: account-security/users.md
      - 2FA & force 2FA: account-security/two-factor.md
      - PWA & Web Push: account-security/pwa-push.md
  - Operations:
      - Environment reference: operations/env-reference.md
      - Volumes: operations/volumes.md
      - Settings: operations/settings.md
      - Stack Status: operations/status.md
      - Self-backup & DR: operations/self-backup.md
      - Upgrades: operations/upgrades.md
      - Multi-worker Celery: operations/multi-worker.md
      - Metrics & webhooks: operations/metrics-webhooks.md
      - Alerts (email & webhooks): operations/alerts-email-webhooks.md
      - API tokens: operations/api-tokens.md
  - Troubleshooting:
      - Overview: troubleshooting/index.md
      - Locked out / sole admin: troubleshooting/locked-out.md
      - SSH, rsync & dependencies: troubleshooting/ssh-rsync.md
      - Backups stuck or failing: troubleshooting/backups.md
      - Push / PWA: troubleshooting/push.md
      - Templates & Docker: troubleshooting/templates-docker.md
  - Developers:
      - Overview: developers/index.md
      - Local setup: developers/setup.md
      - Architecture: developers/architecture.md
      - Template schema: developers/templates-schema.md
      - Testing: developers/testing.md
      - Publish image: developers/publish-image.md
      - Contributing docs (versioning & screenshots): developers/contributing-docs.md