# hbox-docs — sitio de documentación técnica del HBOX

Sitio **MkDocs Material** (español) con el subconjunto de documentación del proyecto
Drogheda que los técnicos necesitan: procedimientos de banco, montaje/arneses,
diagnóstico remoto y la guía Git. Vive como **submódulo de Drogheda**, igual que el
repo de KiCad.

## Flujo de trabajo

```bash
# 1. actualizar el contenido desde Drogheda (la lista curada vive en el script)
./scripts/sync-docs.sh

# 2. ver el sitio en local
pip install mkdocs-material        # una sola vez
mkdocs serve                        # http://127.0.0.1:8000

# 3. commit + push de este repo (y bump del submódulo en Drogheda)

# 4. publicar al servidor
./scripts/deploy.sh                 # leo@git.helgen.online:/srv/projects/hbox-docs/site (puerto 22)
```

**Política de publicación:** solo se publica lo que está en la lista de
`scripts/sync-docs.sh`. Nada de finanzas, briefs de diseño ni auditorías EMC; para
agregar un documento al sitio se agrega a esa lista (y con eso queda auditado en git).

## Configuración del servidor (una sola vez)

En el servidor (`git.helgen.online` u otro), como root:

```bash
mkdir -p /srv/projects/hbox-docs/site
chown -R leo:leo /srv/projects/hbox-docs           # el usuario con el que hace rsync deploy.sh

# usuarios para los técnicos (HTTP Basic)
apt install -y apache2-utils
htpasswd -c /etc/nginx/hbox-docs.htpasswd luz
htpasswd    /etc/nginx/hbox-docs.htpasswd leo
```

Bloque de nginx (por ejemplo `/etc/nginx/sites-available/hbox-docs`, con el certificado
que ya tenga el servidor o uno nuevo de certbot para `docs.helgen.online`):

```nginx
server {
    listen 443 ssl;
    server_name docs.helgen.online;

    # ssl_certificate     ... ;   # certbot --nginx -d docs.helgen.online
    # ssl_certificate_key ... ;

    root /srv/projects/hbox-docs/site;
    index index.html;

    auth_basic           "Helgen HBOX docs";
    auth_basic_user_file /etc/nginx/hbox-docs.htpasswd;

    location / {
        try_files $uri $uri/ =404;
    }
}
```

```bash
ln -s /etc/nginx/sites-available/hbox-docs /etc/nginx/sites-enabled/
nginx -t && systemctl reload nginx
```

Los técnicos entran a `https://docs.helgen.online` con su usuario y contraseña.
Alternativa sin subdominio: servirlo como `location /hbox/` dentro del server block
existente, con el mismo `auth_basic`.

## Estructura

```
mkdocs.yml            configuración del sitio (nav, tema, español)
docs/                 contenido publicado (generado por sync-docs.sh + index.md)
scripts/sync-docs.sh  lista curada Drogheda → docs/
scripts/deploy.sh     mkdocs build --strict + rsync al servidor
```