Banners del sitio

docmd proporciona un sistema de banners flexible y de múltiples posiciones que admite tanto barras de anuncios de ancho completo como tarjetas dedicadas para la barra lateral y la tabla de contenidos (TOC). Utilice banners para mostrar anuncios de versiones, alertas de mantenimiento, llamadas de patrocinio o campañas promocionales en toda su documentación.

Configuración rápida

Puede configurar un solo banner de anuncio superior con layout.banner, o configurar banners de múltiples posiciones con layout.banners en su docmd.config.json:

{
  "layout": {
    "banner": {
      "content": "**¡v0.9.6 ya está disponible!** Explore las nuevas funciones de Modo Enfoque y banners.",
      "type": "info",
      "dismissible": true,
      "link": { "text": "Notas del lanzamiento", "url": "/release-notes/0-9-6" }
    }
  }
}

{
  "layout": {
    "banners": {
      "top": {
        "content": "**¡v0.9.6 ya está disponible!** Descubra las últimas mejoras de documentación.",
        "type": "announcement",
        "dismissible": true,
        "link": { "text": "Novedades", "url": "/release-notes/0-9-6" }
      },
      "toc-top": {
        "image": "/assets/sponsor-badge.png",
        "alt": "Patrocinar Docmd",
        "content": "**Apoye la documentación de código abierto**",
        "link": { "text": "Hazte patrocinador", "url": "https://github.com/sponsors" }
      },
      "sidebar-bottom": {
        "icon": "book-open",
        "content": "¿Necesita soporte empresarial o temas personalizados?",
        "link": { "text": "Contáctenos", "url": "https://docmd.io/contact" }
      }
    }
  }
}

Posiciones de banner admitidas

docmd admite 7 posiciones de banner distintas:

Referencia de configuración

Cada objeto de banner dentro de layout.banners[posición] (o layout.banner para la barra superior) acepta las siguientes opciones:

Banners de tarjeta (Barra lateral y Tabla de contenidos)

Los banners de tarjeta (sidebar-top, sidebar-bottom, toc-top, toc-bottom) están diseñados específicamente como widgets compactos y no invasivos para contenido complementario, avisos de patrocinio o recursos para desarrolladores.

Valores predeterminados y persistencia

A diferencia de la barra de anuncios superior, los banners de tarjeta son persistentes por defecto (dismissible: false). Permanecen visibles en todas las páginas y no desaparecen al navegar.

Si desea que un banner de tarjeta sea descartable por el lector, configure explícitamente dismissible: true (o dismissable: true):

{
  "layout": {
    "banners": {
      "toc-top": {
        "image": "/assets/survey-banner.png",
        "content": "¡Complete nuestra breve encuesta para desarrolladores!",
        "dismissible": true,
        "link": { "text": "Iniciar encuesta", "url": "https://example.com/survey" }
      }
    }
  }
}

Al ser descartado, el estado se guarda en sessionStorage durante la sesión del navegador.

Herencia de versiones y anulaciones

En sitios con varias versiones (versions.all), las configuraciones de versión heredan automáticamente los banners del proyecto raíz. Una versión puede sobrescribir una posición específica sin perder los banners de la raíz:

{
  "layout": {
    "banners": {
      "top": { "content": "¡Bienvenido a nuestra documentación!" },
      "toc-top": { "image": "/assets/sponsor.png", "link": "https://docmd.io" }
    }
  },
  "versions": {
    "current": "v2",
    "all": [
      {
        "id": "v1",
        "dir": "docs-v1",
        "label": "v1.0",
        "banners": {
          "top": {
            "content": "⚠️ Estás viendo la documentación heredada v1. Cambia a v2 para ver las últimas funciones.",
            "type": "warning",
            "dismissible": false
          }
        }
      },
      {
        "id": "v2",
        "dir": "docs-v2",
        "label": "v2.0"
      }
    ]
  }
}

Estilos personalizados

Los banners se renderizan con clases BEM estándar:

• Banners: .docmd-banner (o .summer-banner en la plantilla Summer)
• Variantes de posición: .docmd-banner--pos-top, .docmd-banner--pos-sidebar-top, .docmd-banner--pos-toc-top, etc.
• Estilo de tarjeta: .docmd-banner--card
• Variantes de tipo: .docmd-banner--info, .docmd-banner--warning, .docmd-banner--success, .docmd-banner--danger

.docmd-banner--pos-toc-top {
  border-radius: 8px;
  border: 1px solid var(--docmd-color-border);
  box-shadow: 0 2px 8px rgba(0, 0, 0, 0.05);
}

.docmd-banner--announcement {
  background: linear-gradient(135deg, #4f46e5 0%, #7c3aed 100%);
  color: #ffffff;
}

Desactivar banners

Para desactivar banners:

• Establezca layout.banner en null u omítalo.
• En layout.banners, elimine la clave de posición o establézcala en null.
• En una página concreta, configure banner: null en el frontmatter.