Cómo actualizar este manual¶

Esta página es para quien mantenga el manual

Lo que viene a continuación es un mini-tutorial técnico pensado para alguien con perfil de desarrollador (o para que se lo pases a alguien que lo tenga). Si solo usas el manual, no necesitas leerlo: tu día a día está cubierto en el resto de páginas.

Las personas que mantienen el manual son las que editan los ficheros .md y despliegan los cambios al servidor.

Estructura¶

El manual vive en la carpeta manual/ del proyecto:

manual/docs/ — los textos en Markdown, una carpeta por rol.
manual/mkdocs.yml — el menú lateral y la configuración visual.
manual/site/ — la web final en HTML, lista para publicarse.

Cómo ver una vista previa local¶

Si quieres ver cómo queda antes de publicarlo:

Abre una terminal (en macOS: Spotlight → "Terminal").
Ve a la carpeta del manual:
```
cd manual
```

Crea el entorno virtual (solo la primera vez):

python3 -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt

Arranca el servidor de pruebas:
```
mkdocs serve
```
Abre http://localhost:8000 en tu navegador.
Cuando termines, para el servidor con Ctrl + C.

La vista previa se actualiza sola cuando guardas un archivo.

Cómo añadir una sección nueva¶

Crea un archivo .md dentro de manual/docs/. Por ejemplo: manual/docs/directora/alumnos/mi-pagina-nueva.md
Escribe dentro el contenido en Markdown. Un ejemplo mínimo:
```
# Título de la página
Aquí va el texto.
```

Abre manual/mkdocs.yml y añade en el sitio adecuado del menú:

nav:
  - Directora:
    - Alumnos:
      - Mi página nueva: directora/alumnos/mi-pagina-nueva.md

Guarda y, si tenías mkdocs serve abierto, verás el cambio automáticamente en el navegador.

Cómo añadir una captura de pantalla¶

Haz la captura con tu sistema operativo (en macOS: Cmd + Shift + 4 y selecciona la zona).
Guarda el archivo en manual/docs/assets/ con un nombre claro (por ejemplo, pantalla-alta-alumno.png). Evita usar nombres que apunten a capturas concretas que aún no existen — primero crea la imagen y luego la referencias desde el texto.
En el texto de la página, escribe la referencia a la imagen con una ruta relativa al directorio actual. Si la página está en manual/docs/directora/alumnos/alta.md y la imagen está en manual/docs/assets/pantalla.png, usa:
```
![Alta de alumno](../../assets/pantalla.png)
```
Listo. MkDocs la mostrará en la versión web.

Tamaño recomendado

Procura que las capturas no pasen de 1 MB. Si son muy grandes, puedes comprimirlas (por ejemplo con ImageOptim en macOS).

Cómo publicar una nueva versión¶

Cuando tengas lista la versión nueva:

Genera el sitio estático:
```
mkdocs build
```
Sube la carpeta site/ resultante al servidor. Tiene que quedar donde Caddy la pueda servir, normalmente /opt/hipica/site/.
```
rsync -az --delete \
  manual/site/ usuario@servidor:/opt/hipica/site/
```
Asegúrate de que el bloque de Caddy de manual.hipicalasrozas.com apunta a esa carpeta. Si aún no existe, míralo más abajo.
Espera unos segundos y refresca https://manual.hipicalasrozas.com/.

Cómo configurar Caddy (solo una vez)¶

Solo si Caddy aún no tiene el bloque de manual.hipicalasrozas.com

Si ya está sirviendo el manual, no toques nada. Habla con la Dirección si dudas.

Edita el archivo /opt/hipica/Caddyfile en el servidor y añade este bloque:

manual.hipicalasrozas.com {
    encode zstd gzip
    root * /opt/hipica/site
    file_server
}

Después, recarga Caddy:

docker compose -f /opt/hipica/compose.prod.yaml restart caddy

Cómo añadir el subdominio en el DNS (solo una vez)¶

Solo la primera vez

Si el dominio ya apunta a la IP del servidor, sáltate este paso.

En el panel DNS de Hostinger (lo gestiona Dirección):

Añade un registro tipo A:
Nombre: manual
Valor: la dirección IP del servidor (la misma que el resto de subdominios: 77.37.124.2).
Espera unos minutos a que se propague.

Si tienes dudas sobre cómo, mira el documento interno de despliegue del proyecto (pide a Dirección).

Resumen rápido¶

Editar local
    ↓ mkdocs serve (vista previa)
    ↓ mkdocs build (genera site/)
    ↓ rsync site/ al servidor
    ↓ Caddy sirve /opt/hipica/site
    ↓ manual.hipicalasrozas.com actualizado

Quién hace qué¶

la Dirección: edita el contenido en manual/docs/ (lo puede hacer con cualquier editor de texto).
Cualquiera con acceso al servidor: hace el paso 2 (subir la nueva versión).
Solo la Dirección: cambios en Caddy, DNS, o permisos.