Merge branch 'main' into main

docs/package.json

@@ -15,17 +15,18 @@
   "dependencies": {
     "@astrojs/starlight": "workspace:*",
     "@types/culori": "^2.0.0",
-    "astro": "^3.2.3",
+    "astro": "^4.0.1",
     "culori": "^3.2.0",
     "sharp": "^0.32.5"
   },
   "devDependencies": {
-    "hast-util-from-html": "^1.0.2",
-    "hast-util-to-string": "^2.0.0",
-    "hastscript": "^7.2.0",
+    "@types/hast": "^3.0.3",
+    "hast-util-from-html": "^2.0.1",
+    "hast-util-to-string": "^3.0.0",
+    "hastscript": "^8.0.0",
     "pa11y-ci": "^3.0.1",
-    "rehype": "^12.0.1",
+    "rehype": "^13.0.1",
     "start-server-and-test": "^2.0.0",
-    "unist-util-visit": "^4.1.2"
+    "unist-util-visit": "^5.0.0"
   }
 }

docs/src/components/internal/rehype-file-tree.ts

@@ -1,7 +1,7 @@
 import { fromHtml } from 'hast-util-from-html';
 import { toString } from 'hast-util-to-string';
-import { h } from 'hastscript';
-import type { Element, HChild } from 'hastscript/lib/core';
+import { h, type Child } from 'hastscript';
+import type { Element } from 'hast';
 import { rehype } from 'rehype';
 import { CONTINUE, SKIP, visit } from 'unist-util-visit';
 import { getIcon } from './file-tree-icons';
@@ -35,9 +35,10 @@ const FolderIcon = makeSVGIcon(
 	'<svg viewBox="0 0 20 20"><path d="M14.77 6.45H9.8v-.47A.97.97 0 0 0 8.83 5H3.75v10H15.7V7.42a.91.91 0 0 0-.93-.97Z"/></svg>'
 );
 
-export const fileTreeProcessor = rehype().use(() => (tree, file) => {
+export const fileTreeProcessor = rehype().use(() => (tree: Element, file) => {
 	const { directoryLabel } = file.data as { directoryLabel: string };
 	visit(tree, 'element', (node) => {
+		if (node.type !== 'element') return CONTINUE;
 		// Strip nodes that only contain newlines
 		node.children = node.children.filter(
 			(child) => child.type === 'comment' || child.type !== 'text' || !/^\n+$/.test(child.value)
@@ -50,7 +51,7 @@ export const fileTreeProcessor = rehype().use(() => (tree, file) => {
 
 		const [firstChild, ...otherChildren] = node.children;
 
-		const comment: HChild[] = [];
+		const comment: Child[] = [];
 		if (firstChild?.type === 'text') {
 			const [filename, ...fragments] = firstChild.value.split(' ');
 			firstChild.value = filename || '';
@@ -64,14 +65,14 @@ export const fileTreeProcessor = rehype().use(() => (tree, file) => {
 		otherChildren.splice(0, subTreeIndex > -1 ? subTreeIndex : otherChildren.length);
 		comment.push(...commentNodes);
 
-		const firstChildTextContent = toString(firstChild);
+		const firstChildTextContent = firstChild ? toString(firstChild) : '';
 
 		// Decide a node is a directory if it ends in a `/` or contains another list.
 		const isDirectory =
 			/\/\s*$/.test(firstChildTextContent) ||
 			otherChildren.some((child) => child.type === 'element' && child.tagName === 'ul');
 		const isPlaceholder = /^\s*(\.{3}|…)\s*$/.test(firstChildTextContent);
-		const isHighlighted = firstChild.type === 'element' && firstChild.tagName === 'strong';
+		const isHighlighted = firstChild?.type === 'element' && firstChild.tagName === 'strong';
 		const hasContents = otherChildren.length > 0;
 
 		const fileExtension = isDirectory ? 'dir' : firstChildTextContent.trim().split('.').pop() || '';

docs/src/components/showcase-sites.astro

@@ -77,4 +77,10 @@ import FluidGrid from './fluid-grid.astro';
 	/>
 	<Card title="Knip" href="https://knip.dev" thumbnail="knip.dev.png" />
 	<Card title="secco" href="https://secco.lekoarts.de" thumbnail="secco.lekoarts.de.png" />
+	<Card
+		title="SiteOne Crawler"
+		href="https://crawler.siteone.io/?utm_source=starlight-docs"
+		thumbnail="crawler.siteone.io.png"
+	/>
+	<Card title="csmos" href="https://csmos.space" thumbnail="csmos.space.png" />
 </FluidGrid>

docs/src/content/docs/es/getting-started.mdx

@@ -134,27 +134,27 @@ Debido a que Starlight es un software beta, habrá actualizaciones y mejoras fre
 ¡Asegúrate de actualizar Starlight regularmente!
 :::
 
-Starlight es una integración Astro y se actualiza de la misma manera que cualquier otra integración `@astrojs/*`:
+Starlight es una integración Astro. Puedes actualizarlo y otros paquetes de Astro ejecutando el siguiente comando en tu terminal:
 
 <Tabs>
 <TabItem label="npm">
 
 ```sh
-npm install @astrojs/starlight@latest
+npx @astrojs/upgrade
 ```
 
 </TabItem>
 <TabItem label="pnpm">
 
 ```sh
-pnpm upgrade @astrojs/starlight --latest
+pnpm dlx @astrojs/upgrade
 ```
 
 </TabItem>
 <TabItem label="Yarn">
 
 ```sh
-yarn upgrade @astrojs/starlight --latest
+yarn dlx @astrojs/upgrade
 ```
 
 </TabItem>

docs/src/content/docs/es/guides/authoring-content.md

@@ -21,7 +21,7 @@ El contenido de la página sigue luego de los `---`.
 ```
 
 Cada página debe incluir al menos un `title`.
-Vea la [referencia de frontmatter](/es/reference/frontmatter/) para ver todos los campos disponibles y cómo añadir campos personalizados.
+Consulta la [referencia de frontmatter](/es/reference/frontmatter/) para ver todos los campos disponibles y cómo añadir campos personalizados.
 
 ## Estilos en línea
 

docs/src/content/docs/fr/getting-started.mdx

@@ -135,27 +135,28 @@ Comme Starlight est un logiciel en version bêta, il y aura des mises à jour et
 Assurez-vous de mettre à jour Starlight régulièrement !
 :::
 
-Starlight est une intégration Astro, et est mis à jour comme toute intégration `@astrojs/*` :
+Starlight est une intégration Astro.
+Vous pouvez la mettre à jour ainsi que tous autres packages Astro en exécutant la commande suivante dans votre terminal :
 
 <Tabs>
 <TabItem label="npm">
 
 ```sh
-npm install @astrojs/starlight@latest
+npx @astrojs/upgrade
 ```
 
 </TabItem>
 <TabItem label="pnpm">
 
 ```sh
-pnpm upgrade @astrojs/starlight --latest
+pnpm dlx @astrojs/upgrade
 ```
 
 </TabItem>
 <TabItem label="Yarn">
 
 ```sh
-yarn upgrade @astrojs/starlight --latest
+yarn dlx @astrojs/upgrade
 ```
 
 </TabItem>

docs/src/content/docs/fr/guides/authoring-content.md

@@ -7,6 +7,22 @@ Starlight prend en charge l'ensemble de la syntaxe [Markdown](https://daringfire
 
 Veillez à consulter les [MDX docs](https://mdxjs.com/docs/what-is-mdx/#markdown) ou les [Markdoc docs](https://markdoc.dev/docs/syntax) si vous utilisez ces formats de fichiers, car la prise en charge et l'utilisation de Markdown peuvent varier.
 
+## Frontmatter
+
+Vous pouvez personnaliser chaque page individuellement en définissant des valeurs dans leur frontmatter.
+Le frontmatter se situe en haut de vos fichiers entre les séparateurs `---` :
+
+```md title="src/content/docs/exemple.md"
+---
+title: Le titre de ma page
+---
+
+Le contenu de la page suit le second `---`.
+```
+
+Chaque page doit inclure au moins un titre (`title`).
+Consultez la [référence du frontmatter](/fr/reference/frontmatter/) pour connaître tous les champs disponibles et comment ajouter des champs personnalisés.
+
 ## Styles en ligne
 
 Le texte peut être **gras**, _italique_, ou ~~barré~~.

docs/src/content/docs/fr/guides/i18n.mdx

@@ -147,9 +147,9 @@ En plus d'héberger des fichiers de contenu traduits, Starlight vous permet de t
 
 Les textes de l'interface utilisateur traduits en <LanguagesList /> sont disponibles prêts à l'emploi, et nous acceptons les [contributions pour ajouter d'autres langues par défaut](https://github.com/withastro/starlight/blob/main/CONTRIBUTING.md).
 
-Vous pouvez fournir des traductions pour les langues supplémentaires que vous supportez - ou remplacer nos étiquettes par défaut - via la collection de données `i18n`.
+Vous pouvez fournir des traductions pour les langues supplémentaires que vous supportez - ou remplacer nos étiquettes par défaut - via la collection de contenus `i18n`.
 
-1. Configurez la collection de données `i18n` dans `src/content/config.ts` si elle n'est pas déjà configurée :
+1. Configurez la collection de contenus `i18n` dans `src/content/config.ts` si elle n'est pas déjà configurée :
 
    ```diff lang="js" ins=/, (i18nSchema)/
    // src/content/config.ts
@@ -232,3 +232,28 @@ Vous pouvez fournir des traductions pour les langues supplémentaires que vous s
    	"pagefind.searching": "Searching for [SEARCH_TERM]..."
    }
    ```
+
+### Étendre le schéma de traduction
+
+Ajoutez des clés personnalisées aux dictionnaires de traduction de votre site en définissant `extend` dans les options de `i18nSchema()`.
+Dans l'exemple suivant, une nouvelle clé optionnelle `custom.label` est ajoutée aux clés par défaut :
+
+```diff lang="js"
+// src/content/config.ts
+import { defineCollection, z } from 'astro:content';
+import { docsSchema, i18nSchema } from '@astrojs/starlight/schema';
+
+export const collections = {
+	docs: defineCollection({ schema: docsSchema() }),
+	i18n: defineCollection({
+		type: 'data',
+		schema: i18nSchema({
++			extend: z.object({
++				'custom.label': z.string().optional(),
++			}),
+		}),
+	}),
+};
+```
+
+Consultez [« Définir un schéma de collection de contenus »](https://docs.astro.build/fr/guides/content-collections/#defining-a-collection-schema) dans la documentation d'Astro pour en savoir plus sur les schémas de collection de contenus.

docs/src/content/docs/fr/guides/overriding-components.md

@@ -1,8 +1,6 @@
 ---
 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/).

docs/src/content/docs/fr/guides/site-search.mdx

@@ -0,0 +1,166 @@
+---
+title: Recherche
+description: Découvrez les fonctionnalités de recherche intégrées à Starlight et comment les personnaliser.
+sidebar:
+  badge: Nouveau
+---
+
+import { Tabs, TabItem } from '@astrojs/starlight/components';
+
+Par défaut, les sites utilisant Starlight incluent une recherche plein texte utilisant [Pagefind](https://pagefind.app/), un outil de recherche rapide et à faible bande passante pour sites statiques.
+
+Aucune configuration n'est requise pour activer la recherche. Créez et déployez votre site, puis utilisez la barre de recherche dans l'en-tête du site pour trouver du contenu.
+
+## Cacher du contenu dans les résultats de recherche
+
+### Exclure une page
+
+Pour exclure une page de votre index de recherche, ajoutez [`pagefind: false`](/fr/reference/frontmatter/#pagefind) au frontmatter de la page :
+
+```md title="src/content/docs/sans-recherche.md" ins={3}
+---
+title: Contenu à cacher de la recherche
+pagefind: false
+---
+```
+
+### Exclure une partie d'une page
+
+Pagefind ignorera le contenu à l'intérieur d'un élément avec l'attribut [`data-pagefind-ignore`](https://pagefind.app/docs/indexing/#removing-individual-elements-from-the-index).
+
+Dans l'exemple suivant, le premier paragraphe s'affichera dans les résultats de recherche, mais le contenu de la `<div>` ne s'affichera pas :
+
+```md title="src/content/docs/resultats-partiels.md" ins="data-pagefind-ignore"
+---
+title: Page partiellement indexée
+---
+
+Ce texte sera trouvable via la recherche.
+
+<div data-pagefind-ignore>
+
+Ce texte sera caché de la recherche.
+
+</div>
+```
+
+## Système de recherche alternatif
+
+### Algolia DocSearch
+
+Si vous avez accès au [programme DocSearch d'Algolia](https://docsearch.algolia.com/) et que vous souhaitez l'utiliser à la place de Pagefind, vous pouvez utiliser le module d'extension officiel DocSearch de Starlight.
+
+1. Installez `@astrojs/starlight-docsearch` :
+
+   <Tabs>
+
+   <TabItem label="npm">
+
+   ```sh
+   npm install @astrojs/starlight-docsearch
+   ```
+
+   </TabItem>
+
+   <TabItem label="pnpm">
+
+   ```sh
+   pnpm install @astrojs/starlight-docsearch
+   ```
+
+   </TabItem>
+
+   <TabItem label="Yarn">
+
+   ```sh
+   yarn add @astrojs/starlight-docsearch
+   ```
+
+   </TabItem>
+
+   </Tabs>
+
+2. Ajouter DocSearch à votre configuration [`plugins`](/fr/reference/configuration/#plugins) de Starlight dans le fichier `astro.config.mjs` et spécifiez votre `appId`, `apiKey` et `indexName` d'Algolia :
+
+   ```js ins={4,10-16}
+   // astro.config.mjs
+   import { defineConfig } from 'astro/config';
+   import starlight from '@astrojs/starlight';
+   import starlightDocSearch from '@astrojs/starlight-docsearch';
+
+   export default defineConfig({
+   	integrations: [
+   		starlight({
+   			title: 'Site avec DocSearch',
+   			plugins: [
+   				starlightDocSearch({
+   					appId: 'VOTRE_APP_ID',
+   					apiKey: 'VOTRE_CLE_API_DE_RECHERCHE',
+   					indexName: 'VOTRE_NOM_D_INDEX',
+   				}),
+   			],
+   		}),
+   	],
+   });
+   ```
+
+Avec cette configuration mise à jour, la barre de recherche de votre site ouvrira désormais une modale Algolia au lieu de celle par défaut.
+
+#### Traduire l'interface utilisateur de DocSearch
+
+DocSearch fournit seulement des chaînes de l'interface utilisateur en anglais par défaut.
+Ajoutez des traductions de l'interface utilisateur de la modale pour votre langue en utilisant le [système d'internationalisation](/fr/guides/i18n/#traduire-linterface-utilisateur-de-starlight) intégré à Starlight.
+
+1. Étendez la définition de la collection de contenus `i18n` de Starlight avec le schéma DocSearch dans `src/content/config.ts` :
+
+   ```js ins={4} ins=/{ extend: .+ }/
+   // src/content/config.ts
+   import { defineCollection } from 'astro:content';
+   import { docsSchema, i18nSchema } from '@astrojs/starlight/schema';
+   import { docSearchI18nSchema } from '@astrojs/starlight-docsearch/schema';
+
+   export const collections = {
+   	docs: defineCollection({ schema: docsSchema() }),
+   	i18n: defineCollection({
+   		type: 'data',
+   		schema: i18nSchema({ extend: docSearchI18nSchema() }),
+   	}),
+   };
+   ```
+
+2. Ajoutez des traductions à vos fichiers JSON dans `src/content/i18n/`.
+
+   Voici les valeurs par défaut en anglais utilisées par DocSearch :
+
+   ```json title="src/content/i18n/en.json"
+   {
+   	"docsearch.searchBox.resetButtonTitle": "Clear the query",
+   	"docsearch.searchBox.resetButtonAriaLabel": "Clear the query",
+   	"docsearch.searchBox.cancelButtonText": "Cancel",
+   	"docsearch.searchBox.cancelButtonAriaLabel": "Cancel",
+
+   	"docsearch.startScreen.recentSearchesTitle": "Recent",
+   	"docsearch.startScreen.noRecentSearchesText": "No recent searches",
+   	"docsearch.startScreen.saveRecentSearchButtonTitle": "Save this search",
+   	"docsearch.startScreen.removeRecentSearchButtonTitle": "Remove this search from history",
+   	"docsearch.startScreen.favoriteSearchesTitle": "Favorite",
+   	"docsearch.startScreen.removeFavoriteSearchButtonTitle": "Remove this search from favorites",
+
+   	"docsearch.errorScreen.titleText": "Unable to fetch results",
+   	"docsearch.errorScreen.helpText": "You might want to check your network connection.",
+
+   	"docsearch.footer.selectText": "to select",
+   	"docsearch.footer.selectKeyAriaLabel": "Enter key",
+   	"docsearch.footer.navigateText": "to navigate",
+   	"docsearch.footer.navigateUpKeyAriaLabel": "Arrow up",
+   	"docsearch.footer.navigateDownKeyAriaLabel": "Arrow down",
+   	"docsearch.footer.closeText": "to close",
+   	"docsearch.footer.closeKeyAriaLabel": "Escape key",
+   	"docsearch.footer.searchByText": "Search by",
+
+   	"docsearch.noResultsScreen.noResultsText": "No results for",
+   	"docsearch.noResultsScreen.suggestedQueryText": "Try searching for",
+   	"docsearch.noResultsScreen.reportMissingResultsText": "Believe this query should return results?",
+   	"docsearch.noResultsScreen.reportMissingResultsLinkText": "Let us know."
+   }
+   ```