string | BadgeConfig
+
+Agrega una insignia a la página en la barra lateral cuando se muestra en un grupo de enlaces generado automáticamente.
+Cuando se usa un string, la insignia se mostrará con el color de acento predeterminado.
+Opcionalmente, pasa un objeto [`BadgeConfig`](/es/reference/configuration/#badgeconfig) con los campos `text` y `variant` para personalizar la insignia.
+
+```md
+---
+title: Página con una insignia
+sidebar:
+ # Usa la variante predeterminada que coincide con el color de acento de tu sitio
+ badge: Nuevo
+---
+```
+
+```md
+---
+title: Página con una insignia
+sidebar:
+ badge:
+ text: Experimental
+ variant: caution
+---
+```
diff --git a/docs/src/content/docs/es/showcase.mdx b/docs/src/content/docs/es/showcase.mdx
index fc56e50d6ad..2a28fab0bac 100644
--- a/docs/src/content/docs/es/showcase.mdx
+++ b/docs/src/content/docs/es/showcase.mdx
@@ -10,84 +10,11 @@ description: ¡Descubre los sitios construidos con Starlight y herramientas comu
## Sitios
-import Card from '../../../components/showcase-card.astro';
-import FluidGrid from '../../../components/fluid-grid.astro';
+import ShowcaseSites from '../../../components/showcase-sites.astro';
Starlight ya está siendo utilizado en producción. Estos son algunos de los sitios en la web:
-{ \[dir: string\]: [LocaleConfig](#localeconfig) }
@@ -292,7 +304,7 @@ La locale par défaut sera utilisée pour fournir un contenu de remplacement lor
### `social`
-**type:** `Partialstring | BadgeConfig
+
+Ajoute un badge à la page dans la barre latérale lorsqu'elle est affichée dans un groupe de liens généré automatiquement.
+Lors de l'utilisation d'une chaîne de caractères, le badge sera affiché avec une couleur d'accentuation par défaut.
+Passez éventuellement un [objet `BadgeConfig`](/fr/reference/configuration/#badgeconfig) avec les propriétés `text` et `variant` pour personnaliser le badge.
+
+```md
+---
+title: Page avec un badge
+sidebar:
+ # Utilise la variante par défaut correspondant à la couleur d'accentuation de votre site
+ badge: Nouveau
+---
+```
+
+```md
+---
+title: Page avec un badge
+sidebar:
+ badge:
+ text: Expérimental
+ variant: caution
+---
+```
diff --git a/docs/src/content/docs/fr/showcase.mdx b/docs/src/content/docs/fr/showcase.mdx
index b553ae77861..482871bb6f1 100644
--- a/docs/src/content/docs/fr/showcase.mdx
+++ b/docs/src/content/docs/fr/showcase.mdx
@@ -10,84 +10,11 @@ Ouvrez une PR en ajoutant un lien à cette page !
## Sites
-import Card from '../../../components/showcase-card.astro';
-import FluidGrid from '../../../components/fluid-grid.astro';
+import ShowcaseSites from '../../../components/showcase-sites.astro';
Starlight est déjà utilisé en production. Voici quelques sites sur le web :
-
+
+ Halo Product Hunters 👋
+ Kami sedang live sekarang!
+
+
+hero:
+ title: Buat dokumentasi yang bersinar dengan Starlight
+ tagline: Semua yang Anda butuhkan untuk mewujudkan situs dokumentasi yang luar biasa. Cepat, ramah pengguna, dan sangat mudah digunakan.
+ image:
+ file: ../../../assets/hero-star.webp
+ actions:
+ - text: Memulai
+ icon: right-arrow
+ variant: primary
+ link: /id/getting-started/
+ - text: Lihat di GitHub
+ icon: external
+ link: https://github.com/withastro/starlight
+---
+
+import { CardGrid, Card } from '@astrojs/starlight/components';
+import AboutAstro from '../../../components/about-astro.astro';
+
+Controlla l'URL o prova a utilizzare la barra di ricerca. + actions: + - text: Torna alla home + icon: right-arrow + link: /it/ + variant: primary +--- diff --git a/docs/src/content/docs/it/getting-started.mdx b/docs/src/content/docs/it/getting-started.mdx index 96102aed030..49feb43e56f 100644 --- a/docs/src/content/docs/it/getting-started.mdx +++ b/docs/src/content/docs/it/getting-started.mdx @@ -117,3 +117,13 @@ yarn upgrade @astrojs/starlight --latest Puoi esplorare tutte le modifiche effettuate in ogni aggiornamento nel [changelog Starlight](https://github.com/withastro/starlight/blob/main/packages/starlight/CHANGELOG.md). + +## Risoluzione dei problemi relativi a Starlight + +Sia le informazioni sulla [configurazione del progetto](/reference/configuration/) che sulla [configurazione del frontmatter della singola pagina](/reference/frontmatter/) di Starlight sono disponibili nella sezione Riferimenti di questo sito. Utilizza queste pagine per assicurarti che il tuo sito Starlight sia configurato e funzioni correttamente. + +Consulta l'elenco crescente di guide nella barra laterale per ricevere assistenza nell'aggiunta di contenuti e nella personalizzazione del tuo sito Starlight. + +Se non è possibile trovare la risposta in questi documenti, visitare la [documentazione completa di Astro](https://docs.astro.build) per la documentazione completa di Astro. È possibile rispondere alla tua domanda comprendendo come funziona Astro in generale, sotto questo tema Starlight. + +Puoi anche verificare eventuali [problemi di Starlight noti su GitHub](https://github.com/withastro/starlight/issues) e ottenere assistenza nella sezione [Astro Discord](https://astro.build/chat/) dalla nostra comunità attiva e amichevole! Pubblica domande nel nostro forum `#support` con il tag "starlight" o visita il nostro canale dedicato `#starlight` per discutere dello sviluppo attuale e altro ancora! diff --git a/docs/src/content/docs/it/guides/authoring-content.md b/docs/src/content/docs/it/guides/authoring-content.md index 4b3c5038157..a857e9eec80 100644 --- a/docs/src/content/docs/it/guides/authoring-content.md +++ b/docs/src/content/docs/it/guides/authoring-content.md @@ -29,7 +29,7 @@ Puoi evidenziare `codice in linea` con apici inversi. ## Immagini -Le immagini in Starlight utilizzano l'ottimizzazione degli asset di Astro. +Le immagini in Starlight utilizzano [l'ottimizzazione degli asset di Astro](https://docs.astro.build/it/guides/assets/). Markdown e MDX supportano la sintassi Markdown per rappresentare immagini che includono testo alternativo per le tecnologie assistive. @@ -80,7 +80,7 @@ description: Come utilizzare i link automatici di Starlight ## Introduzione -Posso collegarmi alla [conclusione](#conclusione) che si trova più in basso. +Posso collegarmi alla [mia conclusione](#conclusione) che si trova più in basso. ## Conclusione @@ -89,9 +89,9 @@ Posso collegarmi alla [conclusione](#conclusione) che si trova più in basso. Titoli di livello 2 (`
`) e di livello 3 (``) verranno inclusi automaticamente nella tabella dei contenuti.
-## Asides
+## Aside
-Gli aside (conosciuti anche come "richiami") sono utili per indicare contenuti secondari insieme ai contenuti principali.
+Gli aside (conosciuti anche come "ammonizioni" o "richiami") sono utili per indicare contenuti secondari insieme ai contenuti principali.
Starlight fornisce una sintassi Markdown personalizzata per indicarli. I blocchi aside sono indicati da `:::` per racchiudere i contenuti e possono essere di tipo `note`, `tip`, `caution` o `danger`.
@@ -103,7 +103,7 @@ Dentro un "aside" puoi inserire qualsiasi altro contenuto Markdown anche se sono
Starlight è uno strumento per siti da documentazione con [Astro](https://astro.build/). Puoi iniziare con questo comando:
```sh
-npm run create astro@latest --template starlight
+npm run create astro@latest -- --template starlight
```
:::
@@ -114,7 +114,7 @@ Starlight è uno strumento per siti da documentazione con [Astro](https://astro.
Puoi iniziare con questo comando:
```sh
-npm run create astro@latest --template starlight
+npm run create astro@latest -- --template starlight
```
:::
diff --git a/docs/src/content/docs/it/guides/components.mdx b/docs/src/content/docs/it/guides/components.mdx
index 082e16b373c..07c6952a075 100644
--- a/docs/src/content/docs/it/guides/components.mdx
+++ b/docs/src/content/docs/it/guides/components.mdx
@@ -105,3 +105,66 @@ Aggiungi l'attributo `stagger` per rappresentare la seconda colonna più in bass
```
:::
+
+### LinkCard
+
+Utilizza il componente `` per collegare in modo visibile pagine diverse.
+
+Una `` richiede un `title` e un attributo [`href`](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/a#href). Facoltativamente puoi includere una breve `description` o altri attributi del collegamento come `target`.
+
+Raggruppa più componenti `` in `` per visualizzare le schede una accanto all'altra quando c'è spazio sufficiente.
+
+```mdx
+import { LinkCard, CardGrid } from '@astrojs/starlight/components';
+
+
+
+```
+
+Il codice precedente genera quanto segue nella pagina:
+
+import { LinkCard } from '@astrojs/starlight/components';
+
+
+
+
+### Icon
+
+import { Icon } from '@astrojs/starlight/components';
+import IconsList from '../../../../components/icons-list.astro';
+
+Starlight fornisce una serie di icone comuni che puoi visualizzare nei tuoi contenuti utilizzando il componente ``.
+
+Ogni `` richiede un [`name`](#all-icons) e può facoltativamente includere un attributo `label`, `size` e `color`.
+
+```mdx
+import { Icon } from '@astrojs/starlight/components';
+
+
+
+
+```sh
+npm create astro@latest -- --template starlight/tailwind
+```
+
+
+
+
+```sh
+pnpm create astro --template starlight/tailwind
+```
+
+
+
+
+```sh
+yarn create astro --template starlight/tailwind
+```
+
+
+
+
+### Aggiungi Tailwind a un progetto esistente
+
+Se hai già un sito Starlight e desideri aggiungere Tailwind CSS, segui questi passaggi.
+
+1. Aggiungi l'integrazione Tailwind di Astro:
+
+
+
+
+
+ ```sh
+ npx astro add tailwind
+ ```
+
+
+
+
+
+ ```sh
+ pnpm astro add tailwind
+ ```
+
+
+
+
+
+ ```sh
+ yarn astro add tailwind
+ ```
+
+
+
+
+
+2. Installa il plugin Starlight Tailwind:
+
+
+
+
+
+ ```sh
+ npm install @astrojs/starlight-tailwind
+ ```
+
+
+
+
+
+ ```sh
+ pnpm install @astrojs/starlight-tailwind
+ ```
+
+
+
+
+
+ ```sh
+ yarn add @astrojs/starlight-tailwind
+ ```
+
+
+
+
+
+3. Crea un file CSS per gli stili di base di Tailwind, ad esempio in `src/tailwind.css`:
+
+ ```css
+ /* src/tailwind.css */
+ @tailwind base;
+ @tailwind components;
+ @tailwind utilities;
+ ```
+
+4. Aggiorna il file di configurazione Astro per utilizzare gli stili di base Tailwind e disabilitare gli stili di base predefiniti:
+
+ ```js {11-12,16-17}
+ // astro.config.mjs
+ import { defineConfig } from 'astro/config';
+ import starlight from '@astrojs/starlight';
+ import tailwind from '@astrojs/tailwind';
+
+ export default defineConfig({
+ integrations: [
+ starlight({
+ title: 'Docs with Tailwind',
+ customCss: [
+ // Percorso per gli stili di base di Tailwind
+ './src/tailwind.css',
+ ],
+ }),
+ tailwind({
+ // Disattiva gli stili di base predefiniti
+ applyBaseStyles: false,
+ }),
+ ],
+ });
+ ```
+
+5. Aggiungi il plugin Starlight Tailwind a `tailwind.config.cjs`:
+
+ ```js ins={2,7}
+ // tailwind.config.cjs
+ const starlightPlugin = require('@astrojs/starlight-tailwind');
+
+ /** @type {import('tailwindcss').Config} */
+ module.exports = {
+ content: ['./src/**/*.{astro,html,js,jsx,md,mdx,svelte,ts,tsx,vue}'],
+ plugins: [starlightPlugin()],
+ };
+ ```
+
+### Styling di Starlight con Tailwind
+
+Starlight utilizzerà i valori della [configurazione del tema Tailwind](https://tailwindcss.com/docs/theme) nella sua interfaccia utente.
+
+Se impostate, le seguenti opzioni sovrascriveranno gli stili predefiniti di Starlight:
+
+- `colors.accent` — utilizzato per i collegamenti e per l'evidenziazione dell'elemento corrente
+- `colors.gray`: utilizzato per i colori e i bordi dello sfondo
+- `fontFamily.sans`: utilizzato per l'interfaccia utente e il testo del contenuto
+- `fontFamily.mono` — utilizzato per esempi di codice
+
+```js {12,14,18,20}
+// tailwind.config.cjs
+const starlightPlugin = require('@astrojs/starlight-tailwind');
+const colors = require('tailwindcss/colors');
+
+/** @type {import('tailwindcss').Config} */
+module.exports = {
+ content: ['./src/**/*.{astro,html,js,jsx,md,mdx,svelte,ts,tsx,vue}'],
+ theme: {
+ extend: {
+ colors: {
+ // Il tuo colore preferito. Indigo è il più vicino alle impostazioni predefinite di Starlight.
+ accent: colors.indigo,
+ // La tua scala di grigi preferita. Lo zinco è il più vicino ai valori predefiniti di Starlight.
+ gray: colors.zinc,
+ },
+ fontFamily: {
+ sans: ['"Atkinson Hyperlegible"'],
+ // Il tuo carattere di testo preferito. Starlight utilizza uno stack di caratteri di sistema per impostazione predefinita.
+ sans: ['"Atkinson Hyperlegible"'],
+ // Il tuo carattere di codice preferito. Starlight utilizza i caratteri di sistema a spaziatura fissa per impostazione predefinita.
+ mono: ['"IBM Plex Mono"'],
+ },
+ },
+ },
+ plugins: [starlightPlugin()],
+};
+```
+
+## Temi
+
+Il tema colore di Starlight può essere controllato sovrascrivendo le sue proprietà personalizzate predefinite.
+Queste variabili vengono utilizzate in tutta l'interfaccia utente con una gamma di sfumature di grigio utilizzate per i colori del testo e dello sfondo e un colore in risalto utilizzato per i collegamenti e per evidenziare gli elementi correnti nella navigazione.
+
+### Editor di temi colore
+
+Utilizza i dispositivi di scorrimento qui sotto per modificare l'accento di Starlight e le tavolozze dei colori grigi.
+Le aree di anteprima scure e chiare mostreranno i colori risultanti e anche l'intera pagina verrà aggiornata per visualizzare in anteprima le modifiche.
+
+Quando sei soddisfatto delle modifiche, copia il codice CSS o Tailwind di seguito e utilizzalo nel tuo progetto.
+
+import ThemeDesigner from '../../../../components/theme-designer.astro';
+
+
+
+ Aggiungi il seguente CSS al tuo progetto in un [file custom
+ CSS](#stili-css-personalizzati) per applicare questo tema al tuo sito.
+
+
+ L'esempio [file di configurazione di
+ Tailwind](#styling-di-starlight-con-tailwind) di seguito include tavolozze
+ di colori `accent` e `gray` generate da utilizzare in Oggetto di
+ configurazione `theme.extend.colors`.
+
+
diff --git a/docs/src/content/docs/it/guides/customization.mdx b/docs/src/content/docs/it/guides/customization.mdx
new file mode 100644
index 00000000000..236bda3062d
--- /dev/null
+++ b/docs/src/content/docs/it/guides/customization.mdx
@@ -0,0 +1,429 @@
+---
+title: Personalizzazione di Starlight
+description: Scopri come personalizzare il tuo sito Starlight con il tuo logo, caratteri personalizzati, design della pagina di destinazione e altro ancora.
+---
+
+import { Tabs, TabItem } from '@astrojs/starlight/components';
+import FileTree from '../../../../components/file-tree.astro';
+
+Starlight fornisce stili e funzionalità predefiniti sensati, così puoi iniziare rapidamente senza bisogno di configurazione.
+Se vuoi iniziare a personalizzare l'aspetto del tuo sito Starlight, questa guida fa al caso tuo.
+
+## Aggiungi il tuo logo
+
+L'aggiunta di un logo personalizzato all'intestazione del sito è un modo rapido per aggiungere il tuo marchio individuale a un sito Starlight.
+
+1. Aggiungi il file immagine del tuo logo alla directory `src/assets/`:
+
+
+
+ - src/
+ - assets/
+ - **my-logo.svg**
+ - content/
+ - astro.config.mjs
+
+
+
+2. Aggiungi il percorso del tuo logo come opzione [`logo.src`](/it/reference/configuration/#logo) di Starlight in `astro.config.mjs`:
+
+ ```js
+ // astro.config.mjs
+ import { defineConfig } from 'astro/config';
+ import starlight from '@astrojs/starlight';
+
+ export default defineConfig({
+ integrations: [
+ starlight({
+ title: 'Documentazione con il mio logo',
+ logo: {
+ src: './src/assets/my-logo.svg',
+ },
+ }),
+ ],
+ });
+ ```
+
+Per impostazione predefinita, il logo verrà visualizzato accanto al `title` del tuo sito.
+Se l'immagine del tuo logo include già il titolo del sito, puoi nascondere visivamente il testo del titolo impostando l'opzione `replacesTitle`.
+Il testo del `title` verrà comunque incluso per gli screen reader in modo che l'intestazione rimanga accessibile.
+
+```js
+starlight({
+ title: 'Documentazione con il mio logo',
+ logo: {
+ src: './src/assets/my-logo.svg',
+ replacesTitle: true,
+ },
+}),
+```
+
+### Varianti del logo chiaro e scuro
+
+Puoi visualizzare diverse versioni del tuo logo in modalità chiara e scura.
+
+1. Aggiungi un file immagine per ciascuna variante a `src/assets/`:
+
+
+
+ - src/
+ - assets/
+ - **light-logo.svg**
+ - **dark-logo.svg**
+ - content/
+ - astro.config.mjs
+
+
+
+2. Aggiungi il percorso alle varianti del tuo logo come opzioni `light` e `dark` invece di `src` in `astro.config.mjs`:
+
+ ```js
+ starlight({
+ title: 'Documentazione con il mio logo',
+ logo: {
+ light: './src/assets/light-logo.svg',
+ dark: './src/assets/dark-logo.svg',
+ },
+ }),
+ ```
+
+## Enable sitemap
+
+Starlight ha il supporto integrato per la generazione di una mappa del sito. Abilita la generazione della mappa del sito impostando il tuo URL come `site` in `astro.config.mjs`:
+
+```js
+// astro.config.mjs
+
+export default defineConfig({
+ site: 'https://stargazers.club/',
+ integrations: [starlight({ title: 'Sito con mappa del sito' })],
+});
+```
+
+## Layout della pagina
+
+Per impostazione predefinita, le pagine Starlight utilizzano un layout con una barra laterale di navigazione globale e un indice dei contenuti che mostra le intestazioni della pagina corrente.
+
+Puoi applicare un layout di pagina più ampio senza barre laterali impostando [`template: splash`](/it/reference/frontmatter/#template) nel frontmatter di una pagina.
+Funziona particolarmente bene per le pagine di destinazione e puoi vederlo in azione sulla [home page di questo sito](/it/).
+
+```md
+---
+# src/content/docs/index.md
+
+title: La mia pagina di destinazione
+template: splash
+---
+```
+
+## Indice dei contenuti
+
+Starlight visualizza un indice dei contenuti su ogni pagina per consentire ai lettori di passare più facilmente all'intestazione che stanno cercando.
+Puoi personalizzare, o addirittura disabilitare, l'indice dei contenuti a livello globale nell'integrazione Starlight o pagina per pagina in Frontmatter.
+
+Per impostazione predefinita, le intestazioni `` e `` sono incluse nell'indice dei contenuti. Modifica i livelli delle intestazioni da includere in tutto il sito utilizzando le opzioni `minHeadingLevel` e `maxHeadingLevel` nel tuo [global `tableOfContents`](/it/reference/configuration/#tableofcontents). Sostituisci queste impostazioni predefinite su una singola pagina aggiungendo le proprietà [frontmatter `tableOfContents`](/it/reference/frontmatter/#tableofcontents) corrispondenti:
+
+
+
+
+```md
+---
+# src/content/docs/example.md
+title: Pagina con solo H2 nell'indice dei contenuti
+summary:
+ minHeadingLevel: 2
+ maxHeadingLevel: 2
+---
+```
+
+
+
+
+```js
+// astro.config.mjs
+
+defineConfig({
+ integrations: [
+ starlight({
+ title: '',
+ tableOfContents: { minHeadingLevel: 2, maxHeadingLevel: 2 },
+ }),
+ ],
+});
+```
+
+
+
+
+Disabilita completamente l'indice dei contenuti impostando l'opzione `tableOfContents` su `false`:
+
+
+
+
+```md
+---
+# src/content/docs/esempio.md
+title: Pagina senza indice dei contenuti
+tableOfContents: false
+---
+```
+
+
+
+
+```js
+// astro.config.mjs
+
+defineConfig({
+ integrations: [
+ starlight({
+ title:
+ 'Documentazione con indice dei contenuti disabilitato a livello globale',
+ tableOfContents: false,
+ }),
+ ],
+});
+```
+
+
+
+
+## Collegamenti social
+
+Starlight dispone del supporto integrato per aggiungere collegamenti ai tuoi account di social media all'intestazione del sito tramite l'opzione [`social`](/it/reference/configuration/#social) nell'integrazione Starlight.
+
+Attualmente sono supportati i collegamenti a Bitbucket, Codeberg, CodePen, Discord, GitHub, GitLab, Gitter, Instagram, LinkedIn, Mastodon, Microsoft Teams, Stack Overflow, Threads, Twitch, Twitter e Youtube.
+Facci sapere su GitHub o Discord se hai bisogno di supporto per un altro servizio!
+
+```js
+// astro.config.mjs
+import { defineConfig } from 'astro/config';
+import starlight from '@astrojs/starlight';
+
+export default defineConfig({
+ integrations: [
+ starlight({
+ title: 'Documentazione con link social',
+ social: {
+ discord: 'https://astro.build/chat',
+ github: 'https://github.com/withastro/starlight',
+ },
+ }),
+ ],
+});
+```
+
+## Collegamenti di Modifica
+
+Starlight può visualizzare un collegamento "Modifica pagina" nel piè di pagina di ciascuna pagina.
+Ciò rende più semplice per il lettore trovare il file da modificare per migliorare i tuoi documenti.
+Per i progetti open source in particolare, questo può aiutare a incoraggiare i contributi della tua comunità.
+
+Per abilitare i collegamenti di modifica, imposta [`editLink.baseUrl`](/it/reference/configuration/#editlink) sull'URL utilizzato per modificare il tuo repository nella configurazione dell'integrazione Starlight.
+Il valore di `editLink.baseUrl` verrà anteposto al percorso della pagina corrente per formare il collegamento di modifica completo.
+
+I modelli comuni includono:
+
+- GitHub: `https://github.com/USER_NAME/REPO_NAME/edit/BRANCH_NAME/`
+- GitLab: `https://gitlab.com/USER_NAME/REPO_NAME/-/edit/BRANCH_NAME/`
+
+Se il tuo progetto Starlight non è nella radice del tuo repository, includi il percorso del progetto alla fine dell'URL di base.
+
+Questo esempio mostra il collegamento di modifica configurato per i documenti Starlight, che si trovano nella sottodirectory `docs/` sul ramo `main` del repository `withastro/starlight` su GitHub:
+
+```js
+// astro.config.mjs
+import { defineConfig } from 'astro/config';
+import starlight from '@astrojs/starlight';
+
+export default defineConfig({
+ integrations: [
+ starlight({
+ title: 'Documentazione con collegamenti di modifica',
+ editLink: {
+ baseUrl: 'https://github.com/withastro/starlight/edit/main/docs/',
+ },
+ }),
+ ],
+});
+```
+
+## Pagina 404 personalizzata
+
+Per impostazione predefinita, i siti Starlight visualizzano una semplice pagina 404.
+Puoi personalizzarlo aggiungendo un file `404.md` (o `404.mdx`) alla tua directory `src/content/docs/`:
+
+
+
+- src/
+ - content/
+ - docs/
+ - **404.md**
+ - index.md
+- astro.config.mjs
+
+
+
+Puoi utilizzare tutto il layout di pagina e le tecniche di personalizzazione di Starlight nella tua pagina 404. Ad esempio, la pagina 404 predefinita utilizza il componente [`splash` template](#page-layout) e [`hero`](/it/reference/frontmatter/#hero) in frontmatter:
+
+```md
+---
+title: '404'
+template: splash
+editUrl: false
+hero:
+ title: '404'
+ tagline: Pagina non trovata. Controlla l'URL o prova a utilizzare la barra di ricerca.
+---
+```
+
+## Caratteri personalizzati
+
+Per impostazione predefinita, Starlight utilizza i caratteri sans-serif disponibili sul dispositivo locale dell'utente per tutto il testo.
+Ciò garantisce che la documentazione venga caricata rapidamente in un carattere familiare a ciascun utente, senza richiedere larghezza di banda aggiuntiva per scaricare file di caratteri di grandi dimensioni.
+
+Se devi aggiungere un carattere personalizzato al tuo sito Starlight, puoi impostare i caratteri da utilizzare nei file CSS personalizzati o con qualsiasi altra [tecnica di stile Astro](https://docs.astro.build/it/guides/styling/) .
+
+### Imposta i caratteri
+
+Se disponi già di file di font, segui la [guida alla configurazione locale](#configura-i-file-dei-caratteri-locali).
+Per utilizzare Google Fonts, segui la [guida alla configurazione di Fontsource](#configura-un-font-fontsource).
+
+#### Configura i file dei caratteri locali
+
+1. Aggiungi i file dei caratteri a una directory `src/fonts/` e crea un file `font-face.css` vuoto:
+
+
+
+ - src/
+ - content/
+ - fonts/
+ - **CustomFont.woff2**
+ - **font-face.css**
+ - astro.config.mjs
+
+
+
+2. Aggiungi una [dichiarazione `@font-face`](https://developer.mozilla.org/en-US/docs/Web/CSS/@font-face) per ciascuno dei tuoi caratteri in `src/fonts/font-face.css`.
+ Utilizza un percorso relativo al file del font nella funzione `url()`.
+
+ ```css
+ /* src/fonts/font-face.css */
+
+ @font-face {
+ font-family: 'Font Personalizzato';
+ /* Utilizza un percorso relativo al file del font locale in `url()`. */
+ src: url('./CustomFont.woff2') format('woff2');
+ font-weight: normal;
+ font-style: normal;
+ font-display: swap;
+ }
+ ```
+
+3. Aggiungi il percorso del tuo file `font-face.css` all'array `customCss` di Starlight in `astro.config.mjs`:
+
+ ```js
+ // astro.config.mjs
+ import { defineConfig } from 'astro/config';
+ import starlight from '@astrojs/starlight';
+
+ export default defineConfig({
+ integrations: [
+ starlight({
+ title: 'Documentazione con font personalizzato',
+ customCss: [
+ // Percorso relativo al file CSS @font-face.
+ './src/fonts/font-face.css',
+ ],
+ }),
+ ],
+ });
+ ```
+
+#### Configura un font Fontsource
+
+Il progetto [Fontsource](https://fontsource.org/) semplifica l'utilizzo di Google Fonts e altri caratteri open source.
+Fornisce moduli npm che puoi installare per i caratteri che desideri utilizzare e include file CSS già pronti da aggiungere al tuo progetto.
+
+1. Trova il font che desideri utilizzare nel [catalogo di Fontsource](https://fontsource.org/).
+ Questo esempio utilizzerà [IBM Plex Serif](https://fontsource.org/fonts/ibm-plex-serif).
+
+2. Installa il pacchetto per il font scelto.
+ Puoi trovare il nome del pacchetto facendo clic su "Installa" nella pagina dei caratteri Fontsource.
+
+
+
+
+
+ ```sh
+ npm install @fontsource/ibm-plex-serif
+ ```
+
+
+
+
+
+ ```sh
+ pnpm install @fontsource/ibm-plex-serif
+ ```
+
+
+
+
+
+ ```sh
+ yarn add @fontsource/ibm-plex-serif
+ ```
+
+
+
+
+
+3. Aggiungi i file CSS Fontsource all'array `customCss` di Starlight in `astro.config.mjs`:
+
+ ```js
+ // astro.config.mjs
+ import { defineConfig } from 'astro/config';
+ import starlight from '@astrojs/starlight';
+
+ export default defineConfig({
+ integrations: [
+ starlight({
+ title: 'Docs With a Custom Typeface',
+ customCss: [
+ // File Fontsource per pesi di font regolari e semi-grassetto.
+ '@fontsource/ibm-plex-serif/400.css',
+ '@fontsource/ibm-plex-serif/600.css',
+ ],
+ }),
+ ],
+ });
+ ```
+
+ Fontsource fornisce più file CSS per ciascun font. Consulta la [documentazione Fontsource](https://fontsource.org/docs/getting-started/install#4-weights-and-styles) sull'inclusione di pesi e stili diversi per capire quale utilizzare.
+
+### Usa i caratteri
+
+Per applicare il font che hai impostato al tuo sito, utilizza il nome del font scelto in un [file CSS personalizzato](/it/guides/css-and-tailwind/#custom-css-styles).
+Ad esempio, per sovrascrivere ovunque il font predefinito di Starlight, imposta la proprietà personalizzata `--sl-font`:
+
+```css
+/* src/styles/custom.css */
+
+:root {
+ --sl-font: 'IBM Plex Serif', serif;
+}
+```
+
+Puoi anche scrivere CSS più mirati se desideri applicare il tuo font in modo più selettivo.
+Ad esempio, per impostare un font solo sul contenuto principale, ma non sulle barre laterali:
+
+```css
+/* src/styles/custom.css */
+
+main {
+ font-family: 'IBM Plex Serif', serif;
+}
+```
+
+Segui le [istruzioni CSS personalizzate](/it/guides/css-and-tailwind/#custom-css-styles) per aggiungere i tuoi stili al tuo sito.
diff --git a/docs/src/content/docs/it/guides/i18n.mdx b/docs/src/content/docs/it/guides/i18n.mdx
index 9a06c0efc91..8965b396272 100644
--- a/docs/src/content/docs/it/guides/i18n.mdx
+++ b/docs/src/content/docs/it/guides/i18n.mdx
@@ -143,7 +143,7 @@ Se una traduzione non è ancora disponibile per una lingua, Starlight mostrerà
In aggiunta alla possibilità di avere pagine multilingua, Starlight permette di tradurre le scritte dell'interfaccia (per esempio l'intestazione "In questa pagina" nella tabella dei contenuti) in modo che i lettori possano vedere il sito interamente nella lingua selezionata.
-Inglese, francese, tedesco, giapponese, portoghese, spagnolo e italiano sono disponibili di default, e sono benvenute [contribuzioni per aggiungere altre lingue](https://github.com/withastro/starlight/blob/main/CONTRIBUTING.md).
+Le stringhe dell'interfaccia utente tradotte in inglese, ceco, francese, tedesco, italiano, giapponese, portoghese, olandese, danese, spagnolo, turco, arabo, norvegese, farsi, cinese semplificato, coreano, russo e svedese sono disponibili di default e accettiamo [contributi per aggiungere altre lingue predefinite](https://github.com/withastro/starlight/blob/main/CONTRIBUTING.md).
Puoi fornire traduzioni per lingue aggiuntive — o sovrascrivere i valori predefiniti — con la collezione `i18n`.
diff --git a/docs/src/content/docs/it/guides/sidebar.mdx b/docs/src/content/docs/it/guides/sidebar.mdx
new file mode 100644
index 00000000000..b5d6570d9c2
--- /dev/null
+++ b/docs/src/content/docs/it/guides/sidebar.mdx
@@ -0,0 +1,480 @@
+---
+title: Navigazione nella barra laterale
+description: Scopri come impostare e personalizzare i collegamenti di navigazione della barra laterale del tuo sito Starlight.
+sidebar:
+ badge: Nuovo
+---
+
+import FileTree from '../../../../components/file-tree.astro';
+import SidebarPreview from '../../../../components/sidebar-preview.astro';
+
+Una barra laterale ben organizzata è fondamentale per una buona documentazione poiché è uno dei modi principali in cui gli utenti navigheranno nel tuo sito. Starlight fornisce un set completo di opzioni per personalizzare il layout e il contenuto della barra laterale.
+
+## Barra laterale predefinita
+
+Per impostazione predefinita, Starlight genererà automaticamente una barra laterale in base alla struttura del file system della documentazione, utilizzando la proprietà `title` di ciascun file come voce della barra laterale.
+
+Ad esempio, data la seguente struttura di file:
+
+
+
+- src/
+ - content/
+ - docs/
+ - guides/
+ - components.md
+ - i18n.md
+ - reference/
+ - configuration.md
+
+
+
+Verrà generata automaticamente la seguente barra laterale:
+
+
+
+- src/
+ - content/
+ - docs/
+ - guides/
+ - components.md
+ - i18n.md
+ - advanced/
+ - project-structure.md
+
+
+
+Verrà generata la seguente barra laterale:
+
+
+
+ ```sh
+ npx astro add starlight
+ ```
+
+
+
+ ```sh
+ pnpm astro add starlight
+ ```
+
+
+ ```sh
+ yarn astro add starlight
+ ```
+
+
+
+
+Questo installerà le dipendenze richieste e aggiungerà Starlight all'array `integrations` nel tuo file di configurazione Astro.
+
+### Configura l'integrazione
+
+L'integrazione Starlight è configurata nel file `astro.config.mjs`.
+
+Aggiungi un `title` per iniziare:
+
+```js {7-9}
+// astro.config.mjs
+import { defineConfig } from 'astro/config';
+import starlight from '@astrojs/starlight';
+
+export default defineConfig({
+ integrations: [
+ starlight({
+ title: 'Il mio meraviglioso sito di documentazione',
+ }),
+ ],
+});
+```
+
+Trova tutte le opzioni disponibili nel [riferimento per la configurazione di Starlight](/it/reference/configuration/).
+
+### Configura raccolte di contenuti
+
+Starlight si basa sulle [raccolte di contenuti](https://docs.astro.build/it/guides/content-collections/) di Astro, che sono configurate nel file `src/content/config.ts`.
+
+Crea o aggiorna il file di configurazione del contenuto, aggiungendo una raccolta `docs` che utilizza `docsSchema` di Starlight:
+
+```js ins={3,6}
+// src/content/config.ts
+import { defineCollection } from 'astro:content';
+import { docsSchema } from '@astrojs/starlight/schema';
+
+export const collections = {
+ docs: defineCollection({ schema: docsSchema() }),
+};
+```
+
+### Aggiungi contenuto
+
+Starlight è ora configurato ed è ora di aggiungere alcuni contenuti!
+
+Crea una directory `src/content/docs/` e inizia aggiungendo un file `index.md`.
+Questa sarà la home page del tuo nuovo sito:
+
+```md
+---
+# src/content/docs/index.md
+title: I miei documenti
+description: Scopri di più sul mio progetto in questo sito di documenti creato con Starlight.
+---
+
+Benvenuti nel mio progetto!
+```
+
+Starlight utilizza il routing basato su file, il che significa che ogni file Markdown, MDX o Markdoc in `src/content/docs/` verrà trasformato in una pagina sul tuo sito. I metadati di Frontmatter (i campi `title` e `description` nell'esempio sopra) possono modificare il modo in cui viene visualizzata ciascuna pagina.
+Vedi tutte le opzioni disponibili nel [riferimento frontmatter](/it/reference/frontmatter/).
+
+## Suggerimenti per i siti esistenti
+
+Se hai un progetto Astro esistente, puoi utilizzare Starlight per aggiungere rapidamente una sezione di documentazione al tuo sito.
+
+### Usa Starlight in un sottopercorso
+
+Per aggiungere tutte le pagine Starlight in un sottopercorso, posiziona tutto il contenuto dei tuoi documenti in una sottodirectory di `src/content/docs/`.
+
+Ad esempio, se le pagine Starlight dovessero iniziare tutte con `/guides/`, aggiungi il contenuto nella directory `src/content/docs/guides/`:
+
+import FileTree from '../../../components/file-tree.astro';
+
+
+
+- src/
+ - content/
+ - docs/
+ - **guides/**
+ - guide.md
+ - index.md
+ - pages/
+- astro.config.mjs
+
+
+
+In futuro, prevediamo di supportare meglio questo caso d'uso per evitare la necessità di una directory all'interno di una directory aggiuntiva in `src/content/docs/`.
+
+### Usa Starlight con SSR
+
+Attualmente, Starlight non supporta [distribuzione SSR](https://docs.astro.build/it/guides/server-side-rendering/) utilizzando gli adattatori server di Astro. Speriamo di poterlo supportare presto.
diff --git a/docs/src/content/docs/it/reference/configuration.md b/docs/src/content/docs/it/reference/configuration.md
index 1fadaf13974..950e7cf0106 100644
--- a/docs/src/content/docs/it/reference/configuration.md
+++ b/docs/src/content/docs/it/reference/configuration.md
@@ -44,7 +44,7 @@ Definisce il logo da rappresentare nella barra di navigazione con o al posto del
```js
starlight({
logo: {
- src: '/src/assets/my-logo.svg',
+ src: './src/assets/my-logo.svg',
},
});
```
@@ -87,13 +87,20 @@ Con questa configurazione, una pagina `/introduction` avrà un link di modifica
Configura la barra laterale di navigazione del tuo sito.
-Una barra laterale è un array di gruppi, ognuno avente un `label` e o un array `items` o un oggetto `autogenerate`.
+Una barra laterale è un array di collegamenti e gruppi di collegamenti.
+Ogni elemento avente un `label` e una delle seguenti proprietà:
-Puoi manualmente impostare i contenuti di un gruppo con `items`, che è un array che può includere link e sottogruppi. Puoi anche automaticamente generare i contenuti di un gruppo da una specifica cartella della documentazione utilizzando `autogenerate`.
+- `link` — un singolo colelgamento a uno specifico URL, ad es. `'/home'` o `'https://example.com'`.
+
+- `items` — an aray contenente più collegamenti della barra laterale e sottogruppi.
+
+- `autogenerate` — un oggetto indicante una cartella dei tuoi documenti di cui generare automaticamente i collegamenti.
```js
starlight({
sidebar: [
+ // Un singolo elemento chiamato “Home”.
+ { label: 'Home', link: '/' },
// Un gruppo intitolato "Inizia qui" contenente due link.
{
label: 'Inizia qui',
@@ -116,6 +123,34 @@ starlight({
I gruppi generati automaticamente sono ordinati alfabeticamente.
Per esempio, una pagina generata da `astro.md` apparirà sopra a quella generata da `starlight.md`.
+#### Gruppi comprimibili
+
+I gruppi di collegamenti vengono espansi per impostazione predefinita. Puoi modificare questo comportamento impostando la proprietà `collapsed` di un gruppo su `true`.
+
+I sottogruppi generati automaticamente rispettano la proprietà `collapsed` del gruppo principale per impostazione predefinita. Imposta la proprietà `autogenerate.collapsed` per sovrascriverla.
+
+```js
+sidebar: [
+ // Un gruppo di collegamenti compresso.
+ {
+ label: 'Collegamenti compressi',
+ collapsed: true,
+ items: [
+ { label: 'Introduzione', link: '/intro' },
+ { label: 'Prossimi passi', link: '/next-steps' },
+ ],
+ },
+ // An expanded group containing collapsed autogenerated subgroups.
+ {
+ label: 'Riferimenti',
+ autogenerate: {
+ directory: 'reference',
+ collapsed: true,
+ },
+ },
+],
+```
+
#### Tradurre i titoli
Se il tuo sito è multilingua, ogni elemento di `label` è considerato come appartenente alla lingua di default. Puoi definire `translations` per fornire i titoli per le altre lingue:
@@ -139,33 +174,34 @@ sidebar: [
},
],
},
-];
+],
```
-#### `SidebarGroup`
+#### `SidebarItem`
```ts
-type SidebarGroup =
+type SidebarItem = {
+ label: string;
+ translations?: Record;
+} & (
| {
- label: string;
- translations?: Record;
- items: Array;
+ link: string;
+ badge?: string | BadgeConfig;
}
+ | { items: SidebarItem[]; collapsed?: boolean }
| {
- label: string;
- translations?: Record;
- autogenerate: {
- directory: string;
- };
- };
+ autogenerate: { directory: string; collapsed?: boolean };
+ collapsed?: boolean;
+ }
+);
```
-#### `LinkItem`
+#### `BadgeConfig`
```ts
-interface LinkItem {
- label: string;
- link: string;
+interface BadgeConfig {
+ text: string;
+ variant: 'note' | 'tip' | 'caution' | 'danger' | 'success' | 'default';
}
```
@@ -271,17 +307,23 @@ Verrà utilizzato come fallback per le pagine non tradotte.
### `social`
-**type:** `{ discord?: string; github?: string; mastodon?: string; twitter?: string }`
+**type:** `Partial>`
Dettagli opzionali per gli account social del sito. Se vengono aggiunti apparirà l'icona corrispondente nella barra superiore.
```js
starlight({
social: {
+ codeberg: 'https://codeberg.org/knut/examples',
discord: 'https://astro.build/chat',
github: 'https://github.com/withastro/starlight',
+ gitlab: 'https://gitlab.com/delucis',
+ linkedin: 'https://www.linkedin.com/company/astroinc',
mastodon: 'https://m.webtoo.ls/@astro',
+ threads: 'https://www.threads.net/@nmoodev',
+ twitch: 'https://www.twitch.tv/bholmesdev',
twitter: 'https://twitter.com/astrodotbuild',
+ youtube: 'https://youtube.com/@astrodotbuild',
},
});
```
@@ -332,3 +374,53 @@ interface HeadConfig {
content?: string;
}
```
+
+### `lastUpdated`
+
+**type:** `boolean`
+**default:** `false`
+
+Controlla se il piè di pagina mostra quando è stata aggiornata l'ultima volta la pagina.
+
+Per impostazione predefinita, questa funzionalità si basa sulla cronologia Git del repository e potrebbe non essere accurata su alcune piattaforme di distribuzione che eseguono [cloni superficiali](https://git-scm.com/docs/git-clone#Documentation/git-clone.txt---depthltdepthgt). Una pagina può sovrascrivere questa impostazione o la data basata su Git utilizzando il [campo frontmatter `lastUpdated`](/it/reference/frontmatter/#lastupdated).
+
+### `pagination`
+
+**type:** `boolean`
+**default:** `true`
+
+Definisci se il piè di pagina deve includere i collegamenti alla pagina precedente e successiva.
+
+Una pagina può sovrascrivere questa impostazione o il testo del collegamento e/o l'URL utilizzando i campi frontmatter [`prev`](/it/reference/frontmatter/#prev) e [`next`](/it/reference/frontmatter/#next).
+
+### `favicon`
+
+**type:** `string`
+**default:** `'/favicon.svg'`
+
+Imposta il percorso della favicon predefinita per il tuo sito web che dovrebbe trovarsi nella directory `public/` ed essere valido (`.ico`, `.gif`, `.jpg`, `.png` o `.svg`) file di icone.
+
+```js
+starlight({
+ favicon: '/images/favicon.svg',
+}),
+```
+
+Se devi impostare varianti aggiuntive o favicon di fallback, puoi aggiungere tag utilizzando l'[opzione`head`](#head):
+
+```js
+starlight({
+ favicon: '/images/favicon.svg'.
+ head: [
+ // Aggiungi il fallback della favicon ICO per Safari.
+ {
+ tag: 'link',
+ attrs: {
+ rel: 'icon',
+ href:'/images/favicon.ico',
+ sizes: '32x32',
+ },
+ },
+ ],
+});
+```
diff --git a/docs/src/content/docs/it/reference/frontmatter.md b/docs/src/content/docs/it/reference/frontmatter.md
index 681b8d78145..3a76d172498 100644
--- a/docs/src/content/docs/it/reference/frontmatter.md
+++ b/docs/src/content/docs/it/reference/frontmatter.md
@@ -57,6 +57,22 @@ head:
Sovrascrive la [configurazione globale `tableOfContents`](/it/reference/configuration/#tableofcontents).
Cambia i livelli di titoli inclusi o, se messo a `false`, nasconde la tabella dei contenuti della pagina.
+```md
+---
+title: Pagina con solo H2 nella tabella dei contenuti della pagina
+tableOfContents:
+ minHeadingLevel: 2
+ maxHeadingLevel: 2
+---
+```
+
+```md
+---
+title: Pagina senza tabella dei contenuti della pagina
+tableOfContents: false
+---
+```
+
### `template`
**type:** `'doc' | 'splash'`
@@ -117,3 +133,169 @@ interface HeroConfig {
}>;
}
```
+
+### `banner`
+
+**type:** `{ content: string }`
+
+Visualizza un banner di annuncio nella parte superiore di questa pagina.
+
+Il valore `content` può includere HTML per collegamenti o altri contenuti.
+Ad esempio, questa pagina visualizza un banner che include un collegamento a `example.com`.
+
+```md
+---
+title: Pagina con un banner
+banner:
+ content: |
+ Abbiamo appena lanciato qualcosa di interessante!
+ Dai un'occhiata
+---
+```
+
+### `lastUpdated`
+
+**type:** `Date | boolean`
+
+Sostituisce l'[opzione globale `lastUpdated`](/it/reference/configuration/#lastupdated). Se viene specificata una data, deve essere un [timestamp YAML](https://yaml.org/type/timestamp.html) valido e sovrascriverà la data archiviata nella cronologia Git per questa pagina.
+
+```md
+---
+title: Pagina con una data di ultimo aggiornamento personalizzata
+lastUpdated: 2022-08-09
+---
+```
+
+### `prev`
+
+**type:** `boolean | string | { link?: string; label?: string }`
+
+Sostituisce l'[opzione globale `paginazione`](/it/reference/configuration/#pagination). Se viene specificata una stringa, il testo del collegamento generato verrà sostituito e se viene specificato un oggetto, sia il collegamento che il testo verranno sovrascritti.
+
+```md
+---
+# Nascondi il collegamento alla pagina precedente
+prev: false
+---
+```
+
+```md
+---
+# Sostituisci il testo del collegamento della pagina precedente
+prev: Continua il tutorial
+---
+```
+
+```md
+---
+# Sostituisci sia il collegamento che il testo della pagina precedente
+prev:
+ link: /pagina-non-correlata/
+ label: Dai un'occhiata a quest'altra pagina
+---
+```
+
+### `next`
+
+**type:** `boolean | string | { link?: string; label?: string }`
+
+Uguale a [`prev`](#prev) ma per il collegamento alla pagina successiva.
+
+```md
+---
+# Nascondi il collegamento alla pagina successiva
+next: false
+---
+```
+
+### `pagefind`
+
+**type:** `boolean`
+**default:** `true`
+
+Imposta se questa pagina deve essere inclusa nell'indice di ricerca [Pagefind](https://pagefind.app/). Imposta su `false` per escludere una pagina dai risultati di ricerca:
+
+```md
+---
+# Nascondi questa pagina dai risultati di ricerca
+pagefind: false
+---
+```
+
+### `sidebar`
+
+**type:** `{ label?: string; order?: number; hidden?: boolean; badge?: string | BadgeConfig }`
+
+Controlla il modo in cui questa pagina viene visualizzata nella [barra laterale](/it/reference/configuration/#sidebar), quando si utilizza un gruppo di collegamenti generato automaticamente.
+
+#### `label`
+
+**type:** `string`
+**default:** the page [`title`](#title-required)
+
+Imposta l'etichetta per questa pagina nella barra laterale quando viene visualizzata in un gruppo di collegamenti generato automaticamente.
+
+```md
+---
+title: Informazioni su questo progetto
+sidebar:
+ label: Informazioni
+---
+```
+
+#### `order`
+
+**type:** `number`
+
+Controlla l'ordine di questa pagina quando ordini un gruppo di collegamenti generato automaticamente.
+I numeri più bassi vengono visualizzati più in alto nel gruppo di collegamenti.
+
+```md
+---
+title: Pagina da visualizzare per prima
+sidebar:
+ order: 1
+---
+```
+
+#### `hidden`
+
+**type:** `boolean`
+**default:** `false`
+
+Impedisce che questa pagina venga inclusa in un gruppo della barra laterale generato automaticamente.
+
+```md
+---
+title: Pagina da nascondere dalla barra laterale generata automaticamente
+sidebar:
+ hidden: vero
+---
+```
+
+#### `badge`
+
+**type:** string | BadgeConfig
+
+Aggiungi un badge alla pagina nella barra laterale quando viene visualizzata in un gruppo di collegamenti generato automaticamente.
+Quando si utilizza una stringa, il badge verrà visualizzato con un colore in risalto predefinito.
+Facoltativamente, passa un [oggetto `BadgeConfig`](/it/reference/configuration/#badgeconfig) con i campi `text` e `variant` per personalizzare il badge.
+
+```md
+---
+title: Pagina con un badge
+sidebar:
+ # Utilizza la variante predefinita corrispondente al colore principale del tuo sito
+ badge: nuovo
+---
+```
+
+```md
+---
+title: Pagina con un badge
+sidebar:
+ badge:
+ text: Sperimentale
+ variant: caution
+---
+```
diff --git a/docs/src/content/docs/it/showcase.mdx b/docs/src/content/docs/it/showcase.mdx
new file mode 100644
index 00000000000..a3351f3f87c
--- /dev/null
+++ b/docs/src/content/docs/it/showcase.mdx
@@ -0,0 +1,53 @@
+---
+title: Vetrina Starlight
+description: Scopri i siti realizzati con Starlight e gli strumenti della community che estendono Starlight!
+---
+
+:::tip[Aggiungi il tuo!]
+Hai creato un sito Starlight o uno strumento per Starlight?
+Apri una PR aggiungendo un link a questa pagina!
+:::
+
+## Sites
+
+import ShowcaseSites from '../../../components/showcase-sites.astro';
+
+Starlight è già utilizzato nella produzione. Questi sono alcuni dei siti presenti sul web:
+
+
+
diff --git a/docs/src/content/docs/ja/guides/customization.mdx b/docs/src/content/docs/ja/guides/customization.mdx
index 5e113bf9f5c..fafe669206a 100644
--- a/docs/src/content/docs/ja/guides/customization.mdx
+++ b/docs/src/content/docs/ja/guides/customization.mdx
@@ -84,6 +84,19 @@ starlight({
}),
```
+## サイトマップを有効化する
+
+Starlightにはサイトマップ生成機能が組み込まれています。`astro.config.mjs`の`site`にURLを設定すると、サイトマップの生成が有効になります。
+
+```js
+// astro.config.mjs
+
+export default defineConfig({
+ site: 'https://stargazers.club',
+ integrations: [starlight({ title: 'サイトマップを設定したサイト' })],
+});
+```
+
## ページレイアウト
Starlightのページはデフォルトで、グローバルなナビゲーションサイドバーと、現在のページの見出しを表示する目次を配置したレイアウトを使用します。
diff --git a/docs/src/content/docs/ja/guides/i18n.mdx b/docs/src/content/docs/ja/guides/i18n.mdx
index 66d57cb9cc9..a7571086e52 100644
--- a/docs/src/content/docs/ja/guides/i18n.mdx
+++ b/docs/src/content/docs/ja/guides/i18n.mdx
@@ -141,7 +141,7 @@ Starlightは、すべての言語で同等のページが作成されること
Starlightでは、読者が選択した言語でサイト全体を体験できるように、翻訳されたコンテンツファイルをホストするだけでなく、デフォルトUIの文字列（たとえば目次に表示されている「目次」という見出し）も翻訳できるようになっています。
-英語、チェコ語、フランス語、ドイツ語、イタリア語、日本語、ポルトガル語、オランダ語、デンマーク語、スペイン語、トルコ語、アラビア語、ノルウェー語、ペルシア語、簡体字中国語、韓国語、スウェーデン語の翻訳済みUI文字列がすでに用意されていますが、[デフォルト言語をさらに追加するための貢献](https://github.com/withastro/starlight/blob/main/CONTRIBUTING.md)も歓迎します。
+英語、チェコ語、フランス語、ドイツ語、イタリア語、日本語、ポルトガル語、オランダ語、デンマーク語、スペイン語、トルコ語、アラビア語、ノルウェー語、ペルシア語、簡体字中国語、韓国語、ロシア語、スウェーデン語の翻訳済みUI文字列がすでに用意されていますが、[デフォルト言語をさらに追加するための貢献](https://github.com/withastro/starlight/blob/main/CONTRIBUTING.md)も歓迎します。
`18n`データコレクションを使用すると、サポートしたい言語の翻訳を追加したり、デフォルトのラベルを上書きしたりできます。
diff --git a/docs/src/content/docs/ja/reference/frontmatter.md b/docs/src/content/docs/ja/reference/frontmatter.md
index 56367ea651d..eb1aa6356a4 100644
--- a/docs/src/content/docs/ja/reference/frontmatter.md
+++ b/docs/src/content/docs/ja/reference/frontmatter.md
@@ -204,6 +204,20 @@ next: false
---
```
+### `pagefind`
+
+**type:** `boolean`
+**default:** `true`
+
+ページを[Pagefind](https://pagefind.app/)の検索インデックスに含めるかどうかを設定します。ページを検索結果から除外するには、`false`に設定します。
+
+```md
+---
+# このページを検索インデックスから外す
+pagefind: false
+---
+```
+
### `sidebar`
**type:** `{ label?: string; order?: number; hidden?: boolean; badge?: string | BadgeConfig }`
diff --git a/docs/src/content/docs/ja/showcase.mdx b/docs/src/content/docs/ja/showcase.mdx
index 18d24333ff6..68e1189b794 100644
--- a/docs/src/content/docs/ja/showcase.mdx
+++ b/docs/src/content/docs/ja/showcase.mdx
@@ -9,84 +9,11 @@ StarlightサイトやStarlightのツールを作成しましたか？このペ
## サイト
-import Card from '../../../components/showcase-card.astro';
-import FluidGrid from '../../../components/fluid-grid.astro';
+import ShowcaseSites from '../../../components/showcase-sites.astro';
Starlightはすでに本番環境で使用されています。以下はウェブ上のサイトの一部です。
-
-
+
+
+- src/
+ - content/
+ - docs/
+ - guides/
+ - components.md
+ - i18n.md
+ - reference/
+ - configuration.md
+
+
+
+다음 사이드바가 자동으로 생성됩니다.
+
+
+
+- src/
+ - content/
+ - docs/
+ - guides/
+ - components.md
+ - i18n.md
+ - advanced/
+ - project-structure.md
+
+
+
+다음 사이드바가 생성됩니다:
+
+
-
+
-
+
-
+
+
+- src/
+ - content/
+ - docs/
+ - guides/
+ - components.md
+ - i18n.md
+ - reference/
+ - configuration.md
+
+
+
+将会自动生成以下侧边栏：
+
+
+
+- src/
+ - content/
+ - docs/
+ - guides/
+ - components.md
+ - i18n.md
+ - advanced/
+ - project-structure.md
+
+
+
+将会自动生成以下侧边栏：
+
+
-
+` across lines to avoid overflow
+
+- [#642](https://github.com/withastro/starlight/pull/642) [`e623d92`](https://github.com/withastro/starlight/commit/e623d92c2fddc0ff5fe83d2554266885d683a906) Thanks [@fk](https://github.com/fk)! - Don't hard-code nav height in table of contents highlighting script
+
+- [#676](https://github.com/withastro/starlight/pull/676) [`6419006`](https://github.com/withastro/starlight/commit/641900615aa9a9a128d6934e65a57ba89e503cfd) Thanks [@vedmalex](https://github.com/vedmalex)! - Upgrade and pin Pagefind to latest beta release.
+
+- [#647](https://github.com/withastro/starlight/pull/647) [`ea57726`](https://github.com/withastro/starlight/commit/ea5772655274a3900310cb700836fdd2f6dba7cd) Thanks [@bgmort](https://github.com/bgmort)! - Add frontmatter option to exclude a page from Pagefind search results
+
## 0.9.0
### Minor Changes
diff --git a/packages/starlight/__tests__/basics/toc.test.ts b/packages/starlight/__tests__/basics/toc.test.ts
new file mode 100644
index 00000000000..51745d7b81c
--- /dev/null
+++ b/packages/starlight/__tests__/basics/toc.test.ts
@@ -0,0 +1,141 @@
+import { expect, test } from 'vitest';
+import { generateToC } from '../../components/TableOfContents/generateToC';
+
+const defaultOpts = { minHeadingLevel: 2, maxHeadingLevel: 3, title: 'Overview' };
+
+test('generates an overview entry with no headings available', () => {
+ const toc = generateToC([], defaultOpts);
+ expect(toc).toHaveLength(1);
+ expect(toc[0]).toEqual({ children: [], depth: 2, slug: '_top', text: 'Overview' });
+});
+
+test('generates entries from heading array', () => {
+ const toc = generateToC([{ text: 'One', slug: 'one', depth: 2 }], defaultOpts);
+ expect(toc).toHaveLength(2);
+ expect(toc[0]).toEqual({ children: [], depth: 2, slug: '_top', text: 'Overview' });
+ expect(toc[1]).toEqual({ children: [], depth: 2, slug: 'one', text: 'One' });
+});
+
+test('nests lower-level headings in children array h2 => h3', () => {
+ const toc = generateToC(
+ [
+ { text: 'One', slug: 'one', depth: 2 },
+ { text: 'Two', slug: 'two', depth: 3 },
+ ],
+ defaultOpts
+ );
+ expect(toc).toHaveLength(2);
+ expect(toc[0]).toEqual({ children: [], depth: 2, slug: '_top', text: 'Overview' });
+ expect(toc[1]).toEqual({
+ children: [{ children: [], depth: 3, slug: 'two', text: 'Two' }],
+ depth: 2,
+ slug: 'one',
+ text: 'One',
+ });
+});
+
+test('nests lower-level headings in children array h2 => h4', () => {
+ const toc = generateToC(
+ [
+ { text: 'One', slug: 'one', depth: 2 },
+ { text: 'Two', slug: 'two', depth: 4 },
+ ],
+ { ...defaultOpts, maxHeadingLevel: 6 }
+ );
+ expect(toc).toHaveLength(2);
+ expect(toc[0]).toEqual({ children: [], depth: 2, slug: '_top', text: 'Overview' });
+ expect(toc[1]).toEqual({
+ children: [{ children: [], depth: 4, slug: 'two', text: 'Two' }],
+ depth: 2,
+ slug: 'one',
+ text: 'One',
+ });
+});
+
+test('nests lower-level headings deeply h2 => h4 => h6', () => {
+ const toc = generateToC(
+ [
+ { text: 'One', slug: 'one', depth: 2 },
+ { text: 'Two', slug: 'two', depth: 4 },
+ { text: 'Three', slug: 'three', depth: 6 },
+ ],
+ { ...defaultOpts, maxHeadingLevel: 6 }
+ );
+ expect(toc).toHaveLength(2);
+ expect(toc[0]).toEqual({ children: [], depth: 2, slug: '_top', text: 'Overview' });
+ expect(toc[1]).toMatchInlineSnapshot(`
+ {
+ "children": [
+ {
+ "children": [
+ {
+ "children": [],
+ "depth": 6,
+ "slug": "three",
+ "text": "Three",
+ },
+ ],
+ "depth": 4,
+ "slug": "two",
+ "text": "Two",
+ },
+ ],
+ "depth": 2,
+ "slug": "one",
+ "text": "One",
+ }
+ `);
+});
+
+test('adds higher-level headings sequentially h6 => h4 => h2', () => {
+ const toc = generateToC(
+ [
+ { text: 'One', slug: 'one', depth: 6 },
+ { text: 'Two', slug: 'two', depth: 4 },
+ { text: 'Three', slug: 'three', depth: 2 },
+ ],
+ { ...defaultOpts, maxHeadingLevel: 6 }
+ );
+ expect(toc).toHaveLength(2);
+ expect(toc).toMatchInlineSnapshot(`
+ [
+ {
+ "children": [
+ {
+ "children": [],
+ "depth": 6,
+ "slug": "one",
+ "text": "One",
+ },
+ {
+ "children": [],
+ "depth": 4,
+ "slug": "two",
+ "text": "Two",
+ },
+ ],
+ "depth": 2,
+ "slug": "_top",
+ "text": "Overview",
+ },
+ {
+ "children": [],
+ "depth": 2,
+ "slug": "three",
+ "text": "Three",
+ },
+ ]
+ `);
+});
+
+test('filters out higher-level headings than minHeadingLevel', () => {
+ const toc = generateToC([{ text: 'One', slug: 'one', depth: 1 }], defaultOpts);
+ expect(toc).toHaveLength(1);
+ expect(toc[0]).toEqual({ children: [], depth: 2, slug: '_top', text: 'Overview' });
+});
+
+test('filters out lower-level headings than maxHeadingLevel', () => {
+ const toc = generateToC([{ text: 'One', slug: 'one', depth: 4 }], defaultOpts);
+ expect(toc).toHaveLength(1);
+ expect(toc[0]).toEqual({ children: [], depth: 2, slug: '_top', text: 'Overview' });
+});
diff --git a/packages/starlight/components/Search.astro b/packages/starlight/components/Search.astro
index be8997a8ad7..89c2bed0e9b 100644
--- a/packages/starlight/components/Search.astro
+++ b/packages/starlight/components/Search.astro
@@ -58,31 +58,37 @@ const pagefindTranslations = {
const dialog = this.querySelector('dialog')!;
const dialogFrame = this.querySelector('.dialog-frame')!;
- /** Close the modal if a user clicks outside of the modal. */
- const onWindowClick = (event: MouseEvent) => {
+ /** Close the modal if a user clicks on a link or outside of the modal. */
+ const onClick = (event: MouseEvent) => {
+ const isLink = 'href' in (event.target || {});
if (
- document.body.contains(event.target as Node) &&
- !dialogFrame.contains(event.target as Node)
- )
+ isLink ||
+ (document.body.contains(event.target as Node) &&
+ !dialogFrame.contains(event.target as Node))
+ ) {
closeModal();
+ }
};
const openModal = (event?: MouseEvent) => {
dialog.showModal();
+ document.body.toggleAttribute('data-search-modal-open', true);
this.querySelector('input')?.focus();
event?.stopPropagation();
- window.addEventListener('click', onWindowClick);
+ window.addEventListener('click', onClick);
};
- const closeModal = () => {
- dialog.close();
- window.removeEventListener('click', onWindowClick);
- };
+ const closeModal = () => dialog.close();
openBtn.addEventListener('click', openModal);
openBtn.disabled = false;
closeBtn.addEventListener('click', closeModal);
+ dialog.addEventListener('close', () => {
+ document.body.toggleAttribute('data-search-modal-open', false);
+ window.removeEventListener('click', onClick);
+ });
+
// Listen for `/` and `cmd + k` keyboard shortcuts.
window.addEventListener('keydown', (e) => {
const isInput =
@@ -110,9 +116,10 @@ const pagefindTranslations = {
new PagefindUI({
element: '#starlight__search',
baseUrl: import.meta.env.BASE_URL,
- bundlePath: import.meta.env.BASE_URL.replace(/\/$/, '') + '/_pagefind/',
+ bundlePath: import.meta.env.BASE_URL.replace(/\/$/, '') + '/pagefind/',
showImages: false,
translations,
+ showSubResults: true,
});
});
});
@@ -179,7 +186,7 @@ const pagefindTranslations = {
.dialog-frame {
flex-direction: column;
gap: 1rem;
- padding: 1.5rem;
+ padding: 1rem;
}
button[data-close-modal] {
@@ -198,6 +205,7 @@ const pagefindTranslations = {
#starlight__search {
--pagefind-ui-primary: var(--sl-color-accent-light);
--pagefind-ui-text: var(--sl-color-gray-2);
+ --pagefind-ui-font: var(--__sl-font);
--pagefind-ui-background: var(--sl-color-black);
--pagefind-ui-border: var(--sl-color-gray-5);
--pagefind-ui-border-width: 1px;
@@ -218,10 +226,35 @@ const pagefindTranslations = {
min-height: 15rem;
max-height: calc(100% - 8rem);
}
+
+ .dialog-frame {
+ padding: 1.5rem;
+ }
}
diff --git a/packages/starlight/components/TableOfContents/MobileTableOfContents.astro b/packages/starlight/components/TableOfContents/MobileTableOfContents.astro
index b4fc200021a..34fe1d5e19a 100644
--- a/packages/starlight/components/TableOfContents/MobileTableOfContents.astro
+++ b/packages/starlight/components/TableOfContents/MobileTableOfContents.astro
@@ -122,7 +122,7 @@ const t = useTranslations(locale);
}
constructor() {
- super({ smallViewport: true });
+ super();
const details = this.querySelector('details');
if (!details) return;
const closeToC = () => {
diff --git a/packages/starlight/components/TableOfContents/generateToC.ts b/packages/starlight/components/TableOfContents/generateToC.ts
index 30d1005fe08..73c08e3d472 100644
--- a/packages/starlight/components/TableOfContents/generateToC.ts
+++ b/packages/starlight/components/TableOfContents/generateToC.ts
@@ -4,52 +4,29 @@ export interface TocItem extends MarkdownHeading {
children: TocItem[];
}
-function diveChildren(item: TocItem, depth: number): TocItem[] {
- if (depth === 1) {
- return item.children;
- } else if (item.children.length > 0) {
- return diveChildren(item.children.at(-1)!, depth - 1);
- } else {
- return [];
- }
-}
-
interface TocOpts {
minHeadingLevel: number;
maxHeadingLevel: number;
- title?: string;
+ title: string;
}
+/** Convert the flat headings array generated by Astro into a nested tree structure. */
export function generateToC(
headings: MarkdownHeading[],
- { minHeadingLevel, maxHeadingLevel, title = 'Overview' }: TocOpts
+ { minHeadingLevel, maxHeadingLevel, title }: TocOpts
) {
- const overview = { depth: 2, slug: '_top', text: title };
- headings = [
- overview,
- ...headings.filter(({ depth }) => depth >= minHeadingLevel && depth <= maxHeadingLevel),
- ];
- const toc: Array = [];
+ headings = headings.filter(({ depth }) => depth >= minHeadingLevel && depth <= maxHeadingLevel);
+ const toc: Array = [{ depth: 2, slug: '_top', text: title, children: [] }];
+ for (const heading of headings) injectChild(toc, { ...heading, children: [] });
+ return toc;
+}
- for (const heading of headings) {
- if (toc.length === 0) {
- toc.push({ ...heading, children: [] });
- } else {
- const lastItemInToc = toc.at(-1)!;
- if (heading.depth < lastItemInToc.depth) {
- throw new Error(`Orphan heading found: ${heading.text}.`);
- }
- if (heading.depth === lastItemInToc.depth) {
- // same depth
- toc.push({ ...heading, children: [] });
- } else {
- // higher depth
- // push into children, or children's children alike
- const gap = heading.depth - lastItemInToc.depth;
- const target = diveChildren(lastItemInToc, gap);
- target.push({ ...heading, children: [] });
- }
- }
+/** Inject a ToC entry as deep in the tree as its `depth` property requires. */
+function injectChild(items: TocItem[], item: TocItem): void {
+ const lastItem = items.at(-1);
+ if (!lastItem || lastItem.depth >= item.depth) {
+ items.push(item);
+ } else {
+ return injectChild(lastItem.children, item);
}
- return toc;
}
diff --git a/packages/starlight/components/TableOfContents/starlight-toc.ts b/packages/starlight/components/TableOfContents/starlight-toc.ts
index 1d1f4cd0231..4283f36168d 100644
--- a/packages/starlight/components/TableOfContents/starlight-toc.ts
+++ b/packages/starlight/components/TableOfContents/starlight-toc.ts
@@ -10,7 +10,7 @@ export class StarlightTOC extends HTMLElement {
this._current = link;
}
- constructor({ smallViewport = false } = {}) {
+ constructor() {
super();
/** All the links in the table of contents. */
@@ -68,19 +68,13 @@ export class StarlightTOC extends HTMLElement {
// Also observe direct children of `.content` to include elements before
// the first heading.
const toObserve = document.querySelectorAll('main [id], main [id] ~ *, main .content > *');
- /** Start intersections at nav height + 2rem padding. */
- const top = (smallViewport ? 104 : 64) + 32;
- /** End intersections 1.5rem later. */
- const bottom = top + 24;
let observer: IntersectionObserver | undefined;
- function observe() {
+ const observe = () => {
if (observer) observer.disconnect();
- const height = document.documentElement.clientHeight;
- const rootMargin = `-${top}px 0% ${bottom - height}px`;
- observer = new IntersectionObserver(setCurrent, { rootMargin });
+ observer = new IntersectionObserver(setCurrent, { rootMargin: this.getRootMargin() });
toObserve.forEach((h) => observer!.observe(h));
- }
+ };
observe();
const onIdle = window.requestIdleCallback || ((cb) => setTimeout(cb, 1));
@@ -92,6 +86,18 @@ export class StarlightTOC extends HTMLElement {
timeout = setTimeout(() => onIdle(observe), 200);
});
}
+
+ private getRootMargin(): `-${number}px 0% ${number}px` {
+ const navBarHeight = document.querySelector('header')?.getBoundingClientRect().height || 0;
+ // `` only exists in mobile ToC, so will fall back to 0 in large viewport component.
+ const mobileTocHeight = this.querySelector('summary')?.getBoundingClientRect().height || 0;
+ /** Start intersections at nav height + 2rem padding. */
+ const top = navBarHeight + mobileTocHeight + 32;
+ /** End intersections 1.5rem later. */
+ const bottom = top + 24;
+ const height = document.documentElement.clientHeight;
+ return `-${top}px 0% ${bottom - height}px`;
+ }
}
customElements.define('starlight-toc', StarlightTOC);
diff --git a/packages/starlight/index.ts b/packages/starlight/index.ts
index 2198f13fc17..50e37d046c0 100644
--- a/packages/starlight/index.ts
+++ b/packages/starlight/index.ts
@@ -68,7 +68,7 @@ export default function StarlightIntegration(opts: StarlightUserConfig): AstroIn
const cwd = dirname(fileURLToPath(import.meta.url));
const relativeDir = relative(cwd, targetDir);
return new Promise((resolve) => {
- spawn('npx', ['-y', 'pagefind', '--source', relativeDir], {
+ spawn('npx', ['-y', 'pagefind', '--site', relativeDir], {
stdio: 'inherit',
shell: true,
cwd,
diff --git a/packages/starlight/layout/Page.astro b/packages/starlight/layout/Page.astro
index 7b01c441c41..0999122dffc 100644
--- a/packages/starlight/layout/Page.astro
+++ b/packages/starlight/layout/Page.astro
@@ -45,6 +45,8 @@ const tocConfig = !hasSidebar
: config.tableOfContents;
const hasToC = Boolean(tocConfig);
const hasHero = Boolean(entry.data.hero);
+const pagefindEnabled =
+ entry.slug !== '404' && !entry.slug.endsWith('/404') && entry.data.pagefind !== false;
---
}
+
{/* TODO: Revisit how this logic flows. */}
{entry.data.banner &&
` e `` sono incluse nell'indice dei contenuti. Modifica i livelli delle intestazioni da includere in tutto il sito utilizzando le opzioni `minHeadingLevel` e `maxHeadingLevel` nel tuo [global `tableOfContents`](/it/reference/configuration/#tableofcontents). Sostituisci queste impostazioni predefinite su una singola pagina aggiungendo le proprietà [frontmatter `tableOfContents`](/it/reference/frontmatter/#tableofcontents) corrispondenti:
+
+
+
+
+```md
+---
+# src/content/docs/example.md
+title: Pagina con solo H2 nell'indice dei contenuti
+summary:
+ minHeadingLevel: 2
+ maxHeadingLevel: 2
+---
+```
+
+
+
+
+```js
+// astro.config.mjs
+
+defineConfig({
+ integrations: [
+ starlight({
+ title: '',
+ tableOfContents: { minHeadingLevel: 2, maxHeadingLevel: 2 },
+ }),
+ ],
+});
+```
+
+
+
+
+Disabilita completamente l'indice dei contenuti impostando l'opzione `tableOfContents` su `false`:
+
+
+
+
+```md
+---
+# src/content/docs/esempio.md
+title: Pagina senza indice dei contenuti
+tableOfContents: false
+---
+```
+
+
+
+
+```js
+// astro.config.mjs
+
+defineConfig({
+ integrations: [
+ starlight({
+ title:
+ 'Documentazione con indice dei contenuti disabilitato a livello globale',
+ tableOfContents: false,
+ }),
+ ],
+});
+```
+
+
+
+
+## Collegamenti social
+
+Starlight dispone del supporto integrato per aggiungere collegamenti ai tuoi account di social media all'intestazione del sito tramite l'opzione [`social`](/it/reference/configuration/#social) nell'integrazione Starlight.
+
+Attualmente sono supportati i collegamenti a Bitbucket, Codeberg, CodePen, Discord, GitHub, GitLab, Gitter, Instagram, LinkedIn, Mastodon, Microsoft Teams, Stack Overflow, Threads, Twitch, Twitter e Youtube.
+Facci sapere su GitHub o Discord se hai bisogno di supporto per un altro servizio!
+
+```js
+// astro.config.mjs
+import { defineConfig } from 'astro/config';
+import starlight from '@astrojs/starlight';
+
+export default defineConfig({
+ integrations: [
+ starlight({
+ title: 'Documentazione con link social',
+ social: {
+ discord: 'https://astro.build/chat',
+ github: 'https://github.com/withastro/starlight',
+ },
+ }),
+ ],
+});
+```
+
+## Collegamenti di Modifica
+
+Starlight può visualizzare un collegamento "Modifica pagina" nel piè di pagina di ciascuna pagina.
+Ciò rende più semplice per il lettore trovare il file da modificare per migliorare i tuoi documenti.
+Per i progetti open source in particolare, questo può aiutare a incoraggiare i contributi della tua comunità.
+
+Per abilitare i collegamenti di modifica, imposta [`editLink.baseUrl`](/it/reference/configuration/#editlink) sull'URL utilizzato per modificare il tuo repository nella configurazione dell'integrazione Starlight.
+Il valore di `editLink.baseUrl` verrà anteposto al percorso della pagina corrente per formare il collegamento di modifica completo.
+
+I modelli comuni includono:
+
+- GitHub: `https://github.com/USER_NAME/REPO_NAME/edit/BRANCH_NAME/`
+- GitLab: `https://gitlab.com/USER_NAME/REPO_NAME/-/edit/BRANCH_NAME/`
+
+Se il tuo progetto Starlight non è nella radice del tuo repository, includi il percorso del progetto alla fine dell'URL di base.
+
+Questo esempio mostra il collegamento di modifica configurato per i documenti Starlight, che si trovano nella sottodirectory `docs/` sul ramo `main` del repository `withastro/starlight` su GitHub:
+
+```js
+// astro.config.mjs
+import { defineConfig } from 'astro/config';
+import starlight from '@astrojs/starlight';
+
+export default defineConfig({
+ integrations: [
+ starlight({
+ title: 'Documentazione con collegamenti di modifica',
+ editLink: {
+ baseUrl: 'https://github.com/withastro/starlight/edit/main/docs/',
+ },
+ }),
+ ],
+});
+```
+
+## Pagina 404 personalizzata
+
+Per impostazione predefinita, i siti Starlight visualizzano una semplice pagina 404.
+Puoi personalizzarlo aggiungendo un file `404.md` (o `404.mdx`) alla tua directory `src/content/docs/`:
+
+
+
+- src/
+ - content/
+ - docs/
+ - **404.md**
+ - index.md
+- astro.config.mjs
+
+
+
+Puoi utilizzare tutto il layout di pagina e le tecniche di personalizzazione di Starlight nella tua pagina 404. Ad esempio, la pagina 404 predefinita utilizza il componente [`splash` template](#page-layout) e [`hero`](/it/reference/frontmatter/#hero) in frontmatter:
+
+```md
+---
+title: '404'
+template: splash
+editUrl: false
+hero:
+ title: '404'
+ tagline: Pagina non trovata. Controlla l'URL o prova a utilizzare la barra di ricerca.
+---
+```
+
+## Caratteri personalizzati
+
+Per impostazione predefinita, Starlight utilizza i caratteri sans-serif disponibili sul dispositivo locale dell'utente per tutto il testo.
+Ciò garantisce che la documentazione venga caricata rapidamente in un carattere familiare a ciascun utente, senza richiedere larghezza di banda aggiuntiva per scaricare file di caratteri di grandi dimensioni.
+
+Se devi aggiungere un carattere personalizzato al tuo sito Starlight, puoi impostare i caratteri da utilizzare nei file CSS personalizzati o con qualsiasi altra [tecnica di stile Astro](https://docs.astro.build/it/guides/styling/) .
+
+### Imposta i caratteri
+
+Se disponi già di file di font, segui la [guida alla configurazione locale](#configura-i-file-dei-caratteri-locali).
+Per utilizzare Google Fonts, segui la [guida alla configurazione di Fontsource](#configura-un-font-fontsource).
+
+#### Configura i file dei caratteri locali
+
+1. Aggiungi i file dei caratteri a una directory `src/fonts/` e crea un file `font-face.css` vuoto:
+
+
+
+ - src/
+ - content/
+ - fonts/
+ - **CustomFont.woff2**
+ - **font-face.css**
+ - astro.config.mjs
+
+
+
+2. Aggiungi una [dichiarazione `@font-face`](https://developer.mozilla.org/en-US/docs/Web/CSS/@font-face) per ciascuno dei tuoi caratteri in `src/fonts/font-face.css`.
+ Utilizza un percorso relativo al file del font nella funzione `url()`.
+
+ ```css
+ /* src/fonts/font-face.css */
+
+ @font-face {
+ font-family: 'Font Personalizzato';
+ /* Utilizza un percorso relativo al file del font locale in `url()`. */
+ src: url('./CustomFont.woff2') format('woff2');
+ font-weight: normal;
+ font-style: normal;
+ font-display: swap;
+ }
+ ```
+
+3. Aggiungi il percorso del tuo file `font-face.css` all'array `customCss` di Starlight in `astro.config.mjs`:
+
+ ```js
+ // astro.config.mjs
+ import { defineConfig } from 'astro/config';
+ import starlight from '@astrojs/starlight';
+
+ export default defineConfig({
+ integrations: [
+ starlight({
+ title: 'Documentazione con font personalizzato',
+ customCss: [
+ // Percorso relativo al file CSS @font-face.
+ './src/fonts/font-face.css',
+ ],
+ }),
+ ],
+ });
+ ```
+
+#### Configura un font Fontsource
+
+Il progetto [Fontsource](https://fontsource.org/) semplifica l'utilizzo di Google Fonts e altri caratteri open source.
+Fornisce moduli npm che puoi installare per i caratteri che desideri utilizzare e include file CSS già pronti da aggiungere al tuo progetto.
+
+1. Trova il font che desideri utilizzare nel [catalogo di Fontsource](https://fontsource.org/).
+ Questo esempio utilizzerà [IBM Plex Serif](https://fontsource.org/fonts/ibm-plex-serif).
+
+2. Installa il pacchetto per il font scelto.
+ Puoi trovare il nome del pacchetto facendo clic su "Installa" nella pagina dei caratteri Fontsource.
+
+
+
+
+
+ ```sh
+ npm install @fontsource/ibm-plex-serif
+ ```
+
+
+
+
+
+ ```sh
+ pnpm install @fontsource/ibm-plex-serif
+ ```
+
+
+
+
+
+ ```sh
+ yarn add @fontsource/ibm-plex-serif
+ ```
+
+
+
+
+
+3. Aggiungi i file CSS Fontsource all'array `customCss` di Starlight in `astro.config.mjs`:
+
+ ```js
+ // astro.config.mjs
+ import { defineConfig } from 'astro/config';
+ import starlight from '@astrojs/starlight';
+
+ export default defineConfig({
+ integrations: [
+ starlight({
+ title: 'Docs With a Custom Typeface',
+ customCss: [
+ // File Fontsource per pesi di font regolari e semi-grassetto.
+ '@fontsource/ibm-plex-serif/400.css',
+ '@fontsource/ibm-plex-serif/600.css',
+ ],
+ }),
+ ],
+ });
+ ```
+
+ Fontsource fornisce più file CSS per ciascun font. Consulta la [documentazione Fontsource](https://fontsource.org/docs/getting-started/install#4-weights-and-styles) sull'inclusione di pesi e stili diversi per capire quale utilizzare.
+
+### Usa i caratteri
+
+Per applicare il font che hai impostato al tuo sito, utilizza il nome del font scelto in un [file CSS personalizzato](/it/guides/css-and-tailwind/#custom-css-styles).
+Ad esempio, per sovrascrivere ovunque il font predefinito di Starlight, imposta la proprietà personalizzata `--sl-font`:
+
+```css
+/* src/styles/custom.css */
+
+:root {
+ --sl-font: 'IBM Plex Serif', serif;
+}
+```
+
+Puoi anche scrivere CSS più mirati se desideri applicare il tuo font in modo più selettivo.
+Ad esempio, per impostare un font solo sul contenuto principale, ma non sulle barre laterali:
+
+```css
+/* src/styles/custom.css */
+
+main {
+ font-family: 'IBM Plex Serif', serif;
+}
+```
+
+Segui le [istruzioni CSS personalizzate](/it/guides/css-and-tailwind/#custom-css-styles) per aggiungere i tuoi stili al tuo sito.
diff --git a/docs/src/content/docs/it/guides/i18n.mdx b/docs/src/content/docs/it/guides/i18n.mdx
index 9a06c0efc91..8965b396272 100644
--- a/docs/src/content/docs/it/guides/i18n.mdx
+++ b/docs/src/content/docs/it/guides/i18n.mdx
@@ -143,7 +143,7 @@ Se una traduzione non è ancora disponibile per una lingua, Starlight mostrerà
In aggiunta alla possibilità di avere pagine multilingua, Starlight permette di tradurre le scritte dell'interfaccia (per esempio l'intestazione "In questa pagina" nella tabella dei contenuti) in modo che i lettori possano vedere il sito interamente nella lingua selezionata.
-Inglese, francese, tedesco, giapponese, portoghese, spagnolo e italiano sono disponibili di default, e sono benvenute [contribuzioni per aggiungere altre lingue](https://github.com/withastro/starlight/blob/main/CONTRIBUTING.md).
+Le stringhe dell'interfaccia utente tradotte in inglese, ceco, francese, tedesco, italiano, giapponese, portoghese, olandese, danese, spagnolo, turco, arabo, norvegese, farsi, cinese semplificato, coreano, russo e svedese sono disponibili di default e accettiamo [contributi per aggiungere altre lingue predefinite](https://github.com/withastro/starlight/blob/main/CONTRIBUTING.md).
Puoi fornire traduzioni per lingue aggiuntive — o sovrascrivere i valori predefiniti — con la collezione `i18n`.
diff --git a/docs/src/content/docs/it/guides/sidebar.mdx b/docs/src/content/docs/it/guides/sidebar.mdx
new file mode 100644
index 00000000000..b5d6570d9c2
--- /dev/null
+++ b/docs/src/content/docs/it/guides/sidebar.mdx
@@ -0,0 +1,480 @@
+---
+title: Navigazione nella barra laterale
+description: Scopri come impostare e personalizzare i collegamenti di navigazione della barra laterale del tuo sito Starlight.
+sidebar:
+ badge: Nuovo
+---
+
+import FileTree from '../../../../components/file-tree.astro';
+import SidebarPreview from '../../../../components/sidebar-preview.astro';
+
+Una barra laterale ben organizzata è fondamentale per una buona documentazione poiché è uno dei modi principali in cui gli utenti navigheranno nel tuo sito. Starlight fornisce un set completo di opzioni per personalizzare il layout e il contenuto della barra laterale.
+
+## Barra laterale predefinita
+
+Per impostazione predefinita, Starlight genererà automaticamente una barra laterale in base alla struttura del file system della documentazione, utilizzando la proprietà `title` di ciascun file come voce della barra laterale.
+
+Ad esempio, data la seguente struttura di file:
+
+
+
+- src/
+ - content/
+ - docs/
+ - guides/
+ - components.md
+ - i18n.md
+ - reference/
+ - configuration.md
+
+
+
+Verrà generata automaticamente la seguente barra laterale:
+
+
+
+- src/
+ - content/
+ - docs/
+ - guides/
+ - components.md
+ - i18n.md
+ - advanced/
+ - project-structure.md
+
+
+
+Verrà generata la seguente barra laterale:
+
+
+
+ ```sh
+ npx astro add starlight
+ ```
+
+
+
+ ```sh
+ pnpm astro add starlight
+ ```
+
+
+ ```sh
+ yarn astro add starlight
+ ```
+
+
+
+
+Questo installerà le dipendenze richieste e aggiungerà Starlight all'array `integrations` nel tuo file di configurazione Astro.
+
+### Configura l'integrazione
+
+L'integrazione Starlight è configurata nel file `astro.config.mjs`.
+
+Aggiungi un `title` per iniziare:
+
+```js {7-9}
+// astro.config.mjs
+import { defineConfig } from 'astro/config';
+import starlight from '@astrojs/starlight';
+
+export default defineConfig({
+ integrations: [
+ starlight({
+ title: 'Il mio meraviglioso sito di documentazione',
+ }),
+ ],
+});
+```
+
+Trova tutte le opzioni disponibili nel [riferimento per la configurazione di Starlight](/it/reference/configuration/).
+
+### Configura raccolte di contenuti
+
+Starlight si basa sulle [raccolte di contenuti](https://docs.astro.build/it/guides/content-collections/) di Astro, che sono configurate nel file `src/content/config.ts`.
+
+Crea o aggiorna il file di configurazione del contenuto, aggiungendo una raccolta `docs` che utilizza `docsSchema` di Starlight:
+
+```js ins={3,6}
+// src/content/config.ts
+import { defineCollection } from 'astro:content';
+import { docsSchema } from '@astrojs/starlight/schema';
+
+export const collections = {
+ docs: defineCollection({ schema: docsSchema() }),
+};
+```
+
+### Aggiungi contenuto
+
+Starlight è ora configurato ed è ora di aggiungere alcuni contenuti!
+
+Crea una directory `src/content/docs/` e inizia aggiungendo un file `index.md`.
+Questa sarà la home page del tuo nuovo sito:
+
+```md
+---
+# src/content/docs/index.md
+title: I miei documenti
+description: Scopri di più sul mio progetto in questo sito di documenti creato con Starlight.
+---
+
+Benvenuti nel mio progetto!
+```
+
+Starlight utilizza il routing basato su file, il che significa che ogni file Markdown, MDX o Markdoc in `src/content/docs/` verrà trasformato in una pagina sul tuo sito. I metadati di Frontmatter (i campi `title` e `description` nell'esempio sopra) possono modificare il modo in cui viene visualizzata ciascuna pagina.
+Vedi tutte le opzioni disponibili nel [riferimento frontmatter](/it/reference/frontmatter/).
+
+## Suggerimenti per i siti esistenti
+
+Se hai un progetto Astro esistente, puoi utilizzare Starlight per aggiungere rapidamente una sezione di documentazione al tuo sito.
+
+### Usa Starlight in un sottopercorso
+
+Per aggiungere tutte le pagine Starlight in un sottopercorso, posiziona tutto il contenuto dei tuoi documenti in una sottodirectory di `src/content/docs/`.
+
+Ad esempio, se le pagine Starlight dovessero iniziare tutte con `/guides/`, aggiungi il contenuto nella directory `src/content/docs/guides/`:
+
+import FileTree from '../../../components/file-tree.astro';
+
+
+
+- src/
+ - content/
+ - docs/
+ - **guides/**
+ - guide.md
+ - index.md
+ - pages/
+- astro.config.mjs
+
+
+
+In futuro, prevediamo di supportare meglio questo caso d'uso per evitare la necessità di una directory all'interno di una directory aggiuntiva in `src/content/docs/`.
+
+### Usa Starlight con SSR
+
+Attualmente, Starlight non supporta [distribuzione SSR](https://docs.astro.build/it/guides/server-side-rendering/) utilizzando gli adattatori server di Astro. Speriamo di poterlo supportare presto.
diff --git a/docs/src/content/docs/it/reference/configuration.md b/docs/src/content/docs/it/reference/configuration.md
index 1fadaf13974..950e7cf0106 100644
--- a/docs/src/content/docs/it/reference/configuration.md
+++ b/docs/src/content/docs/it/reference/configuration.md
@@ -44,7 +44,7 @@ Definisce il logo da rappresentare nella barra di navigazione con o al posto del
```js
starlight({
logo: {
- src: '/src/assets/my-logo.svg',
+ src: './src/assets/my-logo.svg',
},
});
```
@@ -87,13 +87,20 @@ Con questa configurazione, una pagina `/introduction` avrà un link di modifica
Configura la barra laterale di navigazione del tuo sito.
-Una barra laterale è un array di gruppi, ognuno avente un `label` e o un array `items` o un oggetto `autogenerate`.
+Una barra laterale è un array di collegamenti e gruppi di collegamenti.
+Ogni elemento avente un `label` e una delle seguenti proprietà:
-Puoi manualmente impostare i contenuti di un gruppo con `items`, che è un array che può includere link e sottogruppi. Puoi anche automaticamente generare i contenuti di un gruppo da una specifica cartella della documentazione utilizzando `autogenerate`.
+- `link` — un singolo colelgamento a uno specifico URL, ad es. `'/home'` o `'https://example.com'`.
+
+- `items` — an aray contenente più collegamenti della barra laterale e sottogruppi.
+
+- `autogenerate` — un oggetto indicante una cartella dei tuoi documenti di cui generare automaticamente i collegamenti.
```js
starlight({
sidebar: [
+ // Un singolo elemento chiamato “Home”.
+ { label: 'Home', link: '/' },
// Un gruppo intitolato "Inizia qui" contenente due link.
{
label: 'Inizia qui',
@@ -116,6 +123,34 @@ starlight({
I gruppi generati automaticamente sono ordinati alfabeticamente.
Per esempio, una pagina generata da `astro.md` apparirà sopra a quella generata da `starlight.md`.
+#### Gruppi comprimibili
+
+I gruppi di collegamenti vengono espansi per impostazione predefinita. Puoi modificare questo comportamento impostando la proprietà `collapsed` di un gruppo su `true`.
+
+I sottogruppi generati automaticamente rispettano la proprietà `collapsed` del gruppo principale per impostazione predefinita. Imposta la proprietà `autogenerate.collapsed` per sovrascriverla.
+
+```js
+sidebar: [
+ // Un gruppo di collegamenti compresso.
+ {
+ label: 'Collegamenti compressi',
+ collapsed: true,
+ items: [
+ { label: 'Introduzione', link: '/intro' },
+ { label: 'Prossimi passi', link: '/next-steps' },
+ ],
+ },
+ // An expanded group containing collapsed autogenerated subgroups.
+ {
+ label: 'Riferimenti',
+ autogenerate: {
+ directory: 'reference',
+ collapsed: true,
+ },
+ },
+],
+```
+
#### Tradurre i titoli
Se il tuo sito è multilingua, ogni elemento di `label` è considerato come appartenente alla lingua di default. Puoi definire `translations` per fornire i titoli per le altre lingue:
@@ -139,33 +174,34 @@ sidebar: [
},
],
},
-];
+],
```
-#### `SidebarGroup`
+#### `SidebarItem`
```ts
-type SidebarGroup =
+type SidebarItem = {
+ label: string;
+ translations?: Record;
+} & (
| {
- label: string;
- translations?: Record;
- items: Array;
+ link: string;
+ badge?: string | BadgeConfig;
}
+ | { items: SidebarItem[]; collapsed?: boolean }
| {
- label: string;
- translations?: Record;
- autogenerate: {
- directory: string;
- };
- };
+ autogenerate: { directory: string; collapsed?: boolean };
+ collapsed?: boolean;
+ }
+);
```
-#### `LinkItem`
+#### `BadgeConfig`
```ts
-interface LinkItem {
- label: string;
- link: string;
+interface BadgeConfig {
+ text: string;
+ variant: 'note' | 'tip' | 'caution' | 'danger' | 'success' | 'default';
}
```
@@ -271,17 +307,23 @@ Verrà utilizzato come fallback per le pagine non tradotte.
### `social`
-**type:** `{ discord?: string; github?: string; mastodon?: string; twitter?: string }`
+**type:** `Partial>`
Dettagli opzionali per gli account social del sito. Se vengono aggiunti apparirà l'icona corrispondente nella barra superiore.
```js
starlight({
social: {
+ codeberg: 'https://codeberg.org/knut/examples',
discord: 'https://astro.build/chat',
github: 'https://github.com/withastro/starlight',
+ gitlab: 'https://gitlab.com/delucis',
+ linkedin: 'https://www.linkedin.com/company/astroinc',
mastodon: 'https://m.webtoo.ls/@astro',
+ threads: 'https://www.threads.net/@nmoodev',
+ twitch: 'https://www.twitch.tv/bholmesdev',
twitter: 'https://twitter.com/astrodotbuild',
+ youtube: 'https://youtube.com/@astrodotbuild',
},
});
```
@@ -332,3 +374,53 @@ interface HeadConfig {
content?: string;
}
```
+
+### `lastUpdated`
+
+**type:** `boolean`
+**default:** `false`
+
+Controlla se il piè di pagina mostra quando è stata aggiornata l'ultima volta la pagina.
+
+Per impostazione predefinita, questa funzionalità si basa sulla cronologia Git del repository e potrebbe non essere accurata su alcune piattaforme di distribuzione che eseguono [cloni superficiali](https://git-scm.com/docs/git-clone#Documentation/git-clone.txt---depthltdepthgt). Una pagina può sovrascrivere questa impostazione o la data basata su Git utilizzando il [campo frontmatter `lastUpdated`](/it/reference/frontmatter/#lastupdated).
+
+### `pagination`
+
+**type:** `boolean`
+**default:** `true`
+
+Definisci se il piè di pagina deve includere i collegamenti alla pagina precedente e successiva.
+
+Una pagina può sovrascrivere questa impostazione o il testo del collegamento e/o l'URL utilizzando i campi frontmatter [`prev`](/it/reference/frontmatter/#prev) e [`next`](/it/reference/frontmatter/#next).
+
+### `favicon`
+
+**type:** `string`
+**default:** `'/favicon.svg'`
+
+Imposta il percorso della favicon predefinita per il tuo sito web che dovrebbe trovarsi nella directory `public/` ed essere valido (`.ico`, `.gif`, `.jpg`, `.png` o `.svg`) file di icone.
+
+```js
+starlight({
+ favicon: '/images/favicon.svg',
+}),
+```
+
+Se devi impostare varianti aggiuntive o favicon di fallback, puoi aggiungere tag utilizzando l'[opzione`head`](#head):
+
+```js
+starlight({
+ favicon: '/images/favicon.svg'.
+ head: [
+ // Aggiungi il fallback della favicon ICO per Safari.
+ {
+ tag: 'link',
+ attrs: {
+ rel: 'icon',
+ href:'/images/favicon.ico',
+ sizes: '32x32',
+ },
+ },
+ ],
+});
+```
diff --git a/docs/src/content/docs/it/reference/frontmatter.md b/docs/src/content/docs/it/reference/frontmatter.md
index 681b8d78145..3a76d172498 100644
--- a/docs/src/content/docs/it/reference/frontmatter.md
+++ b/docs/src/content/docs/it/reference/frontmatter.md
@@ -57,6 +57,22 @@ head:
Sovrascrive la [configurazione globale `tableOfContents`](/it/reference/configuration/#tableofcontents).
Cambia i livelli di titoli inclusi o, se messo a `false`, nasconde la tabella dei contenuti della pagina.
+```md
+---
+title: Pagina con solo H2 nella tabella dei contenuti della pagina
+tableOfContents:
+ minHeadingLevel: 2
+ maxHeadingLevel: 2
+---
+```
+
+```md
+---
+title: Pagina senza tabella dei contenuti della pagina
+tableOfContents: false
+---
+```
+
### `template`
**type:** `'doc' | 'splash'`
@@ -117,3 +133,169 @@ interface HeroConfig {
}>;
}
```
+
+### `banner`
+
+**type:** `{ content: string }`
+
+Visualizza un banner di annuncio nella parte superiore di questa pagina.
+
+Il valore `content` può includere HTML per collegamenti o altri contenuti.
+Ad esempio, questa pagina visualizza un banner che include un collegamento a `example.com`.
+
+```md
+---
+title: Pagina con un banner
+banner:
+ content: |
+ Abbiamo appena lanciato qualcosa di interessante!
+ Dai un'occhiata
+---
+```
+
+### `lastUpdated`
+
+**type:** `Date | boolean`
+
+Sostituisce l'[opzione globale `lastUpdated`](/it/reference/configuration/#lastupdated). Se viene specificata una data, deve essere un [timestamp YAML](https://yaml.org/type/timestamp.html) valido e sovrascriverà la data archiviata nella cronologia Git per questa pagina.
+
+```md
+---
+title: Pagina con una data di ultimo aggiornamento personalizzata
+lastUpdated: 2022-08-09
+---
+```
+
+### `prev`
+
+**type:** `boolean | string | { link?: string; label?: string }`
+
+Sostituisce l'[opzione globale `paginazione`](/it/reference/configuration/#pagination). Se viene specificata una stringa, il testo del collegamento generato verrà sostituito e se viene specificato un oggetto, sia il collegamento che il testo verranno sovrascritti.
+
+```md
+---
+# Nascondi il collegamento alla pagina precedente
+prev: false
+---
+```
+
+```md
+---
+# Sostituisci il testo del collegamento della pagina precedente
+prev: Continua il tutorial
+---
+```
+
+```md
+---
+# Sostituisci sia il collegamento che il testo della pagina precedente
+prev:
+ link: /pagina-non-correlata/
+ label: Dai un'occhiata a quest'altra pagina
+---
+```
+
+### `next`
+
+**type:** `boolean | string | { link?: string; label?: string }`
+
+Uguale a [`prev`](#prev) ma per il collegamento alla pagina successiva.
+
+```md
+---
+# Nascondi il collegamento alla pagina successiva
+next: false
+---
+```
+
+### `pagefind`
+
+**type:** `boolean`
+**default:** `true`
+
+Imposta se questa pagina deve essere inclusa nell'indice di ricerca [Pagefind](https://pagefind.app/). Imposta su `false` per escludere una pagina dai risultati di ricerca:
+
+```md
+---
+# Nascondi questa pagina dai risultati di ricerca
+pagefind: false
+---
+```
+
+### `sidebar`
+
+**type:** `{ label?: string; order?: number; hidden?: boolean; badge?: string | BadgeConfig }`
+
+Controlla il modo in cui questa pagina viene visualizzata nella [barra laterale](/it/reference/configuration/#sidebar), quando si utilizza un gruppo di collegamenti generato automaticamente.
+
+#### `label`
+
+**type:** `string`
+**default:** the page [`title`](#title-required)
+
+Imposta l'etichetta per questa pagina nella barra laterale quando viene visualizzata in un gruppo di collegamenti generato automaticamente.
+
+```md
+---
+title: Informazioni su questo progetto
+sidebar:
+ label: Informazioni
+---
+```
+
+#### `order`
+
+**type:** `number`
+
+Controlla l'ordine di questa pagina quando ordini un gruppo di collegamenti generato automaticamente.
+I numeri più bassi vengono visualizzati più in alto nel gruppo di collegamenti.
+
+```md
+---
+title: Pagina da visualizzare per prima
+sidebar:
+ order: 1
+---
+```
+
+#### `hidden`
+
+**type:** `boolean`
+**default:** `false`
+
+Impedisce che questa pagina venga inclusa in un gruppo della barra laterale generato automaticamente.
+
+```md
+---
+title: Pagina da nascondere dalla barra laterale generata automaticamente
+sidebar:
+ hidden: vero
+---
+```
+
+#### `badge`
+
+**type:** string | BadgeConfig
+
+Aggiungi un badge alla pagina nella barra laterale quando viene visualizzata in un gruppo di collegamenti generato automaticamente.
+Quando si utilizza una stringa, il badge verrà visualizzato con un colore in risalto predefinito.
+Facoltativamente, passa un [oggetto `BadgeConfig`](/it/reference/configuration/#badgeconfig) con i campi `text` e `variant` per personalizzare il badge.
+
+```md
+---
+title: Pagina con un badge
+sidebar:
+ # Utilizza la variante predefinita corrispondente al colore principale del tuo sito
+ badge: nuovo
+---
+```
+
+```md
+---
+title: Pagina con un badge
+sidebar:
+ badge:
+ text: Sperimentale
+ variant: caution
+---
+```
diff --git a/docs/src/content/docs/it/showcase.mdx b/docs/src/content/docs/it/showcase.mdx
new file mode 100644
index 00000000000..a3351f3f87c
--- /dev/null
+++ b/docs/src/content/docs/it/showcase.mdx
@@ -0,0 +1,53 @@
+---
+title: Vetrina Starlight
+description: Scopri i siti realizzati con Starlight e gli strumenti della community che estendono Starlight!
+---
+
+:::tip[Aggiungi il tuo!]
+Hai creato un sito Starlight o uno strumento per Starlight?
+Apri una PR aggiungendo un link a questa pagina!
+:::
+
+## Sites
+
+import ShowcaseSites from '../../../components/showcase-sites.astro';
+
+Starlight è già utilizzato nella produzione. Questi sono alcuni dei siti presenti sul web:
+
+
+
diff --git a/docs/src/content/docs/ja/guides/customization.mdx b/docs/src/content/docs/ja/guides/customization.mdx
index 5e113bf9f5c..fafe669206a 100644
--- a/docs/src/content/docs/ja/guides/customization.mdx
+++ b/docs/src/content/docs/ja/guides/customization.mdx
@@ -84,6 +84,19 @@ starlight({
}),
```
+## サイトマップを有効化する
+
+Starlightにはサイトマップ生成機能が組み込まれています。`astro.config.mjs`の`site`にURLを設定すると、サイトマップの生成が有効になります。
+
+```js
+// astro.config.mjs
+
+export default defineConfig({
+ site: 'https://stargazers.club',
+ integrations: [starlight({ title: 'サイトマップを設定したサイト' })],
+});
+```
+
## ページレイアウト
Starlightのページはデフォルトで、グローバルなナビゲーションサイドバーと、現在のページの見出しを表示する目次を配置したレイアウトを使用します。
diff --git a/docs/src/content/docs/ja/guides/i18n.mdx b/docs/src/content/docs/ja/guides/i18n.mdx
index 66d57cb9cc9..a7571086e52 100644
--- a/docs/src/content/docs/ja/guides/i18n.mdx
+++ b/docs/src/content/docs/ja/guides/i18n.mdx
@@ -141,7 +141,7 @@ Starlightは、すべての言語で同等のページが作成されること
Starlightでは、読者が選択した言語でサイト全体を体験できるように、翻訳されたコンテンツファイルをホストするだけでなく、デフォルトUIの文字列（たとえば目次に表示されている「目次」という見出し）も翻訳できるようになっています。
-英語、チェコ語、フランス語、ドイツ語、イタリア語、日本語、ポルトガル語、オランダ語、デンマーク語、スペイン語、トルコ語、アラビア語、ノルウェー語、ペルシア語、簡体字中国語、韓国語、スウェーデン語の翻訳済みUI文字列がすでに用意されていますが、[デフォルト言語をさらに追加するための貢献](https://github.com/withastro/starlight/blob/main/CONTRIBUTING.md)も歓迎します。
+英語、チェコ語、フランス語、ドイツ語、イタリア語、日本語、ポルトガル語、オランダ語、デンマーク語、スペイン語、トルコ語、アラビア語、ノルウェー語、ペルシア語、簡体字中国語、韓国語、ロシア語、スウェーデン語の翻訳済みUI文字列がすでに用意されていますが、[デフォルト言語をさらに追加するための貢献](https://github.com/withastro/starlight/blob/main/CONTRIBUTING.md)も歓迎します。
`18n`データコレクションを使用すると、サポートしたい言語の翻訳を追加したり、デフォルトのラベルを上書きしたりできます。
diff --git a/docs/src/content/docs/ja/reference/frontmatter.md b/docs/src/content/docs/ja/reference/frontmatter.md
index 56367ea651d..eb1aa6356a4 100644
--- a/docs/src/content/docs/ja/reference/frontmatter.md
+++ b/docs/src/content/docs/ja/reference/frontmatter.md
@@ -204,6 +204,20 @@ next: false
---
```
+### `pagefind`
+
+**type:** `boolean`
+**default:** `true`
+
+ページを[Pagefind](https://pagefind.app/)の検索インデックスに含めるかどうかを設定します。ページを検索結果から除外するには、`false`に設定します。
+
+```md
+---
+# このページを検索インデックスから外す
+pagefind: false
+---
+```
+
### `sidebar`
**type:** `{ label?: string; order?: number; hidden?: boolean; badge?: string | BadgeConfig }`
diff --git a/docs/src/content/docs/ja/showcase.mdx b/docs/src/content/docs/ja/showcase.mdx
index 18d24333ff6..68e1189b794 100644
--- a/docs/src/content/docs/ja/showcase.mdx
+++ b/docs/src/content/docs/ja/showcase.mdx
@@ -9,84 +9,11 @@ StarlightサイトやStarlightのツールを作成しましたか？このペ
## サイト
-import Card from '../../../components/showcase-card.astro';
-import FluidGrid from '../../../components/fluid-grid.astro';
+import ShowcaseSites from '../../../components/showcase-sites.astro';
Starlightはすでに本番環境で使用されています。以下はウェブ上のサイトの一部です。
-
-
+
+
+- src/
+ - content/
+ - docs/
+ - guides/
+ - components.md
+ - i18n.md
+ - reference/
+ - configuration.md
+
+
+
+다음 사이드바가 자동으로 생성됩니다.
+
+
+
+- src/
+ - content/
+ - docs/
+ - guides/
+ - components.md
+ - i18n.md
+ - advanced/
+ - project-structure.md
+
+
+
+다음 사이드바가 생성됩니다:
+
+
-
+
-
+
-
+
+
+- src/
+ - content/
+ - docs/
+ - guides/
+ - components.md
+ - i18n.md
+ - reference/
+ - configuration.md
+
+
+
+将会自动生成以下侧边栏：
+
+
+
+- src/
+ - content/
+ - docs/
+ - guides/
+ - components.md
+ - i18n.md
+ - advanced/
+ - project-structure.md
+
+
+
+将会自动生成以下侧边栏：
+
+
-
+` across lines to avoid overflow
+
+- [#642](https://github.com/withastro/starlight/pull/642) [`e623d92`](https://github.com/withastro/starlight/commit/e623d92c2fddc0ff5fe83d2554266885d683a906) Thanks [@fk](https://github.com/fk)! - Don't hard-code nav height in table of contents highlighting script
+
+- [#676](https://github.com/withastro/starlight/pull/676) [`6419006`](https://github.com/withastro/starlight/commit/641900615aa9a9a128d6934e65a57ba89e503cfd) Thanks [@vedmalex](https://github.com/vedmalex)! - Upgrade and pin Pagefind to latest beta release.
+
+- [#647](https://github.com/withastro/starlight/pull/647) [`ea57726`](https://github.com/withastro/starlight/commit/ea5772655274a3900310cb700836fdd2f6dba7cd) Thanks [@bgmort](https://github.com/bgmort)! - Add frontmatter option to exclude a page from Pagefind search results
+
## 0.9.0
### Minor Changes
diff --git a/packages/starlight/__tests__/basics/toc.test.ts b/packages/starlight/__tests__/basics/toc.test.ts
new file mode 100644
index 00000000000..51745d7b81c
--- /dev/null
+++ b/packages/starlight/__tests__/basics/toc.test.ts
@@ -0,0 +1,141 @@
+import { expect, test } from 'vitest';
+import { generateToC } from '../../components/TableOfContents/generateToC';
+
+const defaultOpts = { minHeadingLevel: 2, maxHeadingLevel: 3, title: 'Overview' };
+
+test('generates an overview entry with no headings available', () => {
+ const toc = generateToC([], defaultOpts);
+ expect(toc).toHaveLength(1);
+ expect(toc[0]).toEqual({ children: [], depth: 2, slug: '_top', text: 'Overview' });
+});
+
+test('generates entries from heading array', () => {
+ const toc = generateToC([{ text: 'One', slug: 'one', depth: 2 }], defaultOpts);
+ expect(toc).toHaveLength(2);
+ expect(toc[0]).toEqual({ children: [], depth: 2, slug: '_top', text: 'Overview' });
+ expect(toc[1]).toEqual({ children: [], depth: 2, slug: 'one', text: 'One' });
+});
+
+test('nests lower-level headings in children array h2 => h3', () => {
+ const toc = generateToC(
+ [
+ { text: 'One', slug: 'one', depth: 2 },
+ { text: 'Two', slug: 'two', depth: 3 },
+ ],
+ defaultOpts
+ );
+ expect(toc).toHaveLength(2);
+ expect(toc[0]).toEqual({ children: [], depth: 2, slug: '_top', text: 'Overview' });
+ expect(toc[1]).toEqual({
+ children: [{ children: [], depth: 3, slug: 'two', text: 'Two' }],
+ depth: 2,
+ slug: 'one',
+ text: 'One',
+ });
+});
+
+test('nests lower-level headings in children array h2 => h4', () => {
+ const toc = generateToC(
+ [
+ { text: 'One', slug: 'one', depth: 2 },
+ { text: 'Two', slug: 'two', depth: 4 },
+ ],
+ { ...defaultOpts, maxHeadingLevel: 6 }
+ );
+ expect(toc).toHaveLength(2);
+ expect(toc[0]).toEqual({ children: [], depth: 2, slug: '_top', text: 'Overview' });
+ expect(toc[1]).toEqual({
+ children: [{ children: [], depth: 4, slug: 'two', text: 'Two' }],
+ depth: 2,
+ slug: 'one',
+ text: 'One',
+ });
+});
+
+test('nests lower-level headings deeply h2 => h4 => h6', () => {
+ const toc = generateToC(
+ [
+ { text: 'One', slug: 'one', depth: 2 },
+ { text: 'Two', slug: 'two', depth: 4 },
+ { text: 'Three', slug: 'three', depth: 6 },
+ ],
+ { ...defaultOpts, maxHeadingLevel: 6 }
+ );
+ expect(toc).toHaveLength(2);
+ expect(toc[0]).toEqual({ children: [], depth: 2, slug: '_top', text: 'Overview' });
+ expect(toc[1]).toMatchInlineSnapshot(`
+ {
+ "children": [
+ {
+ "children": [
+ {
+ "children": [],
+ "depth": 6,
+ "slug": "three",
+ "text": "Three",
+ },
+ ],
+ "depth": 4,
+ "slug": "two",
+ "text": "Two",
+ },
+ ],
+ "depth": 2,
+ "slug": "one",
+ "text": "One",
+ }
+ `);
+});
+
+test('adds higher-level headings sequentially h6 => h4 => h2', () => {
+ const toc = generateToC(
+ [
+ { text: 'One', slug: 'one', depth: 6 },
+ { text: 'Two', slug: 'two', depth: 4 },
+ { text: 'Three', slug: 'three', depth: 2 },
+ ],
+ { ...defaultOpts, maxHeadingLevel: 6 }
+ );
+ expect(toc).toHaveLength(2);
+ expect(toc).toMatchInlineSnapshot(`
+ [
+ {
+ "children": [
+ {
+ "children": [],
+ "depth": 6,
+ "slug": "one",
+ "text": "One",
+ },
+ {
+ "children": [],
+ "depth": 4,
+ "slug": "two",
+ "text": "Two",
+ },
+ ],
+ "depth": 2,
+ "slug": "_top",
+ "text": "Overview",
+ },
+ {
+ "children": [],
+ "depth": 2,
+ "slug": "three",
+ "text": "Three",
+ },
+ ]
+ `);
+});
+
+test('filters out higher-level headings than minHeadingLevel', () => {
+ const toc = generateToC([{ text: 'One', slug: 'one', depth: 1 }], defaultOpts);
+ expect(toc).toHaveLength(1);
+ expect(toc[0]).toEqual({ children: [], depth: 2, slug: '_top', text: 'Overview' });
+});
+
+test('filters out lower-level headings than maxHeadingLevel', () => {
+ const toc = generateToC([{ text: 'One', slug: 'one', depth: 4 }], defaultOpts);
+ expect(toc).toHaveLength(1);
+ expect(toc[0]).toEqual({ children: [], depth: 2, slug: '_top', text: 'Overview' });
+});
diff --git a/packages/starlight/components/Search.astro b/packages/starlight/components/Search.astro
index be8997a8ad7..89c2bed0e9b 100644
--- a/packages/starlight/components/Search.astro
+++ b/packages/starlight/components/Search.astro
@@ -58,31 +58,37 @@ const pagefindTranslations = {
const dialog = this.querySelector('dialog')!;
const dialogFrame = this.querySelector('.dialog-frame')!;
- /** Close the modal if a user clicks outside of the modal. */
- const onWindowClick = (event: MouseEvent) => {
+ /** Close the modal if a user clicks on a link or outside of the modal. */
+ const onClick = (event: MouseEvent) => {
+ const isLink = 'href' in (event.target || {});
if (
- document.body.contains(event.target as Node) &&
- !dialogFrame.contains(event.target as Node)
- )
+ isLink ||
+ (document.body.contains(event.target as Node) &&
+ !dialogFrame.contains(event.target as Node))
+ ) {
closeModal();
+ }
};
const openModal = (event?: MouseEvent) => {
dialog.showModal();
+ document.body.toggleAttribute('data-search-modal-open', true);
this.querySelector('input')?.focus();
event?.stopPropagation();
- window.addEventListener('click', onWindowClick);
+ window.addEventListener('click', onClick);
};
- const closeModal = () => {
- dialog.close();
- window.removeEventListener('click', onWindowClick);
- };
+ const closeModal = () => dialog.close();
openBtn.addEventListener('click', openModal);
openBtn.disabled = false;
closeBtn.addEventListener('click', closeModal);
+ dialog.addEventListener('close', () => {
+ document.body.toggleAttribute('data-search-modal-open', false);
+ window.removeEventListener('click', onClick);
+ });
+
// Listen for `/` and `cmd + k` keyboard shortcuts.
window.addEventListener('keydown', (e) => {
const isInput =
@@ -110,9 +116,10 @@ const pagefindTranslations = {
new PagefindUI({
element: '#starlight__search',
baseUrl: import.meta.env.BASE_URL,
- bundlePath: import.meta.env.BASE_URL.replace(/\/$/, '') + '/_pagefind/',
+ bundlePath: import.meta.env.BASE_URL.replace(/\/$/, '') + '/pagefind/',
showImages: false,
translations,
+ showSubResults: true,
});
});
});
@@ -179,7 +186,7 @@ const pagefindTranslations = {
.dialog-frame {
flex-direction: column;
gap: 1rem;
- padding: 1.5rem;
+ padding: 1rem;
}
button[data-close-modal] {
@@ -198,6 +205,7 @@ const pagefindTranslations = {
#starlight__search {
--pagefind-ui-primary: var(--sl-color-accent-light);
--pagefind-ui-text: var(--sl-color-gray-2);
+ --pagefind-ui-font: var(--__sl-font);
--pagefind-ui-background: var(--sl-color-black);
--pagefind-ui-border: var(--sl-color-gray-5);
--pagefind-ui-border-width: 1px;
@@ -218,10 +226,35 @@ const pagefindTranslations = {
min-height: 15rem;
max-height: calc(100% - 8rem);
}
+
+ .dialog-frame {
+ padding: 1.5rem;
+ }
}
diff --git a/packages/starlight/components/TableOfContents/MobileTableOfContents.astro b/packages/starlight/components/TableOfContents/MobileTableOfContents.astro
index b4fc200021a..34fe1d5e19a 100644
--- a/packages/starlight/components/TableOfContents/MobileTableOfContents.astro
+++ b/packages/starlight/components/TableOfContents/MobileTableOfContents.astro
@@ -122,7 +122,7 @@ const t = useTranslations(locale);
}
constructor() {
- super({ smallViewport: true });
+ super();
const details = this.querySelector('details');
if (!details) return;
const closeToC = () => {
diff --git a/packages/starlight/components/TableOfContents/generateToC.ts b/packages/starlight/components/TableOfContents/generateToC.ts
index 30d1005fe08..73c08e3d472 100644
--- a/packages/starlight/components/TableOfContents/generateToC.ts
+++ b/packages/starlight/components/TableOfContents/generateToC.ts
@@ -4,52 +4,29 @@ export interface TocItem extends MarkdownHeading {
children: TocItem[];
}
-function diveChildren(item: TocItem, depth: number): TocItem[] {
- if (depth === 1) {
- return item.children;
- } else if (item.children.length > 0) {
- return diveChildren(item.children.at(-1)!, depth - 1);
- } else {
- return [];
- }
-}
-
interface TocOpts {
minHeadingLevel: number;
maxHeadingLevel: number;
- title?: string;
+ title: string;
}
+/** Convert the flat headings array generated by Astro into a nested tree structure. */
export function generateToC(
headings: MarkdownHeading[],
- { minHeadingLevel, maxHeadingLevel, title = 'Overview' }: TocOpts
+ { minHeadingLevel, maxHeadingLevel, title }: TocOpts
) {
- const overview = { depth: 2, slug: '_top', text: title };
- headings = [
- overview,
- ...headings.filter(({ depth }) => depth >= minHeadingLevel && depth <= maxHeadingLevel),
- ];
- const toc: Array = [];
+ headings = headings.filter(({ depth }) => depth >= minHeadingLevel && depth <= maxHeadingLevel);
+ const toc: Array = [{ depth: 2, slug: '_top', text: title, children: [] }];
+ for (const heading of headings) injectChild(toc, { ...heading, children: [] });
+ return toc;
+}
- for (const heading of headings) {
- if (toc.length === 0) {
- toc.push({ ...heading, children: [] });
- } else {
- const lastItemInToc = toc.at(-1)!;
- if (heading.depth < lastItemInToc.depth) {
- throw new Error(`Orphan heading found: ${heading.text}.`);
- }
- if (heading.depth === lastItemInToc.depth) {
- // same depth
- toc.push({ ...heading, children: [] });
- } else {
- // higher depth
- // push into children, or children's children alike
- const gap = heading.depth - lastItemInToc.depth;
- const target = diveChildren(lastItemInToc, gap);
- target.push({ ...heading, children: [] });
- }
- }
+/** Inject a ToC entry as deep in the tree as its `depth` property requires. */
+function injectChild(items: TocItem[], item: TocItem): void {
+ const lastItem = items.at(-1);
+ if (!lastItem || lastItem.depth >= item.depth) {
+ items.push(item);
+ } else {
+ return injectChild(lastItem.children, item);
}
- return toc;
}
diff --git a/packages/starlight/components/TableOfContents/starlight-toc.ts b/packages/starlight/components/TableOfContents/starlight-toc.ts
index 1d1f4cd0231..4283f36168d 100644
--- a/packages/starlight/components/TableOfContents/starlight-toc.ts
+++ b/packages/starlight/components/TableOfContents/starlight-toc.ts
@@ -10,7 +10,7 @@ export class StarlightTOC extends HTMLElement {
this._current = link;
}
- constructor({ smallViewport = false } = {}) {
+ constructor() {
super();
/** All the links in the table of contents. */
@@ -68,19 +68,13 @@ export class StarlightTOC extends HTMLElement {
// Also observe direct children of `.content` to include elements before
// the first heading.
const toObserve = document.querySelectorAll('main [id], main [id] ~ *, main .content > *');
- /** Start intersections at nav height + 2rem padding. */
- const top = (smallViewport ? 104 : 64) + 32;
- /** End intersections 1.5rem later. */
- const bottom = top + 24;
let observer: IntersectionObserver | undefined;
- function observe() {
+ const observe = () => {
if (observer) observer.disconnect();
- const height = document.documentElement.clientHeight;
- const rootMargin = `-${top}px 0% ${bottom - height}px`;
- observer = new IntersectionObserver(setCurrent, { rootMargin });
+ observer = new IntersectionObserver(setCurrent, { rootMargin: this.getRootMargin() });
toObserve.forEach((h) => observer!.observe(h));
- }
+ };
observe();
const onIdle = window.requestIdleCallback || ((cb) => setTimeout(cb, 1));
@@ -92,6 +86,18 @@ export class StarlightTOC extends HTMLElement {
timeout = setTimeout(() => onIdle(observe), 200);
});
}
+
+ private getRootMargin(): `-${number}px 0% ${number}px` {
+ const navBarHeight = document.querySelector('header')?.getBoundingClientRect().height || 0;
+ // `` only exists in mobile ToC, so will fall back to 0 in large viewport component.
+ const mobileTocHeight = this.querySelector('summary')?.getBoundingClientRect().height || 0;
+ /** Start intersections at nav height + 2rem padding. */
+ const top = navBarHeight + mobileTocHeight + 32;
+ /** End intersections 1.5rem later. */
+ const bottom = top + 24;
+ const height = document.documentElement.clientHeight;
+ return `-${top}px 0% ${bottom - height}px`;
+ }
}
customElements.define('starlight-toc', StarlightTOC);
diff --git a/packages/starlight/index.ts b/packages/starlight/index.ts
index 2198f13fc17..50e37d046c0 100644
--- a/packages/starlight/index.ts
+++ b/packages/starlight/index.ts
@@ -68,7 +68,7 @@ export default function StarlightIntegration(opts: StarlightUserConfig): AstroIn
const cwd = dirname(fileURLToPath(import.meta.url));
const relativeDir = relative(cwd, targetDir);
return new Promise((resolve) => {
- spawn('npx', ['-y', 'pagefind', '--source', relativeDir], {
+ spawn('npx', ['-y', 'pagefind', '--site', relativeDir], {
stdio: 'inherit',
shell: true,
cwd,
diff --git a/packages/starlight/layout/Page.astro b/packages/starlight/layout/Page.astro
index 7b01c441c41..0999122dffc 100644
--- a/packages/starlight/layout/Page.astro
+++ b/packages/starlight/layout/Page.astro
@@ -45,6 +45,8 @@ const tocConfig = !hasSidebar
: config.tableOfContents;
const hasToC = Boolean(tocConfig);
const hasHero = Boolean(entry.data.hero);
+const pagefindEnabled =
+ entry.slug !== '404' && !entry.slug.endsWith('/404') && entry.data.pagefind !== false;
---
}
+
{/* TODO: Revisit how this logic flows. */}
{entry.data.banner &&
+
+ Benvenuti Product Hunters 👋
+ Siamo live ora!
+
+
hero:
title: Fai brillare la tua documentazione con Starlight
tagline: Tutto quello di cui hai bisogno per creare documentazione stellare. Veloce, accessibile e facile da usare.
diff --git a/docs/src/content/docs/it/manual-setup.mdx b/docs/src/content/docs/it/manual-setup.mdx
new file mode 100644
index 00000000000..8791ce0df6b
--- /dev/null
+++ b/docs/src/content/docs/it/manual-setup.mdx
@@ -0,0 +1,128 @@
+---
+title: Configurazione manuale
+description: Scopri come configurare manualmente Starlight per aggiungerlo a un progetto Astro esistente.
+---
+
+import { Tabs, TabItem } from '@astrojs/starlight/components';
+
+Il modo più rapido per creare un nuovo sito Starlight è utilizzare `create astro` come mostrato nella [guida introduttiva](/it/getting-started/#creating-a-new-project).
+Se desideri aggiungere Starlight a un progetto Astro esistente, questa guida spiegherà come.
+
+## Configura Starlight
+
+Per seguire questa guida, avrai bisogno di un progetto Astro esistente.
+
+### Aggiungi l'integrazione Starlight
+
+Starlight è un'[integrazione Astro](https://docs.astro.build/it/guides/integrations-guide/). Aggiungilo al tuo sito eseguendo il comando `astro add` nella directory principale del tuo progetto:
+
+string | BadgeConfig
+
+Aggiungi un badge alla pagina nella barra laterale quando viene visualizzata in un gruppo di collegamenti generato automaticamente.
+Quando si utilizza una stringa, il badge verrà visualizzato con un colore in risalto predefinito.
+Facoltativamente, passa un [oggetto `BadgeConfig`](/it/reference/configuration/#badgeconfig) con i campi `text` e `variant` per personalizzare il badge.
+
+```md
+---
+title: Pagina con un badge
+sidebar:
+ # Utilizza la variante predefinita corrispondente al colore principale del tuo sito
+ badge: nuovo
+---
+```
+
+```md
+---
+title: Pagina con un badge
+sidebar:
+ badge:
+ text: Sperimentale
+ variant: caution
+---
+```
diff --git a/docs/src/content/docs/it/showcase.mdx b/docs/src/content/docs/it/showcase.mdx
new file mode 100644
index 00000000000..a3351f3f87c
--- /dev/null
+++ b/docs/src/content/docs/it/showcase.mdx
@@ -0,0 +1,53 @@
+---
+title: Vetrina Starlight
+description: Scopri i siti realizzati con Starlight e gli strumenti della community che estendono Starlight!
+---
+
+:::tip[Aggiungi il tuo!]
+Hai creato un sito Starlight o uno strumento per Starlight?
+Apri una PR aggiungendo un link a questa pagina!
+:::
+
+## Sites
+
+import ShowcaseSites from '../../../components/showcase-sites.astro';
+
+Starlight è già utilizzato nella produzione. Questi sono alcuni dei siti presenti sul web:
+
+` across lines to avoid overflow
+
+- [#642](https://github.com/withastro/starlight/pull/642) [`e623d92`](https://github.com/withastro/starlight/commit/e623d92c2fddc0ff5fe83d2554266885d683a906) Thanks [@fk](https://github.com/fk)! - Don't hard-code nav height in table of contents highlighting script
+
+- [#676](https://github.com/withastro/starlight/pull/676) [`6419006`](https://github.com/withastro/starlight/commit/641900615aa9a9a128d6934e65a57ba89e503cfd) Thanks [@vedmalex](https://github.com/vedmalex)! - Upgrade and pin Pagefind to latest beta release.
+
+- [#647](https://github.com/withastro/starlight/pull/647) [`ea57726`](https://github.com/withastro/starlight/commit/ea5772655274a3900310cb700836fdd2f6dba7cd) Thanks [@bgmort](https://github.com/bgmort)! - Add frontmatter option to exclude a page from Pagefind search results
+
## 0.9.0
### Minor Changes
diff --git a/packages/starlight/__tests__/basics/toc.test.ts b/packages/starlight/__tests__/basics/toc.test.ts
new file mode 100644
index 00000000000..51745d7b81c
--- /dev/null
+++ b/packages/starlight/__tests__/basics/toc.test.ts
@@ -0,0 +1,141 @@
+import { expect, test } from 'vitest';
+import { generateToC } from '../../components/TableOfContents/generateToC';
+
+const defaultOpts = { minHeadingLevel: 2, maxHeadingLevel: 3, title: 'Overview' };
+
+test('generates an overview entry with no headings available', () => {
+ const toc = generateToC([], defaultOpts);
+ expect(toc).toHaveLength(1);
+ expect(toc[0]).toEqual({ children: [], depth: 2, slug: '_top', text: 'Overview' });
+});
+
+test('generates entries from heading array', () => {
+ const toc = generateToC([{ text: 'One', slug: 'one', depth: 2 }], defaultOpts);
+ expect(toc).toHaveLength(2);
+ expect(toc[0]).toEqual({ children: [], depth: 2, slug: '_top', text: 'Overview' });
+ expect(toc[1]).toEqual({ children: [], depth: 2, slug: 'one', text: 'One' });
+});
+
+test('nests lower-level headings in children array h2 => h3', () => {
+ const toc = generateToC(
+ [
+ { text: 'One', slug: 'one', depth: 2 },
+ { text: 'Two', slug: 'two', depth: 3 },
+ ],
+ defaultOpts
+ );
+ expect(toc).toHaveLength(2);
+ expect(toc[0]).toEqual({ children: [], depth: 2, slug: '_top', text: 'Overview' });
+ expect(toc[1]).toEqual({
+ children: [{ children: [], depth: 3, slug: 'two', text: 'Two' }],
+ depth: 2,
+ slug: 'one',
+ text: 'One',
+ });
+});
+
+test('nests lower-level headings in children array h2 => h4', () => {
+ const toc = generateToC(
+ [
+ { text: 'One', slug: 'one', depth: 2 },
+ { text: 'Two', slug: 'two', depth: 4 },
+ ],
+ { ...defaultOpts, maxHeadingLevel: 6 }
+ );
+ expect(toc).toHaveLength(2);
+ expect(toc[0]).toEqual({ children: [], depth: 2, slug: '_top', text: 'Overview' });
+ expect(toc[1]).toEqual({
+ children: [{ children: [], depth: 4, slug: 'two', text: 'Two' }],
+ depth: 2,
+ slug: 'one',
+ text: 'One',
+ });
+});
+
+test('nests lower-level headings deeply h2 => h4 => h6', () => {
+ const toc = generateToC(
+ [
+ { text: 'One', slug: 'one', depth: 2 },
+ { text: 'Two', slug: 'two', depth: 4 },
+ { text: 'Three', slug: 'three', depth: 6 },
+ ],
+ { ...defaultOpts, maxHeadingLevel: 6 }
+ );
+ expect(toc).toHaveLength(2);
+ expect(toc[0]).toEqual({ children: [], depth: 2, slug: '_top', text: 'Overview' });
+ expect(toc[1]).toMatchInlineSnapshot(`
+ {
+ "children": [
+ {
+ "children": [
+ {
+ "children": [],
+ "depth": 6,
+ "slug": "three",
+ "text": "Three",
+ },
+ ],
+ "depth": 4,
+ "slug": "two",
+ "text": "Two",
+ },
+ ],
+ "depth": 2,
+ "slug": "one",
+ "text": "One",
+ }
+ `);
+});
+
+test('adds higher-level headings sequentially h6 => h4 => h2', () => {
+ const toc = generateToC(
+ [
+ { text: 'One', slug: 'one', depth: 6 },
+ { text: 'Two', slug: 'two', depth: 4 },
+ { text: 'Three', slug: 'three', depth: 2 },
+ ],
+ { ...defaultOpts, maxHeadingLevel: 6 }
+ );
+ expect(toc).toHaveLength(2);
+ expect(toc).toMatchInlineSnapshot(`
+ [
+ {
+ "children": [
+ {
+ "children": [],
+ "depth": 6,
+ "slug": "one",
+ "text": "One",
+ },
+ {
+ "children": [],
+ "depth": 4,
+ "slug": "two",
+ "text": "Two",
+ },
+ ],
+ "depth": 2,
+ "slug": "_top",
+ "text": "Overview",
+ },
+ {
+ "children": [],
+ "depth": 2,
+ "slug": "three",
+ "text": "Three",
+ },
+ ]
+ `);
+});
+
+test('filters out higher-level headings than minHeadingLevel', () => {
+ const toc = generateToC([{ text: 'One', slug: 'one', depth: 1 }], defaultOpts);
+ expect(toc).toHaveLength(1);
+ expect(toc[0]).toEqual({ children: [], depth: 2, slug: '_top', text: 'Overview' });
+});
+
+test('filters out lower-level headings than maxHeadingLevel', () => {
+ const toc = generateToC([{ text: 'One', slug: 'one', depth: 4 }], defaultOpts);
+ expect(toc).toHaveLength(1);
+ expect(toc[0]).toEqual({ children: [], depth: 2, slug: '_top', text: 'Overview' });
+});
diff --git a/packages/starlight/components/Search.astro b/packages/starlight/components/Search.astro
index be8997a8ad7..89c2bed0e9b 100644
--- a/packages/starlight/components/Search.astro
+++ b/packages/starlight/components/Search.astro
@@ -58,31 +58,37 @@ const pagefindTranslations = {
const dialog = this.querySelector('dialog')!;
const dialogFrame = this.querySelector('.dialog-frame')!;
- /** Close the modal if a user clicks outside of the modal. */
- const onWindowClick = (event: MouseEvent) => {
+ /** Close the modal if a user clicks on a link or outside of the modal. */
+ const onClick = (event: MouseEvent) => {
+ const isLink = 'href' in (event.target || {});
if (
- document.body.contains(event.target as Node) &&
- !dialogFrame.contains(event.target as Node)
- )
+ isLink ||
+ (document.body.contains(event.target as Node) &&
+ !dialogFrame.contains(event.target as Node))
+ ) {
closeModal();
+ }
};
const openModal = (event?: MouseEvent) => {
dialog.showModal();
+ document.body.toggleAttribute('data-search-modal-open', true);
this.querySelector('input')?.focus();
event?.stopPropagation();
- window.addEventListener('click', onWindowClick);
+ window.addEventListener('click', onClick);
};
- const closeModal = () => {
- dialog.close();
- window.removeEventListener('click', onWindowClick);
- };
+ const closeModal = () => dialog.close();
openBtn.addEventListener('click', openModal);
openBtn.disabled = false;
closeBtn.addEventListener('click', closeModal);
+ dialog.addEventListener('close', () => {
+ document.body.toggleAttribute('data-search-modal-open', false);
+ window.removeEventListener('click', onClick);
+ });
+
// Listen for `/` and `cmd + k` keyboard shortcuts.
window.addEventListener('keydown', (e) => {
const isInput =
@@ -110,9 +116,10 @@ const pagefindTranslations = {
new PagefindUI({
element: '#starlight__search',
baseUrl: import.meta.env.BASE_URL,
- bundlePath: import.meta.env.BASE_URL.replace(/\/$/, '') + '/_pagefind/',
+ bundlePath: import.meta.env.BASE_URL.replace(/\/$/, '') + '/pagefind/',
showImages: false,
translations,
+ showSubResults: true,
});
});
});
@@ -179,7 +186,7 @@ const pagefindTranslations = {
.dialog-frame {
flex-direction: column;
gap: 1rem;
- padding: 1.5rem;
+ padding: 1rem;
}
button[data-close-modal] {
@@ -198,6 +205,7 @@ const pagefindTranslations = {
#starlight__search {
--pagefind-ui-primary: var(--sl-color-accent-light);
--pagefind-ui-text: var(--sl-color-gray-2);
+ --pagefind-ui-font: var(--__sl-font);
--pagefind-ui-background: var(--sl-color-black);
--pagefind-ui-border: var(--sl-color-gray-5);
--pagefind-ui-border-width: 1px;
@@ -218,10 +226,35 @@ const pagefindTranslations = {
min-height: 15rem;
max-height: calc(100% - 8rem);
}
+
+ .dialog-frame {
+ padding: 1.5rem;
+ }
}
diff --git a/packages/starlight/components/TableOfContents/MobileTableOfContents.astro b/packages/starlight/components/TableOfContents/MobileTableOfContents.astro
index b4fc200021a..34fe1d5e19a 100644
--- a/packages/starlight/components/TableOfContents/MobileTableOfContents.astro
+++ b/packages/starlight/components/TableOfContents/MobileTableOfContents.astro
@@ -122,7 +122,7 @@ const t = useTranslations(locale);
}
constructor() {
- super({ smallViewport: true });
+ super();
const details = this.querySelector('details');
if (!details) return;
const closeToC = () => {
diff --git a/packages/starlight/components/TableOfContents/generateToC.ts b/packages/starlight/components/TableOfContents/generateToC.ts
index 30d1005fe08..73c08e3d472 100644
--- a/packages/starlight/components/TableOfContents/generateToC.ts
+++ b/packages/starlight/components/TableOfContents/generateToC.ts
@@ -4,52 +4,29 @@ export interface TocItem extends MarkdownHeading {
children: TocItem[];
}
-function diveChildren(item: TocItem, depth: number): TocItem[] {
- if (depth === 1) {
- return item.children;
- } else if (item.children.length > 0) {
- return diveChildren(item.children.at(-1)!, depth - 1);
- } else {
- return [];
- }
-}
-
interface TocOpts {
minHeadingLevel: number;
maxHeadingLevel: number;
- title?: string;
+ title: string;
}
+/** Convert the flat headings array generated by Astro into a nested tree structure. */
export function generateToC(
headings: MarkdownHeading[],
- { minHeadingLevel, maxHeadingLevel, title = 'Overview' }: TocOpts
+ { minHeadingLevel, maxHeadingLevel, title }: TocOpts
) {
- const overview = { depth: 2, slug: '_top', text: title };
- headings = [
- overview,
- ...headings.filter(({ depth }) => depth >= minHeadingLevel && depth <= maxHeadingLevel),
- ];
- const toc: Array = [];
+ headings = headings.filter(({ depth }) => depth >= minHeadingLevel && depth <= maxHeadingLevel);
+ const toc: Array = [{ depth: 2, slug: '_top', text: title, children: [] }];
+ for (const heading of headings) injectChild(toc, { ...heading, children: [] });
+ return toc;
+}
- for (const heading of headings) {
- if (toc.length === 0) {
- toc.push({ ...heading, children: [] });
- } else {
- const lastItemInToc = toc.at(-1)!;
- if (heading.depth < lastItemInToc.depth) {
- throw new Error(`Orphan heading found: ${heading.text}.`);
- }
- if (heading.depth === lastItemInToc.depth) {
- // same depth
- toc.push({ ...heading, children: [] });
- } else {
- // higher depth
- // push into children, or children's children alike
- const gap = heading.depth - lastItemInToc.depth;
- const target = diveChildren(lastItemInToc, gap);
- target.push({ ...heading, children: [] });
- }
- }
+/** Inject a ToC entry as deep in the tree as its `depth` property requires. */
+function injectChild(items: TocItem[], item: TocItem): void {
+ const lastItem = items.at(-1);
+ if (!lastItem || lastItem.depth >= item.depth) {
+ items.push(item);
+ } else {
+ return injectChild(lastItem.children, item);
}
- return toc;
}
diff --git a/packages/starlight/components/TableOfContents/starlight-toc.ts b/packages/starlight/components/TableOfContents/starlight-toc.ts
index 1d1f4cd0231..4283f36168d 100644
--- a/packages/starlight/components/TableOfContents/starlight-toc.ts
+++ b/packages/starlight/components/TableOfContents/starlight-toc.ts
@@ -10,7 +10,7 @@ export class StarlightTOC extends HTMLElement {
this._current = link;
}
- constructor({ smallViewport = false } = {}) {
+ constructor() {
super();
/** All the links in the table of contents. */
@@ -68,19 +68,13 @@ export class StarlightTOC extends HTMLElement {
// Also observe direct children of `.content` to include elements before
// the first heading.
const toObserve = document.querySelectorAll('main [id], main [id] ~ *, main .content > *');
- /** Start intersections at nav height + 2rem padding. */
- const top = (smallViewport ? 104 : 64) + 32;
- /** End intersections 1.5rem later. */
- const bottom = top + 24;
let observer: IntersectionObserver | undefined;
- function observe() {
+ const observe = () => {
if (observer) observer.disconnect();
- const height = document.documentElement.clientHeight;
- const rootMargin = `-${top}px 0% ${bottom - height}px`;
- observer = new IntersectionObserver(setCurrent, { rootMargin });
+ observer = new IntersectionObserver(setCurrent, { rootMargin: this.getRootMargin() });
toObserve.forEach((h) => observer!.observe(h));
- }
+ };
observe();
const onIdle = window.requestIdleCallback || ((cb) => setTimeout(cb, 1));
@@ -92,6 +86,18 @@ export class StarlightTOC extends HTMLElement {
timeout = setTimeout(() => onIdle(observe), 200);
});
}
+
+ private getRootMargin(): `-${number}px 0% ${number}px` {
+ const navBarHeight = document.querySelector('header')?.getBoundingClientRect().height || 0;
+ // `` only exists in mobile ToC, so will fall back to 0 in large viewport component.
+ const mobileTocHeight = this.querySelector('summary')?.getBoundingClientRect().height || 0;
+ /** Start intersections at nav height + 2rem padding. */
+ const top = navBarHeight + mobileTocHeight + 32;
+ /** End intersections 1.5rem later. */
+ const bottom = top + 24;
+ const height = document.documentElement.clientHeight;
+ return `-${top}px 0% ${bottom - height}px`;
+ }
}
customElements.define('starlight-toc', StarlightTOC);
diff --git a/packages/starlight/index.ts b/packages/starlight/index.ts
index 2198f13fc17..50e37d046c0 100644
--- a/packages/starlight/index.ts
+++ b/packages/starlight/index.ts
@@ -68,7 +68,7 @@ export default function StarlightIntegration(opts: StarlightUserConfig): AstroIn
const cwd = dirname(fileURLToPath(import.meta.url));
const relativeDir = relative(cwd, targetDir);
return new Promise((resolve) => {
- spawn('npx', ['-y', 'pagefind', '--source', relativeDir], {
+ spawn('npx', ['-y', 'pagefind', '--site', relativeDir], {
stdio: 'inherit',
shell: true,
cwd,
diff --git a/packages/starlight/layout/Page.astro b/packages/starlight/layout/Page.astro
index 7b01c441c41..0999122dffc 100644
--- a/packages/starlight/layout/Page.astro
+++ b/packages/starlight/layout/Page.astro
@@ -45,6 +45,8 @@ const tocConfig = !hasSidebar
: config.tableOfContents;
const hasToC = Boolean(tocConfig);
const hasHero = Boolean(entry.data.hero);
+const pagefindEnabled =
+ entry.slug !== '404' && !entry.slug.endsWith('/404') && entry.data.pagefind !== false;
---
}
+
{/* TODO: Revisit how this logic flows. */}
{entry.data.banner &&