Bloques de Contenido

Cuadrículas de tarjetas, columnas, un stepper, tarjetas de archivo/incrustación/vista previa, un registro de cambios y contenido reutilizable.

Bloques de Contenido

Además de todo lo que hay en Extensiones de Markdown, BX Sites admite una familia de bloques de contenido al estilo GitBook - útiles por sí mismos, y la razón por la que el contenido de un sitio de GitBook es sencillo de migrar: cada uno de estos se corresponde directamente con un bloque de GitBook del mismo nombre. Cada uno usa la misma sintaxis de contenedor ::: name ... ::: (un ::: solo en su propia línea cierra el bloque que esté abierto en ese momento) - sin necesidad de configuración en bxsites.json, siempre disponible. Un bloque puede anidarse dentro de otro (un expandible que contiene un grupo de tarjetas, por ejemplo) - cada uno se vuelve a analizar en busca de más bloques dentro de su propio contenido.

Expandible

Una sección colapsable simple - sin icono/color de aviso, a diferencia de una admonición colapsable (???, consulta Admoniciones):

::: expandable "Is this different from a collapsible admonition?"
Yes - this has no type/icon/color, just a plain expand/collapse section.
Add `open="true"` to start it expanded.
:::

Tarjetas

Una cuadrícula de tarjetas de enlace, cada una su propia ::: card dentro de un envoltorio ::: cards - title, icon, image y href son todos opcionales (una tarjeta sin href se renderiza como una tarjeta simple, no clicable). icon se resuelve de la misma forma que los valores icon de frontmatter/nav - un emoji sencillo, o un icono con nombre de una biblioteca incluida (icon="phosphor-duotone:rocket-launch", icon="lucide:rocket", ...) - consulta Temas: Iconos:

::: cards
::: card title="Getting Started" icon="phosphor-duotone:rocket-launch" href="../getting-started.md"
Install, scaffold and build your first site.
:::
::: card title="Themes" icon="phosphor-duotone:palette" href="themes.md"
Customize a built-in theme or write your own.
:::
:::

Columnas

Un diseño lado a lado - ::: column acepta un width opcional (una longitud/porcentaje CSS simple, por ejemplo "40%"); las columnas sin un ancho explícito comparten la fila equitativamente:

::: columns
::: column width="60%"
The wider column.
:::
::: column
The narrower one.
:::
:::

Stepper

Una secuencia numerada y conectada de pasos:

::: stepper
::: step "Install"
`install-bx-module bx-sites`
:::
::: step "Scaffold"
`bxSites new`
:::
:::

El atributo color opcional de un paso marca su indicador con uno de cuatro colores semánticos - el predeterminado (sin color), success, warning o danger - independientemente de la posición del paso en la secuencia:

::: stepper
::: step "Back up your data" color="success"
Routine, safe to run any time.
:::
::: step "Optional: enable telemetry" color="warning"
Skip this one if you're not sure.
:::
::: step "Delete the old install" color="danger"
Irreversible - make sure the backup above finished first.
:::
:::

El indicador numerado, la línea de conexión y cada una de las tres paletas de color de arriba se pueden personalizar de forma independiente al resto de la paleta del sitio, mediante propiedades CSS personalizadas - consulta Personalizar colores.

Archivo

Una tarjeta de descarga para un PDF, video, o cualquier otro recurso del proyecto - src se resuelve de la misma forma que ya lo hacen theme.logo/el ogImage del frontmatter (relativo a docs/assets/):

::: file src="assets/spec.pdf" title="API Specification"
:::

Incrustación

Una incrustación de iframe responsiva para un proveedor reconocido - actualmente YouTube, Vimeo, CodePen, Spotify, Loom y Figma. Una URL de cualquier otro lugar recurre a una simple tarjeta de enlace "visit ↗" en lugar de un iframe que simplemente se negaría a renderizarse (la mayoría de los sitios bloquean ser incrustados en un frame):

::: embed url="https://www.youtube.com/watch?v=dQw4w9WgXcQ" title="A demo"
:::

Enlace de página

Una tarjeta de vista previa enriquecida que enlaza a otra página - href sigue la misma convención relativa a archivos que un enlace de página ordinario. A diferencia de una tarjeta, su título/icono/resumen se extraen automáticamente del propio frontmatter de la página de destino, así que se mantiene sincronizado si esa página se renombra o cambia su resumen:

::: page-link href="../getting-started.md"
:::

Vista previa de enlace

Una tarjeta de vista previa enriquecida para una URL externa - la misma forma de tarjeta que ::: page-link, pero para un enlace que no es una de las propias páginas de este sitio, así que no hay ninguna página de la que extraer automáticamente un título/resumen. Cada campo proviene de los propios atributos de la directiva: solo url es obligatorio, title recurre a la URL desnuda cuando se omite, y description/image son ambos opcionales. No hay ninguna obtención en el momento de la construcción de la URL de destino para autocompletar estos campos - el mismo razonamiento que mantiene a check limitado solo a enlaces internos se aplica también aquí, de modo que un sitio de terceros lento o inalcanzable nunca afecta al tiempo de construcción:

::: link-preview url="https://boxlang.io" title="BoxLang" description="A dynamic, multi-paradigm JVM language." image="https://boxlang.io/og.png"
:::

BoxLang

Un lenguaje JVM dinámico y multiparadigma.

boxlang.io

Novedades (registro de cambios)

Una lista de registro de cambios con fecha y etiquetable - ::: update acepta date="YYYY-MM-DD" y unas tags opcionales separadas por comas:

::: updates
::: update date="2026-01-15" tags="feature,fix"
Added dark mode and fixed a footer alignment bug.
:::
::: update date="2026-01-01"
Initial release.
:::
:::

Una página con un bloque ::: updates también obtiene su propio feed.xml (RSS 2.0) escrito junto a ella en cuanto baseURL de bxsites.json es una URL completa - el mismo requisito que sitemap.xml - de modo que los lectores puedan suscribirse solo al registro de cambios de esa página.

Contenido reutilizable (inclusiones)

::: include src="..." empalma el Markdown en bruto de otro archivo en ese punto. A diferencia de todos los bloques anteriores, esto se convierte en contenido de página real (encabezados, párrafos, sus propios bloques anidados), no algo envuelto en un widget - útil para una advertencia/aviso repetido en varias páginas. Coloca el propio parcial bajo docs/includes/ - la misma convención de carpeta reservada que assets//versions//i18n//blog/. Un archivo bajo includes/ nunca se construye como su propia página y nunca aparece en la navegación/búsqueda/sitemap/etiquetas - solo existe para empalmarse en otras páginas:

docs/
├── index.md
├── includes/
│   ├── beta-notice.md
│   └── legal/
│       └── terms.md
└── guides/
    └── deep/
        └── setup.md

Un src simple (sin ./ ni ../ iniciales) siempre se resuelve contra el propio docs/includes/ del árbol actual, sin importar cuán anidada esté la página que lo incluye - guides/deep/setup.md de arriba llega al mismo archivo que index.md, ambos con exactamente el mismo src:

::: include src="beta-notice.md"

Un src simple también puede apuntar a una subcarpeta del propio includes/:

::: include src="legal/terms.md"

Antepón ./ o ../ a src en su lugar para llegar a un fragmento adyacente a la página que no está pensado para vivir en el includes/ centralizado - esa forma se resuelve relativa al archivo, respecto a la propia carpeta de la página que incluye, la misma convención que un enlace de página ordinario:

::: include src="../local-note.md"

Un árbol de versión/idioma obtiene su propio includes/ de la misma forma - una página bajo docs/versions/2.0/ resuelve un src simple contra docs/versions/2.0/includes/, y una bajo docs/i18n/es/ contra docs/i18n/es/includes/ - los parciales de cada árbol son propios, no se comparten con el docs/includes/ del árbol principal.

Un archivo incluido puede a su vez incluir otro (una cadena circular lanza BxSites.CircularInclude en el momento de la construcción en lugar de entrar en un bucle infinito).