"> NOMBRE — Lo que hace en una frase - SmallCountry " /> " />
Saltar a contenido

Estructura

4. Estructura de página por tipo

4.1 Ficha de servicio (fichas/programas/*.md, fichas/stacks/*.md, fichas/sistemas/*.md)

<div align="center">
  <img src="/assets/images/logos/NOMBRE.svg" alt="NOMBRE" width="100">
  <p style="...">tag1 · tag2 · tag3</p>
</div>

# NOMBRE — Lo que hace en una frase

Lo que sustituirá del mundo exterior.

## Como usuario
### Qué puedes hacer
### Cómo acceder
| Plataforma | Cómo |
| Navegador | url |
| Ubuntu | cliente |
| Android | app |
| FireTV | app / no aplica |
### Primeros pasos

## Integración con otros servicios de SmallCountry
| Servicio | Relación |

## Servicios que lo hacen posible

??? info "Para el administrador"
    Datos, ZFS, healthcheck, logs, backup, problemas

??? info "Para el arquitecto"
    Relaciones (mermaid), red, Pi-hole, Caddy, Authentik, orquestación

## Captura de pantalla
> 📸 Pendiente de captura

## 🌐 Enlaces de interés

4.2 Manifiesto (manifiesto/*.md)

# Título del principio

Párrafo de apertura.

---

## El problema que resolvemos
## Cómo lo hacemos posible
### Subtema
### Servicios que lo hacen posible
## En resumen
### Secciones relacionadas

4.3 Compromiso (compromisos/*.md)

# Para quién va dirigido

Párrafo de apertura.

---

## 1. Primer compromiso
### Cómo lo hacemos posible
### Servicios que lo hacen posible
## 2. Segundo compromiso
## En resumen
### Secciones relacionadas
### Roles

4.4 Página de bloque del manual (manual/bloques/*.md)

# Bloque X: Nombre

Breve introducción.

---

### [1. Título](enlace)
Resumen de 2-3 líneas.

---

4.5 Rol (manual/roles/*.md)

# Nombre mitológico — Función

Descripción.

## Relación con el ecosistema (tipo, grupo, panel, compromiso)
## Herramientas y servicios (tabla)
## Flujo de trabajo
## Relación con otros roles (tabla)
## Secciones relacionadas

4.6 Runbook (manual/runbooks/*.md)

# Runbook: Nombre

Badge de estado.

| Gravedad | Tiempo | Roles |
## Síntomas
## Diagnóstico (checklist)
## Resolución (checklist)
## Verificación
## Prevención

4.7 Proyecto (proyectos/*.md)

Los proyectos documentan clientes que usarán SmallCountry. Su estructura principal es libre (resumen, marca, producto, sistema tecnológico, formación...) pero deben cumplir:

Requisito Obligatorio
Badge de estado Sí
Tiempo verbal según estado Sí
Logo de SmallCountry inline en cada aparición Sí
Secciones relacionadas al final Sí
Back-link (← Proyectos) Sí
Sección de integración con SmallCountry Sí — siempre al final, antes de Hoja de Ruta

Regla de enlaces externos: los proyectos pueden enlazar al exterior en el cuerpo del texto para servicios, APIs o estándares que no existen en SmallCountry (ej: ORCID, GBIF (red mundial de datos de biodiversidad), Frictionless Data, DataCite, Creative Commons). Si el servicio tiene ficha en SmallCountry, el enlace debe ir a la ficha. No llevan sección ## 🌐 Enlaces de interés (eso es solo para fichas).

Secciones colapsables: como las fichas, los proyectos pueden usar ??? info para secciones de administrador y arquitecto que detallen aspectos técnicos de la integración con SmallCountry que no interesen al lector general.

4.8 Tarjeta de dashboard — Páginas portal e índice (*/index.md, */portada.md)

Las páginas que actúan como portal de sección (inicio, legal, operaciones, exploración, fichas, manual, manifiesto, compromisos) usan el componente grid cards de Material con este patrón:

<div class="grid cards" markdown>

-   :icon-name:{ .lg .middle } **[Título enlazado](destino.md)**

    Texto de gancho — una frase breve que invita a entrar.

    <details markdown="1"><summary>Pregunta que incita a desplegar</summary>

    Más información con [enlaces útiles](otra-pagina.md) integrados en el texto. Entre 40 y 80 palabras. Aquí se responde la pregunta del summary con contexto adicional y referencias cruzadas.

    </details>

</div>

Reglas obligatorias:

Elemento Formato Ejemplo
Icono :material-icono:{ .lg .middle } — Material Design monocolor :material-sprout:{ .lg .middle }
Título **[Texto enlazado](destino.md)** — en negrita Y enlace, en verde por defecto **[Proyectos de campo](proyectos/index.md)**
Gancho 1-2 líneas, sin negrita, sin enlaces. Frase breve que despierte interés Colmenas, frutales, gallinas, clima. Todo lo que crece tiene su dashboard.
Bloque expandible <details markdown="1"><summary>Pregunta atractiva</summary>Contenido con enlaces.</details> Ver ejemplo arriba
Enlaces en details Dentro del <details>, los enlaces son inline en el texto, no botones sueltos [Proyecto Clima](proyecto-clima.md) te dice qué tiempo va a hacer

Lo que NO se debe hacer:

❌ Incorrecto ✅ Correcto
Título sin enlace: **Título** Título enlazado: **[Título](destino.md)**
Usar :octicons-arrow-right-24: Ver → como CTA Poner los enlaces dentro del texto del <details>
Tarjeta sin bloque expandible Siempre incluir <details> con contenido adicional
Enlaces absolutos: /proyectos/corral/ Enlaces relativos: ../proyectos/corral-del-viento.md

Iconos recomendados por tipo de sección:

Sección Iconos sugeridos
Proyectos de campo :material-sprout: :material-leaf: :material-barley:
Stack tecnológico :material-chart-line: :material-server: :material-memory:
Documentación legal :material-gavel: :material-shield-lock: :material-brain:
Operaciones :material-shield-sun: :material-run-fast: :material-clipboard-list:
Filosofía / principios :material-script-text: :material-handshake: :material-bank:
Hogar / familia :material-home-heart: :material-home-lock: :material-image:
Educación :material-school: :material-book-open-page-variant:
Investigación :material-flask: :material-test-tube:
Producción / IA :material-movie-open: :material-robot:
Perfiles de entrada :material-home-heart: :material-tractor: :material-school: :material-flask: :material-movie-open: :material-wrench:

Regla de color: todos los iconos Material heredan el color de acento verde de SmallCountry (#4CAF50 / var(--md-accent-fg-color)). No usar FontAwesome coloreado en cards de portal/índice. FontAwesome solo para casos excepcionales donde no exista equivalente Material.

4.9 Sistema (sistemas/*.md)

Las 7 páginas de sistema documentan una visión global de cada subsistema de SmallCountry (infraestructura, observabilidad, identidad, automatización, IA local, energía, comunicaciones). Siguen este patrón:

# Nombre del sistema

Badge de estado.

## Descripción / Resumen
## Diagrama (mermaid)
## Componentes (tabla con enlaces a fichas)
## Detalles de arquitectura (??? info collapsible)
## Fichas relacionadas

Reglas obligatorias:

Elemento Formato
Frontmatter status: + layer: + tags: (ver sistema de metadatos)
Badge de estado Generado automáticamente por el sistema de metadatos tras el título
Descripción 2-3 párrafos explicando el propósito del subsistema y su relación con los principios
Diagrama Mermaid (flowchart o sequenceDiagram) que muestre el flujo o topología del sistema
Componentes Tabla con columnas: Componente, Función, Ficha (enlace a fichas/programas/*.md)
Detalles de arquitectura Bloque ??? info "Para el arquitecto" con configuración técnica, ZFS layout, asignación de LXC
Fichas relacionadas Lista al final del documento enlazando a todas las fichas mencionadas

4.10 Páginas de doble audiencia — Tabs usuario/técnico

Las páginas que pueden interesar tanto a lectores no técnicos como a administradores deben usar el patrón de tabs integrado de Material for MkDocs:

=== "👀 Para usuarios"

    Explicación en lenguaje llano. Analogías. Sin jerga.
    El usuario debe entender el QUÉ sin importarle el CÓMO.

=== "⚙️ Para técnicos"

    Detalles de implementación. Comandos. Configuraciones.
    Referencias a ADRs y fichas. El técnico necesita el CÓMO.

Reglas obligatorias:

  • La pestaña "Para usuarios" usa analogías, evita acrónimos sin explicar, y responde "¿qué gano yo con esto?"
  • La pestaña "Para técnicos" asume familiaridad técnica y enlaza a fichas, ADRs y runbooks
  • Toda página de manifiesto, compromiso, sistema y legal DEBE tener este patrón
  • Opcional en páginas de proyecto y operaciones
  • Ver ADR-034 para la justificación arquitectónica

4.11 Auto-generación de contenido dinámico

Algunas páginas obtienen su contenido de forma automática para evitar mantener listas manuales:

Dashboard de métricas: La landing page usa --8<-- "dashboard.md" para mostrar conteos (servicios, ADRs, proyectos, críticos). El archivo se genera desde scripts/generate_dynamic_content.py que cuenta archivos en el sistema.

Lista de ADRs: adr/index.md usa --8<-- "adrs.md" — la tabla de ADRs se genera desde el sistema de archivos.

Cards de proyectos: proyectos/index.md usa --8<-- "proyectos_cards.md" — las cards se generan desde sc_config.yml.

--8<-- "dashboard.md"     <!-- métricas para la landing -->
--8<-- "adrs.md"          <!-- tabla completa de ADRs -->
--8<-- "proyectos_cards.md"  <!-- cards de proyectos desde sc_config.yml -->

Reglas:

  • El contenido generado se escribe en _includes/ (fuera de docs/, para que MkDocs no lo escanee como páginas)
  • El script de generación es scripts/generate_dynamic_content.py
  • El script se ejecuta automáticamente en CI antes del build
  • NO modificar manualmente los archivos generados — se sobrescriben en cada build

4.12 Autosuficiencia de las páginas — prohibido páginas con solo enlaces

Toda página debe ser autoexplicativa: un lector debe poder entender de qué trata la página sin necesidad de hacer clic en ningún enlace.

Reglas obligatorias:

Elemento Obligatorio Ejemplo
Título descriptivo ✅ # Proyectos que usan SmallCountry, no # Proyectos
Párrafo introductorio ✅ 2-5 líneas que explican qué hay en la página y por qué importa
Cards con gancho ✅ Cada card tiene 1-2 líneas descriptivas ANTES del <details>
Enlaces solo como apoyo ✅ Los enlaces complementan, no son el contenido principal

Lo que NO se debe hacer:

❌ Incorrecto ✅ Correcto
Lista de enlaces sin descripción Card con título, gancho y <details>
"Para más info, ver [enlace]" El párrafo ya explica lo esencial; el enlace es extra
Página índice con solo - [Título](url) Página índice con cards que describen cada destino

Excepción: Las páginas generadas automáticamente (--8<--) cumplen con esta regla porque el script de generación incluye descripciones desde sc_config.yml.

5. Nomenclatura de dominios internos

Todos los servicios de SmallCountry usan el dominio .sc sin sufijo de nodo. El sufijo .<nodo> solo se usa en contextos de administración donde sea necesario distinguir físicamente entre máquinas (SSH, Proxmox UI, métricas por nodo).

Ejemplos correctos: inicio.sc, forgejo-sc.duckdns.org, vault.sc, docs.sc
Ejemplos incorrectos: ~~inicio.sc.ra~~, ~~forgejo.sc.ra~~

Fundamento: ADR-007.

10. Navegación

  • Toda página nueva debe añadirse al mkdocs.yml
  • La navegación entre páginas es automática: el pie muestra ← Anterior a la izquierda, el nombre de la sección actual en el centro y Siguiente → a la derecha, según el orden definido en mkdocs.yml
  • Las páginas independientes llevan ### Secciones relacionadas

11. Sistema de metadatos

Cada página de SmallCountry lleva un frontmatter YAML con dos campos obligatorios que alimentan el banner informativo que aparece tras el título:

Campos obligatorios

---
status: Definido      # Estado de madurez del contenido
layer: fundacional    # Capa documental a la que pertenece
---

Valores de status

Valor Badge Significado
Definido 📋 Definido Documentado y planificado. Pendiente de implementar o validar.
Conceptual 💡 Conceptual Idea documentada. Existe como concepto pero no está implementada.
Operativo ✅ Operativo En funcionamiento real. Se usa y mantiene activamente.
Aceptado 📌 Aceptado Decisión formal adoptada. Documentada y aceptada.

Valores de layer

Valor Badge Significado
fundacional ☠️ S — Supervivencia Capa base del sistema. Sin esto nada funciona.
arquitectonica 🔴 A — Crítico Decisiones arquitectónicas y servicios críticos.
operativa 🟠 B — Importante Procedimientos operativos. Su fallo afecta el día a día.
tactico 🟢 B — Táctico Herramientas de apoyo a la toma de decisiones.
referencial 🟡 C — Conveniente Documentación de referencia. Su falta no detiene el sistema.

Cómo se genera

  1. El frontmatter se define en cada archivo .md
  2. El template overrides/main.html inyecta <meta name="sc-status"> y <meta name="sc-layer"> en el <head>
  3. assets/javascripts/metadata.js los lee y construye el banner con:
  4. Estado: badge con tooltip explicativo
  5. Capa: badge con tooltip explicativo
  6. Sección: badge inferida de la URL
  7. El mismo JS inyecta un pie relacional con enlaces a páginas relacionadas según la sección

Archivos involucrados

  • overrides/main.html — inyección de meta tags desde page.meta
  • docs/assets/javascripts/metadata.js — lógica de lectura y renderizado
  • docs/assets/stylesheets/operacional.css — estilos del banner
  • scripts/validate_metadata.py — validación CI de los valores
📋 Relacionado con
🔧 Operaciones