Blocchi di contenuto

Blocchi di contenuto

Oltre a tutto quanto in Estensioni Markdown, 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):

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

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

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

BoxLang

Un linguaggio JVM dinamico e multi-paradigma.

boxlang.io

Prompt

Un contenitore stilizzato per un prompt AI riutilizzabile - l'equivalente proprio di bx-sites del blocco 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:

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

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:

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