From 0deffba26f83d32c24bf232d31f791c9fe1c5235 Mon Sep 17 00:00:00 2001 From: casungo Date: Fri, 9 Feb 2024 09:44:26 +0100 Subject: i18n(it): Modified frontmatter.md and overrides.md (#1457) Co-authored-by: HiDeoo <494699+HiDeoo@users.noreply.github.com> --- docs/src/content/docs/it/reference/frontmatter.md | 181 ++++++++++++++++++---- docs/src/content/docs/it/reference/overrides.md | 43 +++-- 2 files changed, 177 insertions(+), 47 deletions(-) diff --git a/docs/src/content/docs/it/reference/frontmatter.md b/docs/src/content/docs/it/reference/frontmatter.md index 6115ded3..ba94e441 100644 --- a/docs/src/content/docs/it/reference/frontmatter.md +++ b/docs/src/content/docs/it/reference/frontmatter.md @@ -5,8 +5,9 @@ description: Una panoramica sui campi predefiniti del frontmatter Starlight. Puoi personalizzare pagine Markdown e MDX in Starlight definendo i valori nel frontmatter. Per esempio, una pagina potrebbe definire `title` e `description` : -```md +```md {3-4} --- +# src/content/docs/example.md title: A proposito del progetto description: Scopri di più sul progetto a cui sto lavorando. --- @@ -18,30 +19,37 @@ Benvenuto alla pagina "a proposito del progetto"! ### `title` (obbligatorio) -**type:** `string` +**tipo:** `string` Devi fornire un titolo ad ogni pagina. Questo sarà usato in testa alla pagina, nelle finestre del browser e nei metadati della pagina. ### `description` -**type:** `string` +**tipo:** `string` La descrizione è utilizzata nei metadati e sarà utilizzata dai motori di ricerca e nelle anteprime nei social. +### `slug` + +**tipo:**: `string` + +Sovrascrivi lo slug della pagina. Vedi [“Definizione degli slug personalizzati”](https://docs.astro.build/it/guides/content-collections/#defining-custom-slugs) nella documentazione di Astro per ulteriori dettagli. + ### `editUrl` -**type:** `string | boolean` +**tipo:** `string | boolean` Sovrascrive la [configurazione globale `editLink`](/it/reference/configuration/#editlink). Metti a `false` per disabilitare "Modifica la pagina" per quella pagina specifica oppure fornisci un link alternativo. ### `head` -**type:** [`HeadConfig[]`](/it/reference/configuration/#headconfig) +**tipo:** [`HeadConfig[]`](/it/reference/configuration/#headconfig) Puoi aggiungere tag aggiuntivi nell'`` della pagina utilizzando la chiave `head` nel frontmatter. Questo significa che puoi aggiungere stili personalizzati, metadati o altri tag in una pagina. Il funzionamento è simile [all'opzione globale `head`](/it/reference/configuration/#head). ```md --- +# src/content/docs/example.md title: Chi siamo head: # Utilizza un personalizzato @@ -52,13 +60,14 @@ head: ### `tableOfContents` -**type:** `false | { minHeadingLevel?: number; maxHeadingLevel?: number; }` +**tipo:** `false | { minHeadingLevel?: number; maxHeadingLevel?: number; }` 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 --- +# src/content/docs/example.md title: Pagina con solo H2 nella tabella dei contenuti della pagina tableOfContents: minHeadingLevel: 2 @@ -68,6 +77,7 @@ tableOfContents: ```md --- +# src/content/docs/example.md title: Pagina senza tabella dei contenuti della pagina tableOfContents: false --- @@ -75,8 +85,8 @@ tableOfContents: false ### `template` -**type:** `'doc' | 'splash'` -**default:** `'doc'` +**tipo:** `'doc' | 'splash'` +**predefinito:** `'doc'` Definisce il layout per la pagina. Le pagine utilizzano `'doc'` come predefinita. @@ -84,7 +94,7 @@ Se valorizzato a `'splash'` viene utilizzato un layout senza barre laterali otti ### `hero` -**type:** [`HeroConfig`](#heroconfig) +**tipo:** [`HeroConfig`](#heroconfig) Aggiunge un componente hero all'inizio della pagina. Funziona bene con `template: splash`. @@ -92,6 +102,7 @@ Per esempio, questa configurazione illustra comuni opzioni, incluso il caricamen ```md --- +# src/content/docs/example.md title: La mia pagina principale template: splash hero: @@ -111,20 +122,45 @@ hero: --- ``` +Puoi mostrare diverse versioni dell'immagine in base alla modalità chiara o scura. + +```md +--- +# src/content/docs/example.md +hero: + image: + alt: Un logo brillante e luminoso + dark: ~/assets/logo-dark.png + light: ~/assets/logo-light.png +--- +``` + #### `HeroConfig` ```ts interface HeroConfig { title?: string; tagline?: string; - image?: { - alt?: string; - // Percorso relativo ad un’immagine dentro il tuo progetto. - file?: string; - // HTML non elaborato da utilizzare al posto dell'immagine. - // Potrebbe essere un tag personalizzato `<img>` o `<svg>` in linea. - html?: string; - }; + image?: + | { + // Percorso relativo a un'immagine nella tua repository. + file: string; + // Testo alternativo per rendere l'immagine accessibile alla tecnologia assistiva + alt?: string; + } + | { + // Percorso relativo a un'immagine nella tua repository da utilizzare per la modalità scura. + dark: string; + // Percorso relativo a un'immagine nella tua repository da utilizzare per la modalità chiara. + light: string; + // Testo alternativo per rendere l'immagine accessibile alla tecnologia assistiva + alt?: string; + } + | { + // HTML grezzo da utilizzare nello slot dell'immagine. + // Potrebbe essere un tag `<img>` personalizzato o `<svg>` inline. + html: string; + }; actions?: Array<{ text: string; link: string; @@ -136,7 +172,7 @@ interface HeroConfig { ### `banner` -**type:** `{ content: string }` +**tipo:** `{ content: string }` Visualizza un banner di annuncio nella parte superiore di questa pagina. @@ -145,6 +181,7 @@ Ad esempio, questa pagina visualizza un banner che include un collegamento a `ex ```md --- +# src/content/docs/example.md title: Pagina con un banner banner: content: | @@ -155,12 +192,13 @@ banner: ### `lastUpdated` -**type:** `Date | boolean` +**tipo:** `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 --- +# src/content/docs/example.md title: Pagina con una data di ultimo aggiornamento personalizzata lastUpdated: 2022-08-09 --- @@ -168,12 +206,13 @@ lastUpdated: 2022-08-09 ### `prev` -**type:** `boolean | string | { link?: string; label?: string }` +**tipo:** `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 --- +# src/content/docs/example.md # Nascondi il collegamento alla pagina precedente prev: false --- @@ -181,6 +220,7 @@ prev: false ```md --- +# src/content/docs/example.md # Sostituisci il testo del collegamento della pagina precedente prev: Continua il tutorial --- @@ -188,6 +228,7 @@ prev: Continua il tutorial ```md --- +# src/content/docs/example.md # Sostituisci sia il collegamento che il testo della pagina precedente prev: link: /pagina-non-correlata/ @@ -197,12 +238,13 @@ prev: ### `next` -**type:** `boolean | string | { link?: string; label?: string }` +**tipo:** `boolean | string | { link?: string; label?: string }` Uguale a [`prev`](#prev) ma per il collegamento alla pagina successiva. ```md --- +# src/content/docs/example.md # Nascondi il collegamento alla pagina successiva next: false --- @@ -210,13 +252,14 @@ next: false ### `pagefind` -**type:** `boolean` -**default:** `true` +**tipo:** `boolean` +**predefinito:** `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 --- +# src/content/docs/example.md # Nascondi questa pagina dai risultati di ricerca pagefind: false --- @@ -224,7 +267,7 @@ pagefind: false ### `sidebar` -**type:** [`SidebarConfig`](#sidebarconfig) +**tipo:** [`SidebarConfig`](#sidebarconfig) 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. @@ -242,13 +285,14 @@ interface SidebarConfig { #### `label` -**type:** `string` -**default:** the page [`title`](#title-obbligatorio) +**tipo:** `string` +**predefinito:** la pagina [`title`](#title-obbligatorio) Imposta l'etichetta per questa pagina nella barra laterale quando viene visualizzata in un gruppo di collegamenti generato automaticamente. ```md --- +# src/content/docs/example.md title: Informazioni su questo progetto sidebar: label: Informazioni @@ -257,13 +301,14 @@ sidebar: #### `order` -**type:** `number` +**tipo:** `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 --- +# src/content/docs/example.md title: Pagina da visualizzare per prima sidebar: order: 1 @@ -272,22 +317,23 @@ sidebar: #### `hidden` -**type:** `boolean` -**default:** `false` +**tipo:** `boolean` +**predefinito:** `false` Impedisce che questa pagina venga inclusa in un gruppo della barra laterale generato automaticamente. ```md --- +# src/content/docs/example.md title: Pagina da nascondere dalla barra laterale generata automaticamente sidebar: - hidden: vero + hidden: true --- ``` #### `badge` -**type:** <code>string | <a href="/it/reference/configuration/#badgeconfig">BadgeConfig</a></code> +**tipo:** <code>string | <a href="/it/reference/configuration/#badgeconfig">BadgeConfig</a></code> 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. @@ -295,6 +341,7 @@ Facoltativamente, passa un [oggetto `BadgeConfig`](/it/reference/configuration/# ```md --- +# src/content/docs/example.md title: Pagina con un badge sidebar: # Utilizza la variante predefinita corrispondente al colore principale del tuo sito @@ -304,6 +351,7 @@ sidebar: ```md --- +# src/content/docs/example.md title: Pagina con un badge sidebar: badge: @@ -314,12 +362,13 @@ sidebar: #### `attrs` -**type:** `Record<string, string | number | boolean | undefined>` +**tipo:** `Record<string, string | number | boolean | undefined>` Attributi HTML da aggiungere al collegamento della pagina nella barra laterale quando viene visualizzato in un gruppo di collegamenti generato automaticamente. ```md --- +# src/content/docs/example.md title: Pagina che si aprirà in una nuova scheda sidebar: # Apre la pagina in una nuova scheda @@ -327,3 +376,71 @@ sidebar: target: _blank --- ``` + +## Personalizza lo schema del frontmatter + +Lo schema del frontmatter per la raccolta di contenuti `docs` di Starlight è configurato in `src/content/config.ts` utilizzando l'helper `docsSchema()`: + +```ts {3,6} +// src/content/config.ts +import { defineCollection } from 'astro:content'; +import { docsSchema } from '@astrojs/starlight/schema'; + +export const collections = { + docs: defineCollection({ schema: docsSchema() }), +}; +``` + +Per saperne di più sugli schemi di raccolta dei contenuti, consulta [“Definizione di uno schema di raccolta”](https://docs.astro.build/it/guides/content-collections/#defining-a-collection-schema) nella documentazione di Astro. + +`docsSchema()` accetta le seguenti opzioni: + +### `extend` + +**tipo:** Schema Zod o funzione che restituisce uno schema Zod +**predefinito:** `z.object({})` + +Estendi lo schema di Starlight con campi aggiuntivi impostando `extend` nelle opzioni di `docsSchema()`. +Il valore dovrebbe essere uno [schema Zod](https://docs.astro.build/it/guides/content-collections/#defining-datatypes-with-zod). + +Nell'esempio seguente, forniamo un tipo più restrittivo per `description` per renderlo obbligatorio e aggiungiamo un nuovo campo opzionale `category`: + +```ts {8-13} +// src/content/config.ts +import { defineCollection, z } from 'astro:content'; +import { docsSchema } from '@astrojs/starlight/schema'; + +export const collections = { + docs: defineCollection({ + schema: docsSchema({ + extend: z.object({ + // Rendi un campo built-in obbligatorio anziché opzionale. + description: z.string(), + // Aggiungi un nuovo campo allo schema. + category: z.enum(['tutorial', 'guide', 'reference']).optional(), + }), + }), + }), +}; +``` + +Per sfruttare l'[helper `image()` di Astro,](https://docs.astro.build/it/guides/images/#images-in-content-collections), utilizza una funzione che restituisce l'estensione dello schema: + +```ts {8-13} +// src/content/config.ts +import { defineCollection, z } from 'astro:content'; +import { docsSchema } from '@astrojs/starlight/schema'; + +export const collections = { + docs: defineCollection({ + schema: docsSchema({ + extend: ({ image }) => { + return z.object({ + // Aggiungi un campo che deve risolvere in un'immagine locale. + cover: image(), + }); + }, + }), + }), +}; +``` diff --git a/docs/src/content/docs/it/reference/overrides.md b/docs/src/content/docs/it/reference/overrides.md index 3f17f406..43b90f09 100644 --- a/docs/src/content/docs/it/reference/overrides.md +++ b/docs/src/content/docs/it/reference/overrides.md @@ -18,6 +18,7 @@ Per aggiungere i tipi di dato ai tuoi componenti personalizzati, importa il tipo ```astro --- +// src/components/Custom.astro import type { Props } from '@astrojs/starlight/props'; const { hasSidebar } = Astro.props; @@ -33,44 +34,44 @@ Starlight trasmetterà le seguenti proprietà ai tuoi componenti personalizzati. #### `dir` -**Tipo:** `'ltr' | 'rtl'` +**tipo:** `'ltr' | 'rtl'` Direzione di scrittura della pagina. #### `lang` -**Tipo:** `string` +**tipo:** `string` Tag di lingua BCP-47 per le impostazioni internazionali di questa pagina, ad es. `en`, `zh-CN` o `pt-BR`. #### `locale` -**Tipo:** `string | undefined` +**tipo:** `string | undefined` Il percorso di base in cui viene servita una lingua. `undefined` per gli slug della lingua di base. #### `slug` -**Tipo:** `string` +**tipo:** `string` Lo slug per questa pagina generato dal nome del file di contenuto. #### `id` -**Tipo:** `string` +**tipo:** `string` L'ID univoco per questa pagina in base al nome del file di contenuto. #### `isFallback` -**Tipo:** `true | undefined` +**tipo:** `true | undefined` `true` se questa pagina non è tradotta nella lingua corrente e utilizza contenuti di riserva dalle impostazioni di lingua predefinite. Utilizzato solo in siti multilingue. #### `entryMeta` -**Tipo:** `{ dir: 'ltr' | 'rtl'; lang: string }` +**tipo:** `{ dir: 'ltr' | 'rtl'; lang: string }` Metadati di lingua per il contenuto della pagina. Può essere diverso dai valori di lingua di livello superiore quando una pagina utilizza contenuti di fallback. @@ -93,47 +94,53 @@ Scopri di più sulla forma di questo oggetto nel riferimento [Tipo di voce della #### `sidebar` -**Tipo:** `SidebarEntry[]` +**tipo:** `SidebarEntry[]` Voci della barra laterale di navigazione del sito per questa pagina. #### `hasSidebar` -**Tipo:** `boolean` +**tipo:** `boolean` Se la barra laterale deve essere visualizzata o meno in questa pagina. #### `pagination` -**Tipo:** `{ prev?: Link; next?: Link }` +**tipo:** `{ prev?: Link; next?: Link }` Collegamenti alla pagina precedente e successiva nella barra laterale, se abilitata. #### `toc` -**Tipo:** `{ minHeadingLevel: number; maxHeadingLevel: number; items: TocItem[] } | undefined` +**tipo:** `{ minHeadingLevel: number; maxHeadingLevel: number; items: TocItem[] } | undefined` Sommario per questa pagina se abilitato. #### `headings` -**Tipo:** `{ depth: number; slug: string; text: string }[]` +**tipo:** `{ depth: number; slug: string; text: string }[]` Matrice di tutte le intestazioni Markdown estratte dalla pagina corrente. Utilizza invece [`toc`](#toc) se vuoi creare un sommario che rispetti le opzioni di configurazione di Starlight. #### `lastUpdated` -**Tipo:** `Date | undefined` +**tipo:** `Date | undefined` Oggetto JavaScript `Date` che rappresenta l'ultimo aggiornamento di questa pagina, se abilitato. #### `editUrl` -**Tipo:** `URL | undefined` +**tipo:** `URL | undefined` Oggetto `URL` per l'indirizzo in cui questa pagina può essere modificata se abilitata. +#### `labels` + +**tipo:** `Record<string, string>` + +Un oggetto contenente stringhe dell'interfaccia utente localizzate per la pagina corrente. Consulta la guida [“Tradurre l'interfaccia di Starlight”](/it/guides/i18n/#tradurre-linterfaccia-starlight) per un elenco di tutte le chiavi disponibili. + --- ## Componenti @@ -141,7 +148,7 @@ Oggetto `URL` per l'indirizzo in cui questa pagina può essere modificata se abi ### Head Questi componenti vengono renderizzati all'interno dell'elemento `<head>` di ciascuna pagina. -Dovrebbero includere solo [elementi consentiti all'interno di `<head>`](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/head#see_also). +Dovrebbero includere solo [elementi consentiti all'interno di `<head>`](https://developer.mozilla.org/it/docs/Web/HTML/Element/head#see_also). #### `Head` @@ -227,6 +234,10 @@ L'implementazione predefinita include la logica per il rendering dei loghi defin Componente utilizzato per eseguire il rendering dell'interfaccia utente di ricerca di Starlight. L'implementazione predefinita include il pulsante nell'intestazione e il codice per visualizzare una schermata di ricerca quando viene cliccata e caricare l'[interfaccia utente di Pagefind](https://pagefind.app/). +Quando [`pagefind`](/it/reference/configuration/#pagefind) è disabilitato, il componente di ricerca predefinito non verrà renderizzato. +Tuttavia, se si sovrascrive `Search`, il componente personalizzato verrà sempre renderizzato anche se l'opzione di configurazione `pagefind` è `false`. +Ciò consente di aggiungere un'interfaccia utente per i provider di ricerca alternativi quando si disabilita Pagefind. + #### `SocialIcons` **Componente standard:** [`SocialIcons.astro`](https://github.com/withastro/starlight/blob/main/packages/starlight/components/SocialIcons.astro) @@ -342,6 +353,8 @@ L'implementazione predefinita mostra un titolo di grandi dimensioni, uno slogan Componente renderizzato attorno al contenuto principale di ogni pagina. L'implementazione predefinita imposta gli stili di base da applicare al contenuto Markdown. +Anche gli stili del contenuto Markdown sono esposti in `@astrojs/starlight/style/markdown.css` e limitati alla classe CSS `.sl-markdown-content`. + --- ### Piè di pagina -- cgit