Salta ai contenuti
Starlight

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. Usa l’attributo opzionale icon per includere una delle icone integrate di Starlight accanto all’etichetta.

src/content/docs/example.mdx
import { Tabs, TabItem } from '@astrojs/starlight/components';


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

Il codice sopra genera quanto segue nella pagina:

Sirius, Vega, Betelgeuse

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

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:

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.

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

Albero di File

Utilizza il componente <FileTree> per visualizzare la struttura di una directory con icone dei file e directory chiudibili.

Specifica la struttura dei tuoi file e directory con una lista Markdown non ordinata all’interno di <FileTree>. Crea una sottodirectory utilizzando una lista nidificata o aggiungi un / alla fine di un elemento della lista per renderlo una directory senza contenuto specifico.

La seguente sintassi può essere utilizzata per personalizzare l’aspetto dell’albero dei file:

  • Evidenzia un file o una directory rendendo il suo nome in grassetto, ad esempio **README.md**.
  • Aggiungi un commento a un file o a una directory aggiungendo più testo dopo il nome.
  • Aggiungi file e directory segnaposto utilizzando ... o … come nome.
src/content/docs/example.mdx
import { FileTree } from '@astrojs/starlight/components';


<FileTree>


- astro.config.mjs un file **importante**
- package.json
- README.md
- src
  - components
    - **Header.astro**
  - …
- pages/


</FileTree>

Il codice sopra genera quanto segue nella pagina:

  • astro.config.mjs un file importante
  • package.json
  • README.md
  • Directorysrc
    • Directorycomponents
      • Header.astro
    • …
  • Directorypages/
    • …

Passaggi

Utilizza il componente <Steps> per stilizzare liste numerate di passaggi. Questo è utile per guide passo-passo più complesse in cui ogni passo deve essere chiaramente evidenziato.

Utilizza <Steps> in una lista ordinata standard di Markdown. Tutta la solita sintassi Markdown è applicabile all’interno di <Steps>.

src/content/docs/example.mdx
import { Steps } from '@astrojs/starlight/components';


<Steps>


1. Importa il componente nel tuo file MDX:


   ```js
   import { Steps } from '@astrojs/starlight/components';
   ```


2. Utilizza `<Steps>` intorno ai tuoi elementi della lista ordinata.


</Steps>

Il codice sopra genera quanto segue nella pagina:

  1. Importa il componente nel tuo file MDX:

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

  2. Utilizza <Steps> intorno ai tuoi elementi della lista ordinata.

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.