Temas

Temas

Los temas son plantillas .bxm nativas de BoxLang - no hay un motor de plantillas ni un paso de compilación separados involucrados.

Incorporados

Los siete temas bifurcados de material de arriba reutilizan las mismas plantillas BoxLang de material sin cambios (layout.bxm/page.bxm/search.bxm) salvo por un renombrado con prefijo de clase CSS acotado - solo assets/style.css difiere (y, en el caso de justthedocs, una línea <bx:include> reubicada que mueve el cuadro de búsqueda a la barra lateral), así que heredan el mismo conjunto completo de funciones y el mismo comportamiento apto para sitios sin conexión que ya tiene material.

El propio CSS/JS de cada tema incorporado (el paquete CSS/JS de Bootstrap, highlight.js, Alpine.js, lunr.js para el proveedor de búsqueda local predeterminado, y Mermaid cuando mermaid está activado) se incluye con este módulo y se copia directamente en cada site/ construido - sin CDN, sin necesidad de acceso a internet para ver un sitio construido. El propio motor de utilidades del tema tailwind (un compilador JIT del lado del cliente, no una hoja de estilo estática) y otras funciones opcionales que actives tú mismo (math, búsqueda de Algolia, Google Analytics) siguen cargándose desde un CDN o una API alojada - consulta Sitios sin conexión a internet más abajo.

bootstrap, material y tailwind aplican la misma paleta de marca de BoxLang (un degradado #00FF78 -> #00DBFF y un acento #FFF500); los siete temas de galería debajo de ellos usan cada uno su propia paleta distinta, inspirada en la plataforma de la que toman su look - consulta la tabla de arriba. Los diez incluyen, sin importar la paleta, el mismo conjunto de funciones de página:

• Una tabla de contenido "En esta página", generada a partir de los propios encabezados h2/h3 de cada página.
• Migas de pan, que muestran la cadena de ancestros de una página cuando está anidada más de un nivel bajo un ancestro enlazado.
• Enlaces de página anterior/siguiente al final del artículo, siguiendo el propio orden de lectura de la navegación.
• Bloques de código con resaltado de sintaxis, mediante highlight.js más una gramática de BoxLang propia (```bx/```boxlang/```cfscript), cada uno con un botón de copiar - mostrado al pasar el cursor en dispositivos que lo admiten, siempre visible en dispositivos táctiles (donde no hay hover para revelarlo). Consulta Extensiones de Markdown.
• Fuentes web autoalojadas - sin solicitudes a fonts.googleapis.com al momento de la visualización.
• Un interruptor de modo claro/oscuro, impulsado por Alpine.js para la reactividad. La elección del visitante se recuerda en localStorage (recurriendo a la preferencia de su sistema operativo), y se aplica antes del primer renderizado para evitar un destello del tema incorrecto.
• Una cabecera responsiva que se mantiene en una sola fila en cualquier ancho - una ventana estrecha reduce el cuadro de búsqueda en lugar de envolverlo en su propia línea - además de una barra lateral de navegación colapsable (un interruptor de hamburguesa en bootstrap/ material/tailwind por igual).
• Atajos de teclado en el cuadro de búsqueda: / enfoca la búsqueda desde cualquier lugar de la página, y Escape cierra los resultados. Consulta Búsqueda.
• Un enlace al repositorio y una línea "Edit this page"/"Last updated", cuando las opciones repo/lastUpdated de bxsites.yaml están configuradas. Consulta Configuración.
• Un enlace "Download Markdown", junto a "Edit this page" - la fuente .md en bruto de cada página se publica junto a su HTML construido (guides/themes.md situado junto a guides/themes/index.html), de modo que ella misma (o un LLM) pueda leer la página como Markdown simple directamente en lugar de analizar el HTML renderizado. Siempre activo, sin configuración necesaria. Consulta Primeros Pasos.
• Un pie de página opcional (copyright, enlaces social, un crédito "Built with BxSites") cuando el footer de bxsites.yaml es true. Consulta Configuración.
• Un selector de versión, que aparece automáticamente en cuanto un proyecto tiene una carpeta docs/versions/ con más de una versión en ella. Consulta Configuración.
• Un 404.html con el tema aplicado, servido automáticamente por la mayoría de los alojamientos estáticos (incluido GitHub Pages) para cualquier ruta sin coincidencia. Añade un 404.md en la raíz de docs/ (o src/) para sustituir su título y contenido por los tuyos - nunca se compila como una página normal (sin entrada en el nav, sin URL en sitemap.xml), solo se renderiza en su lugar como site/404.html.
• Un logo y favicon personalizados, cuando theme.logo/ theme.favicon de bxsites.yaml están configurados. Consulta Configuración.
• Una barra lateral de navegación colapsable, opcional mediante theme.options.navCollapsible. Consulta Configuración.
• Google Analytics, cuando analytics de bxsites.yaml está configurado. Consulta Configuración.
• Tarjetas para compartir en redes sociales (metaetiquetas Open Graph
  • Twitter Card), obtenidas del frontmatter description de cada página (o la description general del sitio) y su propio ogImage (o el general del sitio) - generadas automáticamente por página de forma opcional mediante generateOgImages de bxsites.yaml. Consulta Configuración.
• Etiquetas de página, un icono y una línea de resumen, todo opcional mediante el propio frontmatter de una página - las etiquetas se renderizan como insignias que enlazan a un índice /tags/ de todo el sitio. Consulta Primeros Pasos.
• Una navegación explícita personalizada, en bxsites.yaml o en su propio docs/nav.json, que reemplaza la inferencia por carpetas en sitios grandes. Consulta Configuración.
• CSS/JS adicional, inyectado mediante extraCss/extraJs de bxsites.yaml. Consulta Configuración.
• Cuadros de aviso (nota/advertencia/consejo/...), activos por defecto en el markdown de cualquier página, incluidas variantes colapsables - sin configuración necesaria. Consulta Extensiones de Markdown.
• Notas al pie y listas de definiciones, opcionales mediante markdown de bxsites.yaml. Consulta Extensiones de Markdown.
• Pestañas de contenido, números de línea de código/líneas resaltadas/títulos y marcadores de diff/marcos de terminal para bloques de código, sin configuración necesaria. Consulta Extensiones de Markdown.
• Diagramas Mermaid, opcionales mediante mermaid de bxsites.yaml. Consulta Extensiones de Markdown.
• Matemáticas (KaTeX), opcional mediante math de bxsites.yaml. Consulta Extensiones de Markdown.

Define cuál usa un proyecto en bxsites.yaml:

theme: { name: material }

{ "theme": { "name": "material" } }

Instalar un tema publicado

Un tema publicado en ForgeBox se instala sin nada más que el propio binario bxSites - no hace falta box/CommandBox. Explora lo ya publicado bajo la categoría bxsites-themes en ForgeBox:

bxSites install:theme --name=bx-sites-theme-blog1 [--version=1.0.0]

Esto descarga el zip del paquete y lo extrae en themes/bx-sites-theme-blog1/ en la raíz del proyecto, validando que cumple el contrato ThemeProvider de abajo antes de terminar. Un proyecto puede tener varios temas instalados en paralelo de esta forma, y cambiar entre ellos únicamente por nombre:

theme: { name: bx-sites-theme-blog1 }

{ "theme": { "name": "bx-sites-theme-blog1" } }

Un tema no necesita ninguna participación de módulo/cargador de clases de BoxLang (a diferencia de un plugin) - son archivos puros, así que no hay un paso de activación separado como sí tiene install:plugin; configurar theme.name es la única conexión necesaria. Consulta install:theme en la referencia de la CLI.

¿Partes de un tema construido para otro generador de sitios estáticos? Consulta Importar un tema - theme:import convierte mecánicamente los propios archivos de plantilla de un tema de mkdocs/jekyll/hugo en un scaffold themes/<name>/ de mejor esfuerzo.

Sitios sin conexión a internet (air-gapped)

Un sitio construido funciona sin ningún acceso a internet por defecto, para bootstrap, material y los siete temas bifurcados de material (docsy, slate, docusaurus, justthedocs, vuepress, gitbook, notion) con el proveedor de búsqueda local predeterminado: el propio CSS/JS de Bootstrap, highlight.js, Alpine.js y lunr.js vienen todos incluidos con este módulo (resources/assets/vendor/) y se copian directamente en site/assets/vendor/ en el momento de la construcción - sin ninguna etiqueta <script>/<link> a un CDN en ningún lugar del HTML generado para ninguno de ellos. Activar la clave mermaid de bxsites.yaml incluye Mermaid de la misma forma - su paquete mermaid.min.js se copia en site/assets/vendor/mermaid/ y cada tema incorporado lo carga desde ahí, de modo que los diagramas se siguen renderizando con cero solicitudes salientes.

Todavía hay algunas cosas que se comunican con la red, solo cuando tú mismo las activas:

• El propio motor de utilidades del tema tailwind es un compilador JIT del lado del cliente cargado desde cdn.tailwindcss.com - no es una hoja de estilo estática que este módulo pueda incluir de la misma forma, así que este tema todavía no es apto para sitios sin conexión.
• El propio motor de diseño de Mermaid carga de forma diferida un fragmento adicional, elk-api.js, desde jsDelivr - pero solo para los tipos de diagrama que optan por el algoritmo de diseño elk; el mermaid.min.js incluido renderiza por sí solo cualquier otro tipo de diagrama.
• La opción math de bxsites.yaml carga KaTeX (tanto su JS como sus propios archivos de fuente) desde un CDN cuando está activada.
• searchProvider.provider: "algolia" y analytics.provider: "google" se comunican inherentemente con una API alojada/un endpoint de seguimiento - incluir el archivo JS localmente no eliminaría esa dependencia.

Si tu entorno de despliegue realmente no tiene ningún acceso a internet, limítate a bootstrap/material/uno de los siete temas bifurcados de material, al proveedor de búsqueda local predeterminado, evita los diagramas Mermaid con diseño elk si mermaid está activado, y deja desactivados math/Algolia/Analytics.

Consulta Iconos para saber cómo el propio frontmatter icon de una página (o el propio icon de una entrada de nav.json) se resuelve en un emoji, un icono con nombre de una de las ocho bibliotecas incluidas, o el SVG propio de un proyecto.

El contrato de ThemeProvider

Un tema es simplemente una carpeta con:

• layout.bxm (obligatorio) - el shell HTML exterior + la navegación. Recibe variables.page, variables.nav, variables.siteConfig, variables.themeDir y variables.basePath en el ámbito, e incluye el page.bxm hermano mediante #variables.themeDir#/page.bxm. variables.basePath es siempre una ruta relativa a la raíz que termina en / (/ por defecto, /my-docs/ cuando el baseURL de bxsites.yaml lo sobrescribe) - antepón ese prefijo a cada href/src interno, en lugar de codificar una / inicial de forma fija, para que el tema siga funcionando cuando el sitio se sirva desde una subruta.
• page.bxm (obligatorio) - el cuerpo del artículo. Renderiza variables.page.contentHtml - el markdown ya convertido.
• search.bxm (opcional) - el marcado del cuadro de búsqueda, incluido por layout.bxm solo cuando search de bxsites.yaml es true. Consulta Búsqueda.
• assets/ (opcional) - CSS/JS del tema, copiado a site/assets/theme/ en el momento de la construcción.

variables.page.editUrl/.lastUpdated (cadenas vacías cuando no están configuradas) y variables.siteConfig.repo/.social/.footer también están siempre disponibles, dando soporte a las funciones de enlace al repositorio/enlace de edición/última actualización/pie de página mencionadas arriba - un tema personalizado decide por sí mismo si y cómo renderizarlas, igual que todo lo demás. variables.versions ([ { label, url } ], con "Latest" primero) y variables.currentVersion (el label que se está renderizando en ese momento) dan soporte al selector de versión - vacío/"Latest" para un proyecto que no está versionado, así que un tema solo necesita renderizar un selector cuando variables.versions.len() gt 1. Todos los temas incorporados obtienen sus iconos de repositorio/redes sociales de una pequeña tabla de búsqueda SVG compartida, <bx:include template="#variables.moduleAssetsDir#/icons.bxm"> (define bxsitesIcon( name ), uno de github, twitter/x, rss, youtube, linkedin, facebook, bluesky, threads, slack, patreon, email, edit, clock, recurriendo a un glifo de enlace genérico) - un tema personalizado puede incluirlo de la misma forma, o proporcionar sus propios iconos por completo.

Una carpeta de tema a la que le falte cualquiera de los archivos obligatorios falla de inmediato con un error claro BxSites.InvalidTheme en el momento de la construcción, en lugar de un confuso error de plantilla en lo profundo del renderizado.

Personalizar colores sin sobrescribir un tema

Para un ajuste de color/fuente, bifurcar todo un tema es excesivo - cada tema incorporado lee su paleta de un puñado de propiedades CSS personalizadas en :root, redeclaradas bajo [data-theme="dark"] para el modo oscuro. El extraCss de bxsites.yaml se carga después de la propia hoja de estilo del tema, así que una redeclaración con la misma especificidad en él gana sin tocar resources/themes/ en absoluto:

extraCss: [ assets/brand.css ]

{ "extraCss": ["assets/brand.css"] }

/* docs/assets/brand.css - copiado a site/assets/brand.css en el momento de la construcción */
:root {
	--bxsites-gradient-start: #7C3AED;
	--bxsites-gradient-end: #DB2777;
	--bxsites-accent: #FBBF24;
	--bxsites-link: #7C3AED;
	--bxsites-link-hover: #9F5AF0;
}

[data-theme="dark"] {
	--bxsites-link: #C4B5FD;
	--bxsites-link-hover: #DDD6FE;
}

El propio conjunto del tema bootstrap (resources/themes/bootstrap/assets/style.css) es --bxsites-gradient-start/-end, --bxsites-accent, --bxsites-bg, --bxsites-text, --bxsites-sidebar-bg, --bxsites-sidebar-text, --bxsites-border, --bxsites-link, --bxsites-link-hover, --bxsites-code-bg, --bxsites-step-marker-bg, --bxsites-step-marker-text, --bxsites-step-line, --bxsites-step-success-bg/-text y --bxsites-step-warning-bg/-text/--bxsites-step-danger-bg/-text. Todo tema incorporado garantiza --bxsites-gradient-start/-end, --bxsites-accent y el conjunto --bxsites-step-* bajo esos nombres exactos, así que extraCss siempre puede redirigir el color de marca/los acentos del stepper sin importar el tema - pero solo bootstrap, slate y notion también exponen --bxsites-bg/-text/-sidebar-bg/-sidebar-text/-border/-link/-link-hover/-code-bg bajo esos nombres (justthedocs alias todos menos los dos -sidebar-* de la misma forma). El resto de los temas incorporados (material, tailwind, docsy, docusaurus, vuepress, gitbook) usan sus propios nombres de propiedad personalizada internos para ese segundo grupo (por ejemplo, el propio assets/style.css de material usa --md-bg/--md-ink/--md-link/...) - abre el assets/style.css propio de ese tema para encontrar sus nombres reales antes de sobrescribir uno de ellos mediante extraCss. Cualquier cosa más allá del color/fuente (diseño, añadir/quitar elementos de interfaz) necesita una sobrescritura real o un tema personalizado - ver abajo.

El resto respalda el bloque de directiva ::: stepper/::: step - --bxsites-step-marker-bg/-text son el color de fondo/texto del círculo numerado por defecto (bootstrap/material lo configuran por defecto al propio --bxsites-accent del tema; tailwind usa un par verde azulado/menta dedicado ya que no tiene un único token de acento compartido), --bxsites-step-line es la línea que conecta los pasos, y los pares -success/-warning/-danger respaldan el propio atributo opcional color="..." de un paso - a diferencia del marcador por defecto, estos tres son el mismo par fijo de fondo/texto tanto en modo claro como oscuro (una insignia autocontenida, no ligada al acento de marca del tema), así que no hay ninguna sobrescritura [data-theme="dark"] que redeclarar:

:root {
	--bxsites-step-marker-bg: #7C3AED;
	--bxsites-step-marker-text: #fff;
	--bxsites-step-success-bg: #059669;
	--bxsites-step-success-text: #fff;
}

[data-theme="dark"] {
	--bxsites-step-marker-bg: #C4B5FD;
	--bxsites-step-marker-text: #1b1f21;
}

Banner hero de la página de inicio

Todo tema incorporado incluye CSS para un banner de página de inicio a todo lo ancho, con una imagen de titular y botones de llamada a la acción - el propio docs/index.md de este mismo sitio lo usa. No hay ningún bloque de directiva ni configuración para ello, solo HTML plano que cualquier página puede colocar (una página de inicio es simplemente una página normal, con order: 1 o de otro modo la primera en la navegación):

<div class="bxsites-hero">
	<img class="bxsites-hero__banner" src="assets/home-banner.jpg" alt="...">
	<div class="bxsites-hero__actions">
		<a class="bxsites-hero__btn bxsites-hero__btn--primary" href="getting-started.md">Get Started</a>
		<a class="bxsites-hero__btn bxsites-hero__btn--secondary" href="https://github.com/your/repo">View on GitHub</a>
	</div>
</div>

bxsites-hero__btn--primary/--secondary son los dos mismos estilos de acento que ya usa cada tema en otros lugares - intercambia, quita o añade botones libremente, y redimensiona/reemplaza la propia imagen de bxsites-hero__banner mediante un src relativo a docs/assets/, de la misma forma en que se resuelve cualquier otra imagen.

Sobrescribir un tema

Coloca tu propio layout.bxm + page.bxm (y opcionalmente search.bxm / assets/) en una carpeta theme/ en la raíz de tu proyecto. BxSites prefiere una sobrescritura theme/ a nivel de proyecto tanto sobre un tema instalado en themes/<name>/ como sobre cualquier tema incorporado, siempre que satisfaga el contrato anterior - los temas incorporados bajo el propio resources/themes/ de este módulo son un buen punto de partida para copiar y adaptar. Orden de resolución completo: theme/ (esta sección) -> themes/theme.name/ (un tema instalado, si theme.name coincide con uno) -> un tema incorporado con el nombre theme.name.

Un ejemplo trabajado - partir de bootstrap e intercambiar su paleta de marca y su fuente de encabezados por las tuyas, manteniendo todo lo demás (navegación, búsqueda, modo oscuro, resaltado de código, ...) exactamente como ya funciona:

my-project/
├── bxsites.yaml
├── docs/
└── theme/                    ← project-level override, checked before any built-in theme
    ├── layout.bxm             ← copied from resources/themes/bootstrap/layout.bxm
    ├── page.bxm                ← copied from resources/themes/bootstrap/page.bxm, unchanged
    ├── search.bxm               ← copied unchanged
    └── assets/
        └── style.css              ← copied from bootstrap's assets/style.css, then edited

1. Copia los tres archivos .bxm y assets/style.css desde resources/themes/bootstrap/ de este módulo a theme/ de tu proyecto.

2. Edita solo lo que necesites cambiar. Para intercambiar la paleta de marca y la fuente, eso es solo la parte superior de theme/assets/style.css:

   :root {
   	--bxsites-gradient-start: #7C3AED;  /* was #00FF78 */
   	--bxsites-gradient-end: #DB2777;    /* was #00DBFF */
   	--bxsites-accent: #FBBF24;          /* was #FFF500 */
   }
   
   body {
   	font-family: "Inter", system-ui, sans-serif;  /* was "Poppins" */
   }
   

3. Ejecuta bxSites build (o serve mientras iteras) - BX Docs recoge theme/ automáticamente, sin necesidad de cambiar bxsites.yaml (una carpeta theme/ a nivel de proyecto siempre tiene precedencia sobre el tema incorporado nombrado en theme.name). Todo lo que no tocaste - el renderizado de la navegación, la búsqueda, el interruptor de modo oscuro, las anotaciones de código - sigue funcionando exactamente como lo hacía en el tema bootstrap original, ya que sigue siendo exactamente el mismo marcado layout.bxm/ page.bxm por debajo.

Una carpeta theme/ de proyecto es todo o nada, sin embargo - en cuanto BxSites encuentra una, se usa en lugar del tema incorporado por completo, así que igual necesita su propio layout.bxm + page.bxm aunque lo único que hayas cambiado sea assets/style.css (una carpeta a la que le falte cualquiera de los dos falla de inmediato con BxSites.InvalidTheme en lugar de recurrir silenciosamente al otro). Para un ajuste solo de CSS/sin .bxm, usa extraCss en su lugar - se superpone a cualquier tema que nombre bxsites.yaml, sin ninguna carpeta theme/ involucrada en absoluto. theme/ es para cuando también necesitas cambiar el propio marcado, que se cubre a continuación.

Escribir un tema desde cero

Un tema solo necesita los dos archivos obligatorios, así que aquí hay uno genuinamente mínimo - sin Bootstrap/Tailwind, sin modo oscuro, sin interfaz de búsqueda - para mostrar exactamente qué es obligatorio frente a lo que añaden los temas incorporados. Guarda ambos como theme/layout.bxm y theme/page.bxm en tu proyecto - una carpeta theme/ a nivel de proyecto se recoge automáticamente (como arriba), sin necesidad de cambiar bxsites.yaml:

<!-- theme/layout.bxm -->
<bx:script>
	function renderNav( required array nodes ) {
		var html = "<ul>"
		for ( var node in arguments.nodes ) {
			html &= "<li>"
			html &= len( node.url )
				? '<a href="' & variables.basePath & node.url & '">' & encodeForHTML( node.title ) & '</a>'
				: encodeForHTML( node.title )
			if ( node.children.len() ) {
				html &= renderNav( node.children )
			}
			html &= "</li>"
		}
		return html & "</ul>"
	}
</bx:script>
<bx:output>
<!DOCTYPE html>
<html lang="en">
<head>
	<meta charset="UTF-8">
	<title>#encodeForHTML( variables.page.title )# - #encodeForHTML( variables.siteConfig.name )#</title>
	<link rel="stylesheet" href="#variables.basePath#assets/theme/style.css">
</head>
<body>
	<header><a href="#variables.basePath#">#encodeForHTML( variables.siteConfig.name )#</a></header>
	<nav>#renderNav( variables.nav )#</nav>
	<main>
</bx:output>
<bx:include template="#variables.themeDir#/page.bxm">
<bx:output>
	</main>
</body>
</html>
</bx:output>

<!-- theme/page.bxm -->
<bx:output>
<article>
	<h1>#encodeForHTML( variables.page.title )#</h1>
	#variables.page.contentHtml#
</article>
</bx:output>

Eso es un tema completo y funcional - variables.page.contentHtml es el markdown ya convertido (resaltado de sintaxis, admoniciones, pestañas, matemáticas y todo lo demás), así que no queda nada por analizar, solo por maquetar. A partir de aquí, añade lo que sea que tengan los temas incorporados que realmente quieras: search.bxm (incluido solo cuando search de bxsites.yaml es true - consulta Búsqueda), un interruptor de modo oscuro (copia el par x-data/x-init de Alpine.js de la etiqueta <body> de resources/themes/bootstrap/layout.bxm y el bloque CSS [data-theme="dark"] correspondiente), migas de pan/ etiquetas/enlaces anterior-siguiente (page.bxm en cualquier tema incorporado muestra el patrón - cada uno es solo un if alrededor de una pequeña función de renderizado, todas impulsadas por campos ya presentes en variables.page), o una carpeta assets/ para tu propio CSS/JS, copiada a site/assets/theme/ automáticamente en el momento de la construcción.