Blocchi di contenuto

Blocchi di contenuto

Oltre a tutto quanto in Estensioni Markdown, BX Sites 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.json 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 Temi: 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"
:::

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

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.json è 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).