"> Referencias - SmallCountry " /> " />
Saltar a contenido

Referencias

6. Reglas de enlaces

Origen Destino permitido
Cualquier página Fichas (/fichas/...)
Cualquier página Otras páginas internas
Solo fichas Enlaces externos (sección 🌐)
Nunca Enlace externo desde manifiesto, compromisos, manual, legal
Contexto Archivo Color Tamaño
Cabecera del sitio (header) /assets/logo.svg Blanco 2rem (CSS)
Intro del index (centrado) /assets/logo-accent.svg Verde #4CAF50 150px
Inline en texto /assets/logo-accent.svg Verde #4CAF50 1.2em

Formato inline exacto: 

<img src="/assets/logo-accent.svg" style="height:1.2em;vertical-align:text-bottom;" alt=""> **SmallCountry**

El logo inline debe aparecer en todas las apariciones de SmallCountry en el texto.

8. Logos de servicios

  • Todos en assets/images/logos/, formato SVG
  • Paleta unificada: verde Material (#4CAF50, #2E7D32, #1B5E20, #81C784, #E8F5E9)
  • Si no existe logo oficial, crear uno simple en la paleta verde
  • Nombre de archivo: nombre-del-servicio.svg

9. Voz y tono

  • Castellano, no español neutro
  • Tú, no usted
  • Presente para lo desplegado, futuro para lo definido, condicional para lo conceptual
  • Primera persona del plural solo en manifiesto y legal
  • Tercera persona en la documentación de operaciones

11. Screenshots

  • Sección ## Captura de pantalla antes de 🌐 Enlaces
  • Si no hay captura real: placeholder PNG + nota 📸 Pendiente de captura
  • Las capturas se guardan en assets/images/screenshots/

12. Código y comandos

Elemento Sintaxis
Comandos de terminal ```bash
Diagramas de arquitectura ```mermaid
Tablas de datos (LXC, IP, Tier) Tabla Markdown
Secciones colapsables ??? info "Título"

13. Proceso de creación de contenido

flowchart TD
    C1[1. Clasificar<br>Desplegado / Definido / Conceptual] --> C2[2. Elegir plantilla<br>según tipo de página]
    C2 --> C3[3. Escribir<br>siguiendo plantilla y tiempo verbal]
    C3 --> C4[4. Enlazar<br>solo fichas desde el cuerpo]
    C4 --> C5[5. Añadir al nav<br>actualizar mkdocs.yml]
    C5 --> C6[6. Verificar<br>properdocs build --strict]
    C6 --> C7[7. Commit<br>con mensaje descriptivo]
  1. Clasificar: ¿✅ Desplegado, 📋 Definido o 💡 Conceptual?
  2. Elegir plantilla: según el tipo de página
  3. Escribir: siguiendo la plantilla y el tiempo verbal correcto
  4. Enlazar: solo a fichas desde el cuerpo; externos solo en 🌐
  5. Añadir al nav: actualizar mkdocs.yml
  6. Verificar: properdocs build --strict sin errores
  7. Commit: con mensaje descriptivo

14. Diagramas Mermaid

Todo proceso secuencial de 3 o más pasos, flujo de datos, arquitectura de integración o procedimiento documentado debe llevar un diagrama Mermaid. El diagrama se coloca debajo del encabezado ## que introduce el proceso y encima de la lista numerada o checklist.

14.1 Tipos de diagrama y dirección

Propósito Tipo Dirección
Proceso paso a paso, procedimiento, flujo de trabajo flowchart TD Top-down (vertical)
Flujo de datos entre servicios, integración, red flowchart LR Left-right (horizontal)
Arquitectura con capas o zonas flowchart TD o LR con subgraph Según convenga

14.2 Formas

Significado Sintaxis Ejemplo
Inicio / fin ([Texto]) ([Inicio: verificación semanal])
Paso de proceso [Texto] [1. Exportar datos<br>a formatos estándar]
Decisión / bifurcación {Texto} {¿Dato dentro<br>de rango?}
Base de datos / almacenamiento [(Texto)] [(PostgreSQL)]

14.3 Etiquetas de nodo

  • En español, usando el mismo lenguaje que el resto de la página.
  • Descriptivas: nada de A, B, C ni abreviaturas de una letra. Cada nodo debe entenderse sin leer el texto circundante.
  • Los pasos numerados llevan el número delante: [1. Exportar datos...], [2. Verificar...].
  • Para nodos de servicio, usar el nombre completo: [Caddy LXC 102], no C.
  • Los saltos de línea dentro de un nodo se hacen con <br>.

14.4 Colores (solo cuando aporten significado)

Usar colores pastel de la paleta Material con texto oscuro legible. Los colores deben agrupar conceptos (ej. verde = operación, azul = seguridad, rosa = control, amarillo = humano).

Categoría fill stroke color
Control / verdad #f9a8d4 #c2185b #000
Seguridad / red #90caf9 #1565c0 #000
Operación / infraestructura #a5d6a7 #2e7d32 #000
Interacción humana #ffe082 #f57f17 #000
Emergencia / fallo #ef9a9a #c62828 #000

No usar colores en diagramas de 3-5 nodos que no ganen claridad con ellos. Los colores son para diagramas con subgrafos o muchas categorías distintas.

14.5 Subgrafos

Usar subgraph para agrupar nodos por zona (red interna, Zona Cero, IoT, IA), por fase (detección, diagnóstico, resolución) o por ubicación (Ra, Horus, Finca).

flowchart TD
    subgraph interna [Red interna]
        Caddy[Caddy LXC 102]
        Authentik[Authentik LXC 105]
    end

14.6 Estilo de flechas

Significado Sintaxis
Flujo normal -->
Flujo con etiqueta -->|Texto|
Flujo opcional / condicional -.->
Etiqueta en decisión (rama sí) -->|Sí|
Etiqueta en decisión (rama no) -->|No|

14.7 Ubicación en la página

  • Fichas (programas/stacks): el diagrama de integración va dentro de ??? info "Para el arquitecto", en la sección ## Integración con otros servicios de SmallCountry.
  • Manual (principios, mecanismos, runbooks): debajo del encabezado que describe el flujo.
  • Legal: debajo del encabezado del procedimiento.
  • Proyectos: dentro de ??? info "Para el arquitecto" en la sección de integración.
  • Operaciones: debajo del encabezado del proceso.

14.8 Lo que NO se debe hacer

❌ Prohibido ✅ Correcto
Nodos de una letra (A, B, C) [Caddy LXC 102]
Etiquetas en inglés en páginas en español Todo en español
graph LR (sintaxis obsoleta) flowchart LR
Nodos sin forma (Caddy --> Kavita) Caddy[Caddy] --> Kavita[Kavita]
Colores neón o ilegibles Colores pastel con texto #000
Diagramas sin start/end cuando hay proceso ([Inicio]) y ([Fin])
15+ nodos en un solo diagrama Dividir en subgrafos o diagramas separados
📋 Relacionado con
🔧 Operaciones