--- title: Blocchi di contenuto order: 4.5 icon: phosphor-duotone:squares-four tags: [guide, markdown, gitbook] --- # Blocchi di contenuto Oltre a tutto quanto in [Estensioni Markdown](markdown.md), BxSites supporta una famiglia di blocchi di contenuto in stile GitBook - utili di per sé, e il motivo per cui il contenuto di un sito GitBook è semplice da migrare: ognuno di questi corrisponde direttamente a un blocco GitBook dello stesso nome. Ognuno usa la stessa sintassi contenitore `::: name ... :::` (un `:::` nudo su una riga a sé chiude qualsiasi blocco attualmente aperto) - nessuna configurazione di `bxsites.yaml` necessaria, sempre disponibile. Un blocco può essere annidato dentro un altro (un espandibile che contiene un gruppo di card, per esempio) - ognuno viene analizzato di nuovo per ulteriori blocchi al proprio interno. ## Espandibile Una sezione comprimibile semplice - nessuna icona/colore di richiamo, a differenza di un'ammonizione comprimibile (`???`, vedi [Ammonizioni](markdown.md#collapsible-admonitions)): ```markdown title="Esempio" linenums="1" ::: 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. ::: ``` ::: expandable "È diverso da un'ammonizione comprimibile?" Sì - questa non ha tipo/icona/colore, solo una semplice sezione espandi/comprimi. Aggiungi `open="true"` per farla iniziare espansa. ::: ## Card Una griglia di card di collegamento, ognuna un proprio `::: card` dentro un wrapper `::: cards` - `title`, `icon`, `image` e `href` sono tutti opzionali (una card senza `href` viene renderizzata come una card semplice, non cliccabile). `icon` viene risolta allo stesso modo dei valori `icon` di frontmatter/nav - una semplice emoji, oppure un'icona con nome da una libreria inclusa (`icon="phosphor-duotone:rocket-launch"`, `icon="lucide:rocket"`, ...) - vedi [Icone](icons.md): ```markdown title="Esempio" linenums="1" ::: 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. ::: ::: ``` ::: cards ::: card title="Per iniziare" icon="phosphor-duotone:rocket-launch" href="../getting-started.md" Installa, genera lo scheletro e compila il tuo primo sito. ::: ::: card title="Temi" icon="phosphor-duotone:palette" href="themes.md" Personalizza un tema integrato oppure scrivine uno tuo. ::: ::: ## Colonne Un layout affiancato - `::: column` accetta un `width` opzionale (una lunghezza/percentuale CSS semplice, ad es. `"40%"`); le colonne senza una larghezza esplicita condividono la riga in parti uguali: ```markdown title="Esempio" linenums="1" ::: columns ::: column width="60%" The wider column. ::: ::: column The narrower one. ::: ::: ``` ::: columns ::: column width="60%" La colonna più larga. ::: ::: column Quella più stretta. ::: ::: ## Stepper Una sequenza numerata e collegata di passaggi: ```markdown title="Esempio" linenums="1" ::: stepper ::: step "Install" `install-bx-module bx-sites` ::: ::: step "Scaffold" `bxSites new` ::: ::: ``` ::: stepper ::: step "Installazione" `install-bx-module bx-sites` ::: ::: step "Scheletro del progetto" `bxSites new` ::: ::: L'attributo opzionale `color` di un passo segna il proprio marcatore con uno di quattro colori semantici - il predefinito (nessun `color`), `success`, `warning` o `danger` - indipendentemente dalla posizione del passo nella sequenza: ```markdown title="Esempio" linenums="1" ::: 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. ::: ::: ``` ::: stepper ::: step "Fai un backup dei tuoi dati" color="success" Operazione di routine, sicura da eseguire in qualsiasi momento. ::: ::: step "Opzionale: attiva la telemetria" color="warning" Salta questo passo se non sei sicuro. ::: ::: step "Elimina la vecchia installazione" color="danger" Irreversibile - assicurati che il backup sopra sia terminato per primo. ::: ::: Il marcatore numerato, la linea di collegamento, e ognuna delle tre palette `color` sopra sono personalizzabili indipendentemente dal resto della palette del sito, tramite proprietà CSS personalizzate - vedi [Personalizzare i colori](themes.md#customizing-colors-without-a-theme-override). ## File Una card di download per un PDF, un video, o qualsiasi altro asset di progetto - `src` viene risolto allo stesso modo in cui lo sono già `theme.logo`/frontmatter `ogImage` (relativo a `docs/assets/`): ```markdown title="Esempio" linenums="1" ::: file src="assets/spec.pdf" title="API Specification" ::: ``` ::: file src="assets/og-image.png" title="Immagine di anteprima del sito" ::: ## Pulsanti Un pulsante di call-to-action in stile GitBook - un `::: button` da solo, oppure diversi allineati in riga dentro un wrapper `::: buttons`. L'etichetta iniziale tra virgolette e l'attributo `href` sono le uniche parti di cui la maggior parte dei pulsanti ha bisogno: ```markdown title="Esempio" linenums="1" ::: button "Get Started" href="../getting-started.md" style="primary" ::: ``` ::: button "Per iniziare" href="../getting-started.md" style="primary" ::: Alcuni attributi opzionali danno a ogni pulsante le proprie capacità: - `style="primary"` oppure `style="secondary"` (il valore predefinito) - tinta piena vs. contorno. - `size="small"`, `"medium"` (il valore predefinito) oppure `"large"`. - `icon="..."` - risolta allo stesso modo dell'`icon` di una card (una semplice emoji, oppure un'icona con nome come `icon="phosphor-duotone:rocket-launch"` - vedi [Temi: Icone](themes.md#icons)). - `target="_blank"` - apre il link in una nuova scheda invece che nella stessa (`rel="noopener noreferrer"` viene aggiunto automaticamente). - `disabled="true"` - renderizza un pulsante inerte, non cliccabile (non serve `href`) per una call-to-action del tipo "prossimamente". ```markdown title="Esempio" linenums="1" ::: buttons ::: button "Read the docs" href="../getting-started.md" icon="phosphor-duotone:book-open" size="large" ::: ::: button "Star on GitHub" href="https://github.com/ortus-boxlang/bx-sites" style="secondary" target="_blank" ::: ::: button "Coming soon" disabled="true" ::: ::: ``` ::: buttons ::: button "Leggi la documentazione" href="../getting-started.md" icon="phosphor-duotone:book-open" size="large" ::: ::: button "Metti una stella su GitHub" href="https://github.com/ortus-boxlang/bx-sites" style="secondary" target="_blank" ::: ::: button "Prossimamente" disabled="true" ::: ::: ## Embed Un embed responsivo in iframe per un provider riconosciuto - attualmente YouTube, Vimeo, CodePen, Spotify, Loom e Figma. Un URL da qualsiasi altra fonte ricade su una semplice card di link "visita ↗" invece di un iframe che si rifiuterebbe comunque di renderizzarsi (la maggior parte dei siti blocca l'essere incorniciata): ```markdown title="Esempio" linenums="1" ::: embed url="https://www.youtube.com/watch?v=dQw4w9WgXcQ" title="A demo" ::: ``` ::: embed url="https://www.youtube.com/watch?v=dQw4w9WgXcQ" title="Una demo" ::: ## Link a pagina Una card di anteprima ricca che rimanda a un'altra pagina - `href` segue la stessa convenzione relativa al file di un normale [link a pagina](../getting-started.md#linking-between-pages). A differenza di una card, il suo titolo/icona/riepilogo vengono ricavati automaticamente dal frontmatter proprio della pagina di destinazione, così resta sincronizzato se quella pagina viene rinominata o il suo riepilogo cambia: ```markdown title="Esempio" linenums="1" ::: page-link href="../getting-started.md" ::: ``` ::: page-link href="../getting-started.md" ::: ## Anteprima link Una card di anteprima ricca per un URL *esterno* - la stessa forma di card di `::: page-link`, ma per un link che non è una delle pagine del sito stesso, quindi non c'è alcuna pagina da cui ricavare automaticamente titolo/riepilogo. Ogni campo proviene dagli attributi propri della direttiva: solo `url` è obbligatorio, `title` ricade sull'URL nudo quando omesso, e `description`/`image` sono entrambi opzionali. Non c'è alcun recupero dell'URL di destinazione al momento del build per riempirli automaticamente - lo stesso ragionamento che mantiene [`check`](../cli-reference.md#check) limitato ai soli link interni si applica anche qui, così un sito di terze parti lento o irraggiungibile non influisce mai sul tempo di build: ```markdown title="Esempio" linenums="1" ::: link-preview url="https://boxlang.io" title="BoxLang" description="A dynamic, multi-paradigm JVM language." image="https://boxlang.io/og.png" ::: ``` ::: link-preview url="https://boxlang.io" title="BoxLang" description="Un linguaggio JVM dinamico e multi-paradigma." image="https://boxlang.io/og.png" ::: ## Prompt Un contenitore stilizzato per un prompt AI riutilizzabile - l'equivalente proprio di bx-sites del [blocco Prompt](https://gitbook.com/docs/create-content/blocks/prompt) di GitBook. Il corpo del blocco *è* il testo del prompt, scritto come normale Markdown (quindi intestazioni, elenchi e codice al suo interno ottengono comunque la propria formattazione); ogni prompt ottiene un pulsante "Copy" che copia esattamente quel testo sorgente, markup di formattazione incluso, pronto da incollare in qualsiasi strumento AI tu stia usando. `description` (un riepilogo opzionale su una riga) e `icon` (risolta allo stesso modo dell'`icon` propria di `::: card` - per impostazione predefinita, se omessa, un glifo a stellina) sono entrambi opzionali: ```markdown title="Esempio" linenums="1" ::: prompt description="Summarizes a pull request for a changelog entry" icon="phosphor-duotone:git-pull-request" Summarize the following pull request diff as a single changelog entry, written for an end user rather than a developer. Group related changes together and skip anything purely internal (refactors, tests, CI). ::: ``` ::: prompt description="Summarizes a pull request for a changelog entry" icon="phosphor-duotone:git-pull-request" Summarize the following pull request diff as a single changelog entry, written for an end user rather than a developer. Group related changes together and skip anything purely internal (refactors, tests, CI). ::: Aggiungi `expanded="preview"` per far vedere un prompt lungo in una breve anteprima con dissolvenza, finché chi legge non fa clic su "Show more", oppure `expanded="hidden"` per farlo iniziare completamente compresso dietro un pulsante "Show prompt" - comodo per una pagina che elenca più prompt uno di seguito all'altro. Ometti `expanded` (oppure impostalo su `"full"`, il valore predefinito) per mostrare sempre il prompt per intero: ```markdown title="Esempio" linenums="1" ::: prompt description="A longer, multi-step prompt" expanded="preview" 1. Read the attached error log line by line. 2. For each stack trace, identify the failing module. 3. Group failures by root cause, not by timestamp. 4. Propose one fix per root cause, not per failure. 5. Skip anything that already has an open issue - list those separately. ::: ``` ::: prompt description="A longer, multi-step prompt" expanded="preview" 1. Read the attached error log line by line. 2. For each stack trace, identify the failing module. 3. Group failures by root cause, not by timestamp. 4. Propose one fix per root cause, not per failure. 5. Skip anything that already has an open issue - list those separately. ::: A differenza del blocco Prompt proprio di GitBook, qui non c'è alcun menu "Open in AI providers" - bx-sites non comunica mai con un provider AI di terze parti, quindi quella parte del blocco proprio di GitBook non ha un equivalente. ## Aggiornamenti (changelog) Una lista di changelog datata e taggabile - `::: update` accetta `date="YYYY-MM-DD"` e un `tags` opzionale separato da virgole: ```markdown title="Esempio" linenums="1" ::: 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. ::: ::: ``` ::: updates ::: update date="2026-01-15" tags="funzionalità,correzione" Aggiunta la modalità scura e corretto un bug di allineamento del footer. ::: ::: update date="2026-01-01" Prima release. ::: ::: Una pagina con un blocco `::: updates` ottiene anche il proprio `feed.xml` (RSS 2.0) scritto accanto a sé una volta che `baseURL` di `bxsites.yaml` è un URL completo - lo stesso requisito di `sitemap.xml` - così i lettori possono iscriversi solo al changelog di quella pagina. ## Contenuto riutilizzabile (include) `::: include src="..."` inserisce il Markdown grezzo di un altro file in quel punto. A differenza di ogni blocco sopra, questo diventa vero contenuto di pagina (intestazioni, paragrafi, i propri blocchi annidati), non qualcosa avvolto in un widget - utile per un avviso/nota ripetuto su più pagine. Metti il partial stesso sotto `docs/includes/` - la stessa convenzione di cartella riservata di `assets/`/`versions/`/ `i18n/`/`blog/`. Un file sotto `includes/` non viene mai compilato come propria pagina e non compare mai in nav/ricerca/sitemap/tag - esiste solo per essere inserito in altre pagine: ```text title="Struttura di docs/" docs/ ├── index.md ├── includes/ │ ├── beta-notice.md │ └── legal/ │ └── terms.md └── guides/ └── deep/ └── setup.md ``` Uno `src` **nudo** (senza `./` o `../` iniziale) si risolve sempre rispetto al proprio `docs/includes/` dell'albero corrente, non importa quanto in profondità sia annidata la pagina che include - `guides/deep/setup.md` sopra raggiunge lo stesso file che raggiunge `index.md`, entrambi con esattamente lo stesso `src`: ```markdown title="Da index.md oppure da guides/deep/setup.md" ::: include src="beta-notice.md" ``` Uno `src` nudo può anche puntare a una sottocartella di `includes/` stessa: ```markdown title="Esempio" ::: include src="legal/terms.md" ``` Anteponi invece `./` o `../` a `src` per raggiungere un frammento adiacente alla pagina che non è pensato per vivere nella cartella centralizzata `includes/` - quella forma si risolve in modo relativo al file rispetto alla cartella propria della pagina *che include*, la stessa convenzione di un normale link a pagina: ```markdown title="Da guides/deep/setup.md, un livello sopra invece che centralizzato" ::: include src="../local-note.md" ``` Un albero versione/locale ottiene il proprio `includes/` allo stesso modo - una pagina sotto `docs/versions/2.0/` risolve uno `src` nudo rispetto a `docs/versions/2.0/includes/`, e una sotto `docs/i18n/es/` rispetto a `docs/i18n/es/includes/` - i partial di ogni albero sono propri, non condivisi con il `docs/includes/` dell'albero principale. Un file incluso può a sua volta includerne un altro (una catena circolare genera `BxSites.CircularInclude` al momento del build invece di ripetersi all'infinito). ## Contenuto condizionale Mostra una tra più varianti di un blocco in base a una scelta fatta dal lettore stesso - istruzioni "Free" contro "Pro" nella stessa pagina, ad esempio. Questo è un sito interamente statico senza alcuna identità del visitatore, quindi a differenza di una piattaforma con un vero backend, non c'è un "chi è questo lettore" valutato lato server - è il lettore stesso a scegliere, e la sua scelta viene semplicemente ricordata nel proprio browser (`localStorage`) anche per ogni pagina successiva: ```markdown title="Esempio" linenums="1" ::: audience-switcher key="plan" options="free:Free,pro:Pro" ::: ::: conditional key="plan" value="free" The Free plan includes basic search. ::: ::: conditional key="plan" value="pro" The Pro plan adds AI-assisted search and unlimited team seats. ::: ``` ::: audience-switcher key="plan" options="free:Free,pro:Pro" ::: ::: conditional key="plan" value="free" The Free plan includes basic search. ::: ::: conditional key="plan" value="pro" The Pro plan adds AI-assisted search and unlimited team seats. ::: `::: conditional key="..." value="..."` segna una variante; `key` è qualsiasi nome di preferenza tu stia usando per commutare (`"plan"` qui sopra, ma potrebbe altrettanto bene essere `"os"`, `"language"`, qualsiasi cosa), e `value` è l'impostazione per cui questo particolare blocco deve essere mostrato. Ogni variante viene sempre renderizzata nell'HTML - nascosta lato client, mai omessa - così un lettore con JavaScript disattivato (o un crawler di ricerca) vede comunque ogni variante invece di nessuna. `::: audience-switcher key="..." options="valore:Etichetta,valore:Etichetta,..."` è un controllo opzionale, già pronto all'uso - un pulsante per ogni opzione, che commuta immediatamente ogni blocco `::: conditional` che condivide quella stessa `key`, ovunque nella pagina. Non ti serve affatto: un link che termina con `?plan=pro` imposta automaticamente la stessa preferenza al caricamento (comodo per condividere un link diretto verso "la versione Pro di questa pagina"), e una sovrascrittura di tema propria di un progetto può chiamare direttamente `window.bxSitesSetPreference( key, value )` per pilotarla da un'interfaccia personalizzata invece.