diff --git a/docs/src/content/docs/fr/guides/overriding-components.md b/docs/src/content/docs/fr/guides/overriding-components.md new file mode 100644 index 0000000000..23dc7df80e --- /dev/null +++ b/docs/src/content/docs/fr/guides/overriding-components.md @@ -0,0 +1,133 @@ +--- +title: Redéfinition de composants +description: Apprenez à redéfinir les composants intégrés à Starlight pour ajouter des éléments personnalisés à l’interface utilisateur de votre site de documentation. +sidebar: + badge: Nouveau +--- + +L'interface utilisateur et les options de configuration par défaut de Starlight sont conçues pour être flexibles et fonctionner pour une variété de contenus. Une grande partie de l'apparence par défaut de Starlight peut être personnalisée grâce au [CSS](/fr/guides/css-and-tailwind/) et aux [options de configuration](/fr/guides/customization/). + +Quand vos besoins dépassent ce qui est possible de base, Starlight supporte la création de vos propres composants personnalisés pour étendre ou redéfinir (remplacer complètement) ses composants par défaut. + +## Quand redéfinir + +Redéfinir les composants par défaut de Starlight peut être utile lorsque : + +- Vous souhaitez modifier l'apparence d'une partie de l'interface utilisateur de Starlight d'une manière qui n'est pas possible avec du [CSS personnalisé](/fr/guides/css-and-tailwind/). +- Vous souhaitez modifier le comportement d'une partie de l'interface utilisateur de Starlight. +- Vous souhaitez ajouter certains éléments supplémentaires à l'interface utilisateur existante de Starlight. + +## Comment redéfinir + +1. Choisissez le composant de Starlight que vous souhaitez redéfinir. + Vous pouvez trouver une liste complète des composants dans la [référence des redéfinitions](/fr/reference/overrides/). + + Cet exemple va redéfinir le composant [`SocialIcons`](/fr/reference/overrides/#socialicons) de Starlight dans la barre de navigation de la page. + +2. Créez un composant Astro pour remplacer le composant de Starlight. + Cet exemple affiche un lien de contact. + + ```astro + --- + // src/components/EmailLink.astro + import type { Props } from '@astrojs/starlight/props'; + --- + + Me contacter par courriel + ``` + +3. Configurez Starlight pour utiliser votre composant personnalisé avec l'option de configuration [`components`](/fr/reference/configuration/#components) dans le fichier `astro.config.mjs` : + + ```js {9-12} + // astro.config.mjs + import { defineConfig } from 'astro/config'; + import starlight from '@astrojs/starlight'; + + export default defineConfig({ + integrations: [ + starlight({ + title: 'Ma documentation avec redéfinitions', + components: { + // Redéfinit le composant par défaut `SocialLinks`. + SocialIcons: './src/components/EmailLink.astro', + }, + }), + ], + }); + ``` + +## Réutiliser un composant intégré + +Vous pouvez utiliser avec les composants par défaut de Starlight comme vous le feriez avec les vôtres : en les important et en les affichant dans vos propres composants personnalisés. Cela vous permet de conserver toute l'interface utilisateur de base de Starlight dans votre design, tout en ajoutant des éléments supplémentaires à côté. + +L'exemple ci-dessous montre un composant personnalisé qui affiche un lien de courriel suivi du composant `SocialLinks` par défaut : + +```astro {4,8} +--- +// src/components/EmailLink.astro +import type { Props } from '@astrojs/starlight/props'; +import Default from '@astrojs/starlight/components/SocialIcons.astro'; +--- + +Me contacter par courriel + +``` + +Lorsque vous affichez un composant intégré dans un composant personnalisé : + +- Décomposez `Astro.props` dans celui-ci. Cela permet de s'assurer qu'il reçoit toutes les données dont il a besoin pour être affiché. +- Ajoutez un élément [``](https://docs.astro.build/fr/core-concepts/astro-components/#les-emplacements-slots) à l'intérieur du composant par défaut. Cela permet de s'assurer que si le composant reçoit des éléments enfants, Astro sait où les afficher. + +## Utiliser les données de la page + +Lorsque vous redéfinissez un composant de Starlight, votre implémentation personnalisée reçoit un objet `Astro.props` standard contenant toutes les données de la page courante. +Cela vous permet d'utiliser ces valeurs pour contrôler la manière dont votre composant est affiché. + +Par exemple, vous pouvez lire les valeurs du frontmatter de la page via `Astro.props.entry.data`. Dans l'exemple suivant, un composant [`PageTitle`](/fr/reference/overrides/#pagetitle) de remplacement utilise ces données pour afficher le titre de la page courante : + +```astro {5} "{title}" +--- +// src/components/Title.astro +import type { Props } from '@astrojs/starlight/props'; + +const { title } = Astro.props.entry.data; +--- + +

{title}

+ + +``` + +Pour en savoir plus sur les props disponibles, consultez la [référence des redéfinitions](/fr/reference/overrides/#props-des-composants). + +### Redéfinir uniquement sur des pages spécifiques + +Les redéfinitions de composants s'appliquent à toutes les pages. Cependant, vous pouvez les utiliser conditionnellement grâce aux valeurs de `Astro.props` pour déterminer quand afficher votre interface utilisateur personnalisée, quand afficher l'interface utilisateur par défaut de Starlight, ou même quand afficher quelque chose de complètement différent. + +Dans l'exemple suivant, un composant redéfinissant le composant [`Footer`](/fr/reference/overrides/#footer) de Starlight affiche "Construit avec Starlight 🌟" sur la page d'accueil uniquement, et affiche sinon le pied de page par défaut sur toutes les autres pages : + +```astro +--- +// src/components/ConditionalFooter.astro +import type { Props } from '@astrojs/starlight/props'; +import Default from '@astrojs/starlight/components/Footer.astro'; + +const isHomepage = Astro.props.slug === ''; +--- + +{ + isHomepage ? ( + + ) : ( + + + + ) +} +``` + +Pour en savoir plus sur le rendu conditionnel, consultez le [guide de syntaxe d'Astro](https://docs.astro.build/fr/core-concepts/astro-syntax/#html-dynamique). diff --git a/docs/src/content/docs/fr/reference/overrides.md b/docs/src/content/docs/fr/reference/overrides.md new file mode 100644 index 0000000000..47a2c9fdea --- /dev/null +++ b/docs/src/content/docs/fr/reference/overrides.md @@ -0,0 +1,374 @@ +--- +title: Référence des redéfinitions +description: Une vue d'ensemble de tous les composants et les props des composants supportés par les redéfinitions de Starlight. +tableOfContents: + maxHeadingLevel: 4 +--- + +Vous pouvez redéfinir les composants intégrés à Starlight en spécifiant des chemins vers des composants de remplacement avec l'option de configuration [`components`](/fr/reference/configuration#components) de Starlight. +Cette page répertorie tous les composants disponibles qui peuvent être redéfinis et fournit des liens vers leurs implémentations par défaut sur GitHub. + +Pour en savoir plus, consultez le [guide des redéfinitions de composants](/fr/guides/overriding-components/). + +## Props des composants + +Tous les composants peuvent accéder à un objet `Astro.props` standard qui contient des informations concernant la page courante. + +Pour typer vos composants personnalisés, importez le type `Props` depuis Starlight : + +```astro +--- +import type { Props } from '@astrojs/starlight/props'; + +const { hasSidebar } = Astro.props; +// ^ type: boolean +--- +``` + +Cela vous permettra d'obtenir de l'autocomplétion et un typage lors de l'utilisation de `Astro.props`. + +### Props + +Starlight passera les props suivantes à vos composants personnalisés. + +#### `dir` + +**Type:** `'ltr' | 'rtl'` + +Le sens d'écriture de la page. + +#### `lang` + +**Type:** `string` + +L’étiquette d’identification BCP-47 pour la langue de la page, par exemple `en`, `zh` ou `pt-BR`. + +#### `locale` + +**Type:** `string | undefined` + +Le chemin de base utilisé pour servir une langue. `undefined` pour les slugs de la locale racine. + +#### `slug` + +**Type:** `string` + +Le slug de la page généré à partir du nom du fichier du contenu. + +#### `id` + +**Type:** `string` + +L'identifiant unique de cette page basé sur le nom du fichier du contenu. + +#### `isFallback` + +**Type:** `true | undefined` + +`true` si cette page n'est pas traduite dans la langue actuelle et utilise le contenu de la langue par défaut en tant que repli. +Utilisé uniquement dans les sites multilingues. + +#### `entryMeta` + +**Type:** `{ dir: 'ltr' | 'rtl'; lang: string }` + +Métadonnées de la locale pour le contenu de la page. Peut être différent des valeurs de locale de premier niveau lorsque la page utilise un contenu de repli. + +#### `entry` + +L'entrée de la collection de contenu Astro pour la page courante. +Inclut les valeurs du frontmatter pour la page courante dans `entry.data`. + +```ts +entry: { + data: { + title: string; + description: string | undefined; + // etc. + } +} +``` + +Pour en savoir plus sur le format de cet objet, consultez la [référence du type d'entrée de collection](https://docs.astro.build/fr/reference/api-reference/#collection-entry-type). + +#### `sidebar` + +**Type:** `SidebarEntry[]` + +Les entrées de la barre latérale de navigation du site pour cette page. + +#### `hasSidebar` + +**Type:** `boolean` + +Indique si la barre latérale est affichée sur cette page. + +#### `pagination` + +**Type:** `{ prev?: Link; next?: Link }` + +Liens vers la page précédente et suivante dans la barre latérale si celle-ci est activée. + +#### `toc` + +**Type:** `{ minHeadingLevel: number; maxHeadingLevel: number; items: TocItem[] } | undefined` + +Table des matières de la page courante si celle-ci est activée. + +#### `headings` + +**Type:** `{ depth: number; slug: string; text: string }[]` + +Un tableau de toutes les en-têtes Markdown extraites de la page courante. +Utilisez [`toc`](#toc) à la place si vous souhaitez construire une table des matières qui respecte les options de configuration de Starlight. + +#### `lastUpdated` + +**Type:** `Date | undefined` + +Un objet JavaScript de type `Date` représentant la date de dernière mise à jour de cette page si cette fonctionnalité est activée. + +#### `editUrl` + +**Type:** `URL | undefined` + +Un objet `URL` de l'adresse où cette page peut être modifiée si cette fonctionnalité est activée. + +--- + +## Composants + +### Métadonnées + +Ces composants sont utilisés dans l'élément `` de chaque page. +Ils ne doivent inclure que des [éléments autorisés à l'intérieur de ``](https://developer.mozilla.org/fr/docs/Web/HTML/Element/head). + +#### `Head` + +**Composant par défaut:** [`Head.astro`](https://github.com/withastro/starlight/blob/main/packages/starlight/components/Head.astro) + +Composant utilisé à l'intérieur de l'élément `` de chaque page. +Inclut des balises importantes comme `` et `<meta charset="utf-8">`. + +Redéfinissez ce composant en dernier recours. +Préférez l'option [`head`](/fr/reference/configuration#head) de la configuration de Starlight si possible. + +#### `ThemeProvider` + +**Composant par défaut:** [`ThemeProvider.astro`](https://github.com/withastro/starlight/blob/main/packages/starlight/components/ThemeProvider.astro) + +Composant utilisé à l'intérieur de l'élément `<head>` qui configure la prise en charge du thème sombre/clair. +L'implémentation par défaut inclut un script en ligne et un élément `<template>` utilisé par le script situé dans [`<ThemeSelect />`](#themeselect). + +--- + +### Accessibilité + +#### `SkipLink` + +**Composant par défaut:** [`SkipLink.astro`](https://github.com/withastro/starlight/blob/main/packages/starlight/components/SkipLink.astro) + +Composant utilisé comme premier élément à l'intérieur du `<body>` qui relie au contenu principal de la page pour des raisons d'accessibilité. +L'implémentation par défaut est masquée jusqu'à ce qu'il reçoive le focus d'un utilisateur utilisant la navigation au clavier. + +--- + +### Mise en page + +Ces composants sont responsables de la mise en page des composants de Starlight et de la gestion des vues pour différents points d'arrêt. +Redéfinir ceux-ci implique une complexité significative. +Lorsque cela est possible, préférez redéfinir un composant de plus bas niveau. + +#### `PageFrame` + +**Composant par défaut:** [`PageFrame.astro`](https://github.com/withastro/starlight/blob/main/packages/starlight/components/PageFrame.astro) + +Composant de mise en page contenant la plupart du contenu de la page. +L'implémentation par défaut configure la mise en page de l'en-tête, de la barre latérale et du contenu principal et inclut des emplacements (slots) nommés `header` et `sidebar` en plus de l'emplacement par défaut pour le contenu principal. +Il affiche également [`<MobileMenuToggle />`](#mobilemenutoggle) qui prend en charge l'affichage de la barre latérale de navigation sur petits écrans (mobiles). + +#### `MobileMenuToggle` + +**Composant par défaut:** [`MobileMenuToggle.astro`](https://github.com/withastro/starlight/blob/main/packages/starlight/components/MobileMenuToggle.astro) + +Composant utilisé à l'intérieur de [`<PageFrame>`](#pageframe) qui est responsable de l'affichage de la barre latérale de navigation sur petits écrans (mobiles). + +#### `TwoColumnContent` + +**Composant par défaut:** [`TwoColumnContent.astro`](https://github.com/withastro/starlight/blob/main/packages/starlight/components/TwoColumnContent.astro) + +Composant de mise en page enveloppant le contenu principal de la page et la barre latérale de droite (table des matières). +L'implémentation par défaut prend en charge le changement entre une mise en page à une seule colonne pour petits écrans et une mise en page à deux colonnes pour écrans plus larges. + +--- + +### En-tête + +Ces composants affichent la barre de navigation supérieure de Starlight. + +#### `Header` + +**Composant par défaut:** [`Header.astro`](https://github.com/withastro/starlight/blob/main/packages/starlight/components/Header.astro) + +Composant d'en-tête affiché en haut de chaque page. +L'implémentation par défaut affiche [`<SiteTitle />`](#sitetitle), [`<Search />`](#search), [`<SocialIcons />`](#socialicons), [`<ThemeSelect />`](#themeselect) et [`<LanguageSelect />`](#languageselect). + +#### `SiteTitle` + +**Composant par défaut:** [`SiteTitle.astro`](https://github.com/withastro/starlight/blob/main/packages/starlight/components/SiteTitle.astro) + +Composant utilisé au début de l'en-tête du site pour afficher le titre du site. +L'implémentation par défaut inclut la logique pour afficher les logos définis dans la configuration de Starlight. + +#### `Search` + +**Composant par défaut:** [`Search.astro`](https://github.com/withastro/starlight/blob/main/packages/starlight/components/Search.astro) + +Composant utilisé pour afficher l'interface de recherche de Starlight. +L'implémentation par défaut inclut le bouton dans l'en-tête et le code pour afficher une fenêtre modale de recherche lorsqu'il est cliqué et charger [l'interface utilisateur de Pagefind](https://pagefind.app/). + +#### `SocialIcons` + +**Composant par défaut:** [`SocialIcons.astro`](https://github.com/withastro/starlight/blob/main/packages/starlight/components/SocialIcons.astro) + +Composant utilisé dans l'en-tête du site qui inclut des liens avec des icônes vers différents médias sociaux. +L'implémentation par défaut utilise l'option [`social`](/fr/reference/configuration#social) de la configuration de Starlight pour afficher les icônes et les liens. + +#### `ThemeSelect` + +**Composant par défaut:** [`ThemeSelect.astro`](https://github.com/withastro/starlight/blob/main/packages/starlight/components/ThemeSelect.astro) + +Composant utilisé dans l'en-tête du site qui permet aux utilisateurs de sélectionner leur thème de couleur préféré. + +#### `LanguageSelect` + +**Composant par défaut:** [`LanguageSelect.astro`](https://github.com/withastro/starlight/blob/main/packages/starlight/components/LanguageSelect.astro) + +Component utilisé dans l'en-tête du site qui permet aux utilisateurs de changer de langue. + +--- + +### Barre latérale globale + +La barre latérale globale de Starlight contient la navigation principale du site. +Sur des écrans peu larges, elle est masquée derrière un menu déroulant. + +#### `Sidebar` + +**Composant par défaut:** [`Sidebar.astro`](https://github.com/withastro/starlight/blob/main/packages/starlight/components/Sidebar.astro) + +Composant utilisé avant le contenu de la page qui contient la navigation globale. +L'implémentation par défaut est affichée comme une barre latérale sur des écrans suffisamment larges et à l'intérieur d'un menu déroulant sur des écrans plus petits (mobiles). +Il utilise aussi [`<MobileMenuFooter />`](#mobilemenufooter) pour afficher des éléments supplémentaires dans le menu mobile. + +#### `MobileMenuFooter` + +**Composant par défaut:** [`MobileMenuFooter.astro`](https://github.com/withastro/starlight/blob/main/packages/starlight/components/MobileMenuFooter.astro) + +Composant utilisé à la fin du menu déroulant mobile. +L'implémentation par défaut affiche [`<ThemeSelect />`](#themeselect) et [`<LanguageSelect />`](#languageselect). + +--- + +### Barre latérale de page + +La barre latérale de page de Starlight est responsable d'afficher une table des matières mettant en avant les titres de section de la page courante. +Sur des écrans peu larges, elle est remplacée par un menu déroulant adhérant. + +#### `PageSidebar` + +**Composant par défaut:** [`PageSidebar.astro`](https://github.com/withastro/starlight/blob/main/packages/starlight/components/PageSidebar.astro) + +Composant affiché avant le contenu de la page et contenant la table des matières. +L'implémentation par défaut affiche [`<TableOfContents />`](#tableofcontents) et [`<MobileTableOfContents />`](#mobiletableofcontents). + +#### `TableOfContents` + +**Composant par défaut:** [`TableOfContents.astro`](https://github.com/withastro/starlight/blob/main/packages/starlight/components/TableOfContents.astro) + +Composant qui affiche la table des matières de la page courante sur des écrans suffisamment larges. + +#### `MobileTableOfContents` + +**Composant par défaut:** [`MobileTableOfContents.astro`](https://github.com/withastro/starlight/blob/main/packages/starlight/components/MobileTableOfContents.astro) + +Composant qui affiche la table des matières de la page courante sur des petits écrans (mobiles). + +--- + +### Contenu + +Ces composants sont utilisés dans la colonne principale de contenu de la page. + +#### `Banner` + +**Composant par défaut:** [`Banner.astro`](https://github.com/withastro/starlight/blob/main/packages/starlight/components/Banner.astro) + +Composant représentant une bannière affichée en haut de chaque page. +L'implémentation par défaut utilise la valeur du champ [`banner`](/fr/reference/frontmatter#banner) du frontmatter de la page pour décider de l'affichage ou non. + +#### `ContentPanel` + +**Composant par défaut:** [`ContentPanel.astro`](https://github.com/withastro/starlight/blob/main/packages/starlight/components/ContentPanel.astro) + +Composant de mise en page utilisé pour envelopper les section de la colonne principale de contenu. + +#### `PageTitle` + +**Composant par défaut:** [`PageTitle.astro`](https://github.com/withastro/starlight/blob/main/packages/starlight/components/PageTitle.astro) + +Composant contenant l'élement `<h1>` de la page courante. + +Les implémentations personnalisées doivent s'assurer qu'elles définissent `id="_top"` sur l'élément `<h1>` comme dans l'implémentation par défaut. + +#### `FallbackContentNotice` + +**Composant par défaut:** [`FallbackContentNotice.astro`](https://github.com/withastro/starlight/blob/main/packages/starlight/components/FallbackContentNotice.astro) + +Note affichée aux utilisateurs sur les pages où une traduction pour la langue courante n'est pas disponible. +Utilisé uniquement sur les sites multilingues. + +#### `Hero` + +**Composant par défaut:** [`Hero.astro`](https://github.com/withastro/starlight/blob/main/packages/starlight/components/Hero.astro) + +Composant affiché en haut de la page lorsque le champ [`hero`](/fr/reference/frontmatter#hero) est défini dans le frontmatter. +L'implémentation par défaut affiche un large titre, une accroche et des liens d'appel à l'action à côté d'une image facultative. + +#### `MarkdownContent` + +**Composant par défaut:** [`MarkdownContent.astro`](https://github.com/withastro/starlight/blob/main/packages/starlight/components/MarkdownContent.astro) + +Composant affiché autour du contenu principal de chaque page. +L'implémentation par défaut définit les styles de base à appliquer au contenu Markdown. + +--- + +### Pied de page + +Ces composants sont affichés en bas de la colonne principale de contenu de la page. + +#### `Footer` + +**Composant par défaut:** [`Footer.astro`](https://github.com/withastro/starlight/blob/main/packages/starlight/components/Footer.astro) + +Composant pied de page affiché en bas de chaque page. +L'implémentation par défaut affiche [`<LastUpdated />`](#lastupdated), [`<Pagination />`](#pagination) et [`<EditLink />`](#editlink). + +#### `LastUpdated` + +**Composant par défaut:** [`LastUpdated.astro`](https://github.com/withastro/starlight/blob/main/packages/starlight/components/LastUpdated.astro) + +Composant utilisé dans le pied de page pour afficher la date de dernière mise à jour de la page. + +#### `EditLink` + +**Composant par défaut:** [`EditLink.astro`](https://github.com/withastro/starlight/blob/main/packages/starlight/components/EditLink.astro) + +Composant utilisé dans le pied de page pour afficher un lien vers l'emplacement où la page peut être modifiée. + +#### `Pagination` + +**Composant par défaut:** [`Pagination.astro`](https://github.com/withastro/starlight/blob/main/packages/starlight/components/Pagination.astro) + +Composant utilisé dans le pied de page pour afficher des flèches de navigation entre les pages précédentes/suivantes.