Blocchi di contenuto

Blocchi di contenuto

Oltre a tutto quanto in Estensioni Markdown, BxSites supporta una famiglia di ricchi blocchi di contenuto per cose di cui il CommonMark puro non ha alcun concetto - card, sequenze a schede di passaggi, download, embed e altro ancora. Ognuno usa la stessa sintassi contenitore ::: name ... ::: (un ::: nudo su una riga a sé chiude qualsiasi blocco attualmente aperto, oppure scrivi il ::: di chiusura direttamente sulla stessa riga per un blocco senza un proprio corpo - ::: file src="assets/spec.pdf" ::: funziona esattamente come la forma su due righe) - 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. Stai migrando da GitBook? Ogni blocco qui corrisponde direttamente al proprio omologo GitBook dello stesso nome - vedi Migrare da GitBook.

Espandibile

Una sezione comprimibile semplice - nessuna icona/colore di richiamo, a differenza di un'ammonizione comprimibile (???, vedi Ammonizioni):

::: 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.
:::

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:

::: 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.
:::
:::

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:

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

Stepper

Una sequenza numerata e collegata di passaggi:

::: stepper
::: step "Install"
`install-bx-module bx-sites`
:::
::: step "Scaffold"
`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:

::: 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.
:::
:::

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.

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/):

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

Pulsanti

Un pulsante di call-to-action - 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:

::: button "Get Started" 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).
• 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".

::: 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" :::
:::

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):

::: embed url="https://www.youtube.com/watch?v=dQw4w9WgXcQ" title="A 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. 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:

::: 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 audit 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:

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

Prompt AI

Un contenitore stilizzato per un prompt AI riutilizzabile. 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:

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

::: 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.
:::

Qui non c'è alcun menu "Open in AI providers" - bx-sites non comunica mai con un provider AI di terze parti, quindi il pulsante "Copy" proprio di un prompt è l'unico modo per portarlo nello strumento che stai usando.

Aggiornamenti (changelog)

Una lista di changelog datata e taggabile - ::: update accetta date="YYYY-MM-DD" e un tags opzionale separato da virgole:

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

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:

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

Uno src nudo può anche puntare a una sottocartella di includes/ stessa:

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

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

::: 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.

Loop e condizionale (basati sui dati)

::: for e ::: if renderizzano il proprio contenuto rispetto ai dati riutilizzabili - il valore proprio di un file docs/data/*.yaml/.json, indirizzato per percorso puntato. A differenza di ogni blocco sopra, questi due accettano un'espressione nuda invece di attributi key="value" - deliberatamente ristretti, la stessa filosofia basata solo sul percorso puntato che {{ }} stesso già usa (nessun operatore di confronto in questa prima versione):

::: for member, idx in data.team
{{ idx }}. **{{ member.name }}** - {{ member.role }}
:::

1. Luis Majano - CEO

2. Jon Clausen - CTO

::: for <item>, <index> in <dotted.path> associa <item>/<index> nello stesso modo in cui lo fa il loop for a due variabili proprio di BoxLang, qualunque cosa risolva il percorso - elemento + indice a base 1 per un array (come sopra), oppure chiave + valore per uno struct, con la sintassi identica in entrambi i casi:

::: for name, enabled in data.flags
- {{ name }}: {{ enabled }}
:::

• betaBanner: true

• darkModeDefault: false

::: if <dotted.path> renderizza il proprio contenuto solo quando il valore risolto è veritiero - un array/struct/stringa vuoto, 0 e false contano tutti come falsi:

::: if data.flags.betaBanner
Beta features are enabled on this build.
:::

Le funzionalità beta sono attive in questa build.

Concatena ::: elseif <dotted.path> (un numero qualsiasi) e un ::: else nudo finale dopo un ::: if per una vera semantica if/elseif/else - la prima condizione veritiera vince, ::: else (senza una propria condizione) cattura tutto ciò che resta, e una condizione successiva a quella vincente non viene nemmeno risolta, quindi un percorso ::: elseif con un errore di battitura interrompe il build solo una volta che il proprio ramo viene effettivamente raggiunto. L'intera catena si chiude con un solo ::: finale - ::: elseif/ ::: else stessi segnano dove finisce il ramo precedente, quindi non serve alcun ::: prima di ciascuno di essi:

::: if data.flags.darkModeDefault
Dark mode is on by default.
::: elseif data.flags.betaBanner
Beta features are enabled, though dark mode isn't on by default.
::: else
Nothing special about this build.
:::

Le funzionalità beta sono attive, anche se la modalità scura non è attiva per impostazione predefinita.

Un ::: prima di un ::: elseif/::: else funziona comunque, se preferisci chiudere esplicitamente ogni ramo - entrambe le forme vengono analizzate in modo identico.

Entrambi i corpi possono contenere normale Markdown e persino altri blocchi di contenuto - incluso un altro ::: for/::: if, annidato esattamente come qualsiasi blocco sopra. Vedi File di dati: Usare i dati per il quadro completo di loop/condizionali, inclusi gli altri due modi per lavorare con data.* - una sovrascrittura di tema, oppure una funzione magica.

Indice del corso

::: course id="..." ::: renderizza tutte le lezioni di un intero corso come un unico indice numerato e collegato - un grande elenco "1. Introduzione, 2. Installazione su Windows, 3. Installazione su Mac..." in cui ogni numero è un link vero e proprio, costruito a partire da un manifest docs/data/courses.yaml invece che redatto a mano:

::: course id="getting-started" :::

A differenza di ogni blocco sopra, questo accetta solo un id nudo, senza un proprio href/corpo di contenuto - le lezioni stesse, e il loro ordine, provengono interamente dal manifest. Vedi Corsi per il formato del manifest, la navigazione lezione-per-lezione limitata al corso, e come vengono tracciati i progressi del lettore una volta che l'indice è presente sulla pagina.