Temi

Temi

I temi sono template nativi BoxLang .bxm - non c'è alcun motore di template separato o passaggio di build coinvolto.

Integrati

Il CSS/JS proprio di ogni tema integrato (il pacchetto CSS/JS di Bootstrap, highlight.js, Alpine.js, lunr.js per il provider di ricerca local predefinito, e Mermaid quando mermaid è attivato) viene incluso con questo modulo e copiato direttamente in ogni site/ compilato - nessuna CDN, nessun accesso a internet necessario per visualizzare un sito compilato. Il motore di utility proprio del tema tailwind (un compilatore JIT lato client, non un foglio di stile statico) e altre funzionalità opzionali che attivi tu stesso (math, ricerca Algolia, Google Analytics) continuano a caricarsi da una CDN o da un'API ospitata - vedi Siti air-gapped/offline più sotto.

Tutti e tre applicano la stessa palette del brand BoxLang: un gradiente #00FF78 -> #00DBFF e un accento #FFF500 - e tutti e tre includono lo stesso insieme di funzionalità di pagina:

• Un sommario "In questa pagina" in pagina, generato dalle intestazioni h2/h3 proprie di ogni pagina.
• Breadcrumb, che mostrano la catena di antenati di una pagina quando è annidata più di un livello sotto un antenato collegato.
• Link pagina precedente/successiva in fondo all'articolo, seguendo l'ordine di lettura della nav stessa.
• Blocchi di codice con evidenziazione della sintassi, tramite highlight.js più una grammatica BoxLang propria (```bx/```boxlang/```cfscript), ciascuno con un pulsante di copia - mostrato al passaggio del mouse sui dispositivi che lo supportano, sempre visibile sui dispositivi touch (dove non c'è hover per rivelarlo). Vedi Estensioni Markdown.
• Webfont autoospitati - nessuna richiesta a fonts.googleapis.com al momento della visualizzazione.
• Un interruttore modalità scura/chiara, alimentato da Alpine.js per la reattività. La scelta del visitatore viene ricordata in localStorage (ricadendo sulla preferenza del suo sistema operativo), e applicata prima del primo rendering per evitare un lampo del tema sbagliato.
• Un header responsivo che resta su una sola riga a qualsiasi larghezza - un viewport stretto restringe il box di ricerca invece di farlo andare a capo - più una nav laterale comprimibile (un interruttore a hamburger sia in bootstrap, sia in material, sia in tailwind).
• Scorciatoie da tastiera nel box di ricerca: / porta il focus sulla ricerca da qualsiasi punto della pagina, e Escape chiude i risultati. Vedi Ricerca.
• Un link al repository e una riga "Modifica questa pagina"/"Ultimo aggiornamento", quando le opzioni repo/lastUpdated di bxsites.json sono impostate. Vedi Configurazione.
• Un link "Scarica Markdown", accanto a "Modifica questa pagina" - il sorgente .md grezzo di ogni pagina viene pubblicato accanto al proprio HTML compilato (guides/themes.md si trova accanto a guides/themes/index.html), così una persona (o un LLM) può leggere la pagina come Markdown puro direttamente invece di analizzare l'HTML renderizzato. Sempre attivo, nessuna configurazione necessaria. Vedi Per iniziare.
• Un footer opzionale (copyright, link social, un credito "Built with BX Sites") quando footer di bxsites.json è true. Vedi Configurazione.
• Un selettore di versione, che appare automaticamente non appena un progetto ha una cartella docs/versions/ con più di una versione al suo interno. Vedi Configurazione.
• Un 404.html con tema applicato, servito automaticamente dalla maggior parte degli host statici (incluso GitHub Pages) per qualsiasi percorso non corrispondente.
• Un logo e una favicon personalizzati, quando theme.logo/ theme.favicon di bxsites.json sono impostati. Vedi Configurazione.
• Una nav laterale comprimibile, opzionale tramite theme.options.navCollapsible. Vedi Configurazione.
• Google Analytics, quando analytics di bxsites.json è configurato. Vedi Configurazione.
• Social share card (meta tag Open Graph + Twitter Card), ricavate dal frontmatter description di ogni pagina (o dalla description a livello di sito) e dal suo ogImage (o da quello a livello di sito) - generate automaticamente per pagina in modo opzionale tramite generateOgImages di bxsites.json. Vedi Configurazione.
• Tag di pagina, un'icona e una riga di riepilogo, tutti opzionali tramite il frontmatter di una pagina - i tag vengono renderizzati come badge che collegano a un indice /tags/ a livello di sito. Vedi Per iniziare.
• Una nav esplicita in sostituzione, in bxsites.json o nel proprio docs/nav.json, che sostituisce la deduzione dalle cartelle per siti di grandi dimensioni. Vedi Configurazione.
• CSS/JS extra, iniettati tramite extraCss/extraJs di bxsites.json. Vedi Configurazione.
• Box di richiamo per ammonizioni (nota/avviso/suggerimento/...), attivi di default nel markdown di qualsiasi pagina, incluse le varianti comprimibili - nessuna configurazione necessaria. Vedi Estensioni Markdown.
• Note a piè di pagina e liste di definizioni, opzionali tramite markdown di bxsites.json. Vedi Estensioni Markdown.
• Schede di contenuto, numeri di riga/righe evidenziate/titoli del codice e indicatori di diff/cornici terminale per i blocchi di codice, nessuna configurazione necessaria. Vedi Estensioni Markdown.
• Diagrammi Mermaid, opzionali tramite mermaid di bxsites.json. Vedi Estensioni Markdown.
• Matematica (KaTeX), opzionale tramite math di bxsites.json. Vedi Estensioni Markdown.

Imposta quale tema usa un progetto in bxsites.json:

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

Siti air-gapped/offline

Un sito compilato funziona senza alcun accesso a internet per impostazione predefinita, per i temi bootstrap e material con il provider di ricerca local predefinito: il CSS/JS proprio di Bootstrap, highlight.js, Alpine.js e lunr.js sono tutti inclusi con questo modulo (resources/assets/vendor/) e copiati direttamente in site/assets/vendor/ al momento del build - nessun tag <script>/ <link> verso una CDN in nessun punto dell'HTML generato per nessuno di questi. Attivare la chiave mermaid di bxsites.json include Mermaid nello stesso modo - il suo pacchetto mermaid.min.js viene copiato in site/assets/vendor/mermaid/ e ogni tema integrato lo carica da lì, così i diagrammi continuano a essere renderizzati con zero richieste in uscita.

Alcune cose comunicano ancora con la rete, solo quando le attivi tu stesso:

• Il motore di utility proprio del tema tailwind è un compilatore JIT lato client caricato da cdn.tailwindcss.com - non è un foglio di stile statico che questo modulo può includere allo stesso modo, quindi questo tema non è ancora predisposto per l'uso air-gapped.
• Il motore di layout proprio di Mermaid carica in modo differito un chunk aggiuntivo, elk-api.js, da jsDelivr - ma solo per i tipi di diagramma che optano per l'algoritmo di layout elk; il pacchetto incluso mermaid.min.js renderizza da solo ogni altro tipo di diagramma.
• L'opzione math di bxsites.json carica KaTeX (sia il suo JS sia i propri file font) da una CDN quando è attivata.
• searchProvider.provider: "algolia" e analytics.provider: "google" comunicano intrinsecamente con un'API ospitata/un endpoint di tracciamento - includere il file JS localmente non eliminerebbe questa dipendenza.

Se il tuo ambiente di distribuzione non ha davvero alcun accesso a internet, limitati a bootstrap/material, al provider di ricerca local predefinito, evita i diagrammi Mermaid con layout elk se mermaid è attivo, e lascia disattivati math/Algolia/analytics.

Icone

Il frontmatter icon di una pagina (mostrato accanto al suo titolo, e accanto alla sua voce nella nav laterale) accetta sia un'emoji/testo breve semplice - la forma originale, ancora pienamente supportata - sia un'icona con nome da una delle otto librerie autoospitate, tutte con licenza MIT/ISC e incluse in questo modulo (circa 16.200 icone combinate, nessuna CDN, nulla di aggiunto al peso di una pagina compilata oltre alla manciata di icone effettivamente usate - vedi IconResolver.bx):

---
icon: rocket
---

---
icon: lucide:rocket
---

---
icon: phosphor-bold:rocket
---

Un semplice rocket ricade su Phosphor, peso regolare. Phosphor include tutti e sei i suoi pesi, ciascuno con il proprio prefisso: phosphor-thin:, phosphor-light:, phosphor: (regolare, uguale al nome nudo), phosphor-bold:, phosphor-fill: e phosphor-duotone:. Usa il prefisso lucide: per Lucide, oppure tabler: per Tabler. Sfoglia la galleria di ciascun sito per il nome esatto - corrisponde esattamente al nome file incluso in questo modulo (minuscolo, con trattini, ad es. book-open, arrow-up-right; il sito di Phosphor mostra un selettore di peso - ciascuna delle sue sei opzioni lì corrisponde a uno dei sei prefissi phosphor[-weight]: di questo modulo).

Font Awesome non è deliberatamente incluso tra queste - il suo stile Duotone (e la maggior parte del suo set di icone dalla v6 in poi) è disponibile solo con Pro, non disponibile con una licenza che questo modulo possa includere e ridistribuire gratuitamente.

Anche un SVG del tuo progetto funziona - mettilo in docs/assets/icons/my-icon.svg e riferiscilo come icon: custom:my-icon.

Una voce di nav.json può impostare la propria icon, sovrascrivendo il frontmatter proprio della pagina di destinazione per quella singola voce:

{ "title": "Guides", "path": "guides/index.md", "icon": "lucide:book-open" }

Il contratto ThemeProvider

Un tema è semplicemente una cartella con:

• layout.bxm (obbligatorio) - il guscio HTML esterno + la nav. Riceve variables.page, variables.nav, variables.siteConfig, variables.themeDir e variables.basePath nello scope, e include il file gemello page.bxm tramite #variables.themeDir#/page.bxm. variables.basePath è sempre un percorso relativo alla radice che termina con / (/ di default, /my-docs/ quando baseURL di bxsites.json lo sovrascrive) - anteponilo a ogni href/src interno, invece di codificare un / iniziale fisso, così il tema continua a funzionare quando il sito viene servito da un sotto-percorso.
• page.bxm (obbligatorio) - il corpo dell'articolo. Renderizza variables.page.contentHtml - il markdown già convertito.
• search.bxm (opzionale) - il markup del box di ricerca, incluso da layout.bxm solo quando search di bxsites.json è true. Vedi Ricerca.
• assets/ (opzionale) - CSS/JS del tema, copiati in site/assets/theme/ al momento del build.

variables.page.editUrl/.lastUpdated (stringhe vuote quando non configurati) e variables.siteConfig.repo/.social/.footer sono sempre disponibili anch'essi, a supporto delle funzionalità di link al repository/link di modifica/ultimo aggiornamento/footer sopra descritte - un tema personalizzato decide da sé se e come renderizzarli, come tutto il resto. variables.versions ([ { label, url } ], con "Latest" per primo) e variables.currentVersion (l'etichetta label in fase di rendering in questo momento) sono a supporto del selettore di versione - vuoti/"Latest" per un progetto non versionato, quindi un tema deve renderizzare un selettore solo quando variables.versions.len() gt 1. I tre temi integrati ottengono le proprie icone repository/social da una piccola tabella SVG condivisa, <bx:include template="#variables.moduleAssetsDir#/icons.bxm"> (definisce bxsitesIcon( name ), uno tra github, twitter/x, rss, youtube, linkedin, facebook, bluesky, threads, slack, patreon, email, edit, clock, con un glifo di link generico come ripiego) - un tema personalizzato può includerla nello stesso modo, oppure fornire le proprie icone del tutto.

Una cartella tema a cui manca uno dei due file obbligatori fallisce subito con un chiaro errore BxSites.InvalidTheme al momento del build, invece di un confuso errore di template nel profondo del rendering.

Personalizzare i colori senza sovrascrivere un tema

Per una piccola modifica di colore/font, forkare un intero tema è eccessivo - ogni tema integrato legge la propria palette da una manciata di proprietà CSS personalizzate su :root, ridichiarate sotto [data-theme="dark"] per la modalità scura. L' extraCss di bxsites.json si carica dopo il foglio di stile proprio del tema, quindi una ridichiarazione con la stessa specificità al suo interno vince senza toccare affatto resources/themes/:

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

/* docs/assets/brand.css - copiato in site/assets/brand.css al momento del build */
: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;
}

L'insieme proprio del tema bootstrap (resources/themes/bootstrap/assets/style.css) è composto da --bxsites-gradient-start/-end, --bxsites-accent, --bxsites-bg, --bxsites-text, --bxsites-sidebar-bg, --bxsites-sidebar-text, --bxsites-border, --bxsites-link, --bxsites-link-hover e --bxsites-code-bg - material e tailwind seguono la stessa denominazione --bxsites-* con piccole variazioni proprie. Qualsiasi cosa oltre a colore/font (layout, aggiungere/rimuovere elementi di contorno) richiede una vera sovrascrittura o un tema personalizzato - vedi sotto.

Sovrascrivere un tema

Metti il tuo layout.bxm + page.bxm (e opzionalmente search.bxm / assets/) in una cartella theme/ alla radice del tuo progetto. BX Sites preferisce una sovrascrittura theme/ a livello di progetto rispetto a qualsiasi tema integrato, purché soddisfi il contratto sopra descritto - i temi integrati sotto resources/themes/ proprio di questo modulo sono un buon punto di partenza da copiare e adattare.

Un esempio pratico - parti da bootstrap e sostituisci la sua palette del brand e il font delle intestazioni con i tuoi, mantenendo tutto il resto (nav, ricerca, modalità scura, evidenziazione del codice, ...) esattamente come già funziona:

my-project/
├── bxsites.yaml
├── docs/
└── theme/                    ← sovrascrittura a livello di progetto, verificata prima di qualsiasi tema integrato
    ├── layout.bxm             ← copiato da resources/themes/bootstrap/layout.bxm
    ├── page.bxm                ← copiato da resources/themes/bootstrap/page.bxm, invariato
    ├── search.bxm               ← copiato invariato
    └── assets/
        └── style.css              ← copiato da assets/style.css di bootstrap, poi modificato

1. Copia i tre file .bxm e assets/style.css da resources/themes/bootstrap/ di questo modulo nel theme/ del tuo progetto.

2. Modifica solo ciò che serve cambiare. Per sostituire la palette del brand e il font, basta agire sulla parte iniziale di theme/assets/style.css:

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

3. Esegui bxSites build (o serve mentre iteri) - BX Docs recepisce theme/ automaticamente, nessuna modifica a bxsites.json necessaria (una cartella theme/ a livello di progetto ha sempre la precedenza sul tema integrato nominato in theme.name). Tutto ciò che non hai toccato - rendering della nav, ricerca, interruttore modalità scura, annotazioni del codice - continua a funzionare esattamente come nel tema bootstrap originale, dato che è sempre lo stesso identico markup layout.bxm/page.bxm sottostante.

Una cartella theme/ di progetto è comunque tutto-o-niente - una volta che BX Sites ne trova una, viene usata al posto del tema integrato per intero, quindi necessita comunque del proprio layout.bxm + page.bxm anche se l'unica cosa cambiata è assets/style.css (una cartella priva di uno dei due file fallisce subito con BxSites.InvalidTheme invece di ricadere silenziosamente su un altro tema). Per una modifica solo CSS senza .bxm, usa extraCss come sopra invece - si sovrappone a qualunque tema bxsites.json nomini, senza alcuna cartella theme/ coinvolta. theme/ serve per quando devi anche cambiare il markup stesso, argomento trattato di seguito.

Scrivere un tema da zero

Un tema necessita solo dei due file obbligatori, quindi ecco un esempio davvero minimale - niente Bootstrap/Tailwind, niente modalità scura, niente UI di ricerca - per mostrare esattamente cosa è richiesto rispetto a cosa aggiungono in più i temi integrati. Salva entrambi come theme/layout.bxm e theme/page.bxm nel tuo progetto - una cartella theme/ a livello di progetto viene recepita automaticamente (come sopra), nessuna modifica a bxsites.json necessaria:

<!-- 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>

Questo è un tema completo e funzionante - variables.page.contentHtml è il markdown già convertito (evidenziazione della sintassi, ammonizioni, schede, matematica e tutto il resto), quindi non c'è più nulla da analizzare, solo da impaginare. Da qui, aggiungi qualsiasi cosa dei temi integrati che vuoi davvero: search.bxm (incluso solo quando search di bxsites.json è true - vedi Ricerca), un interruttore modalità scura (copia la coppia x-data/x-init di Alpine.js dal tag <body> di resources/themes/bootstrap/layout.bxm e il blocco CSS [data-theme="dark"] corrispondente), breadcrumb/tag/link pagina precedente-successiva (page.bxm in qualsiasi tema integrato mostra lo schema - ognuno è solo un if intorno a una piccola funzione di rendering, tutti guidati da campi già presenti su variables.page), oppure una cartella assets/ per il tuo CSS/JS, copiata automaticamente in site/assets/theme/ al momento del build.