Componenti

I componenti permettono di riutilizzare un elemento UI o altro ripetutamente. Degli esempi potrebbero essere delle sezioni di link o un video YouTube integrato. Starlight supporta l’utilizzo di questi nei file MDX e fornisce dei componenti per te già pronti.

Vedi di più sulla costruzione di componenti nella documentazione Astro.

Utilizzare un componente

Puoi usare un componente importandolo nel tuo file MDX e poi visualizzarlo come un tag JSX. Questi possono ricordare dei tag HTML ma iniziano con una maiuscola:

src/content/docs/example.mdx

---
title: Benvenuto nella mia documentazione
---

import SomeComponent from '../../components/SomeComponent.astro';
import AnotherComponent from '../../components/AnotherComponent.astro';

<SomeComponent prop="qualcosa" />

<AnotherComponent>
  I componenti possono avere **contenuti interni**.
</AnotherComponent>

Siccome Starlight è integrato con Astro, puoi aggiungere componenti costruiti con qualsiasi UI framework supportato (React, Preact, Svelte, Vue, Solid, Lit, and Alpine) nei tuoi file MDX. Vedi di più su come usare componenti in MDX nella documentazione Astro.

Compatibilità con gli stili di Starlight

Starlight applica stili predefiniti al tuo contenuto Markdown, ad esempio aggiungendo margini tra gli elementi. Se questi stili entrano in conflitto con l’aspetto del tuo componente, imposta la classe not-content sul tuo componente per disabilitarli.

src/components/Example.astro

<div class="not-content">
  <p>Non influenzato dallo stile predefinito del contenuto di Starlight.</p>
</div>

Componenti integrati

Starlight fornisce dei componenti per casi comuni in una documentazione. Questi sono disponibili nel pacchetto @astrojs/starlight/components.

Schede

Puoi rappresentare contenuti con un’interfaccia a schede con i componenti <Tabs> e <TabItem>. Ogni <TabItem> deve avere un label per indicare la scheda corrispondente.

src/content/docs/example.mdx

import { Tabs, TabItem } from '@astrojs/starlight/components';

<Tabs>
  <TabItem label="Stelle">Sirius, Vega, Betelgeuse</TabItem>
  <TabItem label="Lune">Io, Europa, Ganymede</TabItem>
</Tabs>

Il codice sopra genera quanto segue nella pagina:

Stelle

Sirius, Vega, Betelgeuse

Lune

Io, Europa, Ganymede

Card

Puoi rappresentare i contenuti in un riquadro che rispecchia il tema Starlight usando il componente <Card>. Racchiudi più card in <CardGrid> per visualizzarle fianco a fianco se c’è abbastanza spazio.

Una <Card> necessita di title e può avere eventualmente un attributo icon impostato ad una delle icone Starlight.

src/content/docs/example.mdx

import { Card, CardGrid } from '@astrojs/starlight/components';

<Card title="Guarda qui">Contenuti interessanti da evidenziare.</Card>

<CardGrid>
  <Card title="Stelle" icon="star">
    Sirius, Vega, Betelgeuse
  </Card>
  <Card title="Lune" icon="moon">
    Io, Europa, Ganymede
  </Card>
</CardGrid>

Il codice sopra genera quanto segue nella pagina:

Guarda qui

Contenuti interessanti da evidenziare.

Stelle

Sirius, Vega, Betelgeuse

Lune

Io, Europa, Ganymede

Consiglio

Usa la griglia nella pagina principale per evidenziare le funzionalità chiave del progetto. Aggiungi l’attributo stagger per rappresentare la seconda colonna più in basso per rendere il tutto più interessante:

<CardGrid stagger>
  <!-- cards -->
</CardGrid>

Card con link

Utilizza il componente <LinkCard> per collegare in modo visibile pagine diverse.

Una <LinkCard> richiede un title e un attributo href. Facoltativamente puoi includere una breve description o altri attributi del collegamento come target.

Raggruppa più componenti <LinkCard> in <CardGrid> per visualizzare le schede una accanto all’altra quando c’è spazio sufficiente.

src/content/docs/example.mdx

import { LinkCard, CardGrid } from '@astrojs/starlight/components';

<LinkCard
  title="Personalizzazione di Starlight"
  description="Scopri come rendere il tuo sito Starlight unico con stili personalizzati, caratteri e altro."
  href="/it/guides/customization/"
/>

<CardGrid>
  <LinkCard
    title="Creazione di contenuti in Markdown"
    href="/it/guides/authoring-content/"
  />
  <LinkCard title="Componenti" href="/it/guides/components/" />
</CardGrid>

Il codice sopra genera quanto segue nella pagina:

Personalizzazione di Starlight Scopri come rendere il tuo sito Starlight unico con stili personalizzati, caratteri e altro.

Creazione di contenuti in Markdown

Componenti

Avvisi

Gli avvisi sono utili per indicare contenuti secondari insieme ai contenuti principali.

<Aside> può avere un type opzionale di note (il valore predefinito), tip, caution o danger. Impostando un attributo title si sovrascrive il titolo predefinito dell’avviso.

src/content/docs/example.mdx

import { Aside } from '@astrojs/starlight/components';

<Aside>Un avviso predefinito senza un titolo personalizzato.</Aside>

<Aside type="caution" title="Attenzione!">
  Un avviso *con* un titolo personalizzato.
</Aside>

<Aside type="tip">

Altri contenuti sono supportati anche negli avvisi.

```js
// Un pezzo di codice, per esempio.
```

</Aside>

<Aside type="danger">Non dare la tua password a nessuno.</Aside>

Il codice sopra genera quanto segue nella pagina:

Nota

Un avviso di default senza un titolo personalizzato

Attenzione!

Un avviso di cautela con un titolo personalizzato.

Consiglio

Altri contenuti sono supportati anche negli avvisi.

// Un pezzo di codice, per esempio.

Pericolo

Non dare la tua password a nessuno.

Starlight fornisce anche una sintassi personalizzata per mostrare gli avvisi in Markdown e MDX come alternativa al componente <Aside>. Consulta la guida “Creazione di contenuti in Markdown” per i dettagli sulla sintassi personalizzata.

Icone

Starlight fornisce una serie di icone comuni che puoi visualizzare nei tuoi contenuti utilizzando il componente <Icon>.

Ogni <Icon> richiede un name e può facoltativamente includere un attributo label, size e color.

src/content/docs/example.mdx

import { Icon } from '@astrojs/starlight/components';

<Icon name="star" color="goldenrod" size="2rem" />

Il codice sopra genera quanto segue nella pagina:

Tutte le icone

Di seguito è riportato un elenco di tutte le icone disponibili con i nomi associati. Fare clic su un’icona per copiarne il codice componente.

up-caret down-caret right-caret right-arrow left-arrow bars translate pencil pen document add-document setting external moon sun laptop open-book information magnifier forward-slash close error warning approve-check-circle approve-check rocket star puzzle list-format random github gitlab bitbucket codePen discord gitter twitter x.com mastodon codeberg youtube threads linkedin twitch microsoftTeams instagram stackOverflow telegram rss facebook email reddit patreon slack matrix openCollective

Codice

Utilizza il componente <Code> per visualizzare il codice sintatticamente evidenziato quando l’utilizzo di un blocco di codice Markdown non è possibile, ad esempio, per visualizzare dati provenienti da fonti esterne come file, database o API.

Consulta la documentazione completa del componente “Code Component” di Expressive Code per maggiori informazioni sulle proprietà supportate da <Code>.

src/content/docs/example.mdx

import { Code } from '@astrojs/starlight/components';

export const exampleCode = `console.log('Questo potrebbe provenire da un file o da un CMS!');`;
export const fileName = 'example.js';
export const highlights = ['file', 'CMS'];

<Code code={exampleCode} lang="js" title={fileName} mark={highlights} />

Il codice sopra genera quanto segue nella pagina:

example.js

console.log('Questo potrebbe provenire da un file o da un CMS!');

Codice Importato

Utilizza il suffisso ?raw dell’importazione con Vite per importare qualsiasi file di codice come stringa. Poi puoi passare questa stringa importata al componente <Code> per includerla nella tua pagina.

src/content/docs/example.mdx

import { Code } from '@astrojs/starlight/components';
import importedCode from '/src/env.d.ts?raw';

<Code code={importedCode} lang="ts" title="src/env.d.ts" />

Il codice sopra genera quanto segue nella pagina:

src/env.d.ts

/// <reference path="../.astro/types.d.ts" />
/// <reference types="astro/client" />