Merge branch 'main' into hd-feat-link-button

* main: (57 commits) Add type checking job to the CI workflow (withastro#1827) [ci] format i18n(pt-BR): Update `components.mdx` (withastro#1815) [ci] format i18n(ru): update translations (withastro#1825) i18n(pt-BR): Update `css-and-tailwind.mdx` (withastro#1817) i18n(es): updates `pages` (withastro#1823) i18n(es): update `i18n` (withastro#1822) i18n(es): updates `overrides` (withastro#1820) i18n(es): update `guides/components` and add `syncKey` to various pages (withastro#1818) [ci] format i18n(es): update `community-content` (withastro#1824) i18n(es): update `configuration` (withastro#1821) i18n(es): update `frontmatter` (withastro#1819) i18n(fr): update `guides/pages.mdx` (withastro#1800) i18n(fr): update `reference/overrides.md` (withastro#1803) i18n(fr): update `reference/frontmatter.md` (withastro#1802) i18n(fr): update `reference/configuration.mdx` (withastro#1801) i18n(fr): update `guides/i18n.mdx` (withastro#1799) i18n(fr): update `guides/components` and add `syncKey` to various pages (withastro#1797) ...
HiDeoo · May 3, 2024 · c77c2ad · c77c2ad
2 parents 15580a8 + 95ace6d
commit c77c2ad
Show file tree

Hide file tree

Showing 148 changed files with 2,234 additions and 810 deletions.
diff --git a/.changeset/config.json b/.changeset/config.json
@@ -9,7 +9,7 @@
   "access": "public",
   "baseBranch": "main",
   "updateInternalDependencies": "patch",
-  "ignore": ["starlight-docs", "@example/*", "starlight-file-icons-generator"],
+  "ignore": ["starlight-docs", "@example/*", "starlight-file-icons-generator", "@e2e/*"],
   "___experimentalUnsafeOptions_WILL_CHANGE_IN_PATCH": {
     "onlyUpdatePeerDependentsWhenOutOfRange": true
   }

diff --git a/.changeset/sweet-vans-carry.md b/.changeset/sweet-vans-carry.md
diff --git a/.changeset/swift-files-wave.md b/.changeset/swift-files-wave.md
diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml
@@ -30,6 +30,37 @@ jobs:
       - name: Test packages
         run: pnpm -r test:coverage
 
+  e2e-test:
+    name: Run E2E tests
+    runs-on: ubuntu-20.04
+    steps:
+      - uses: actions/checkout@v4
+      - uses: pnpm/action-setup@v3
+      - uses: actions/setup-node@v4
+        with:
+          node-version: ${{ env.NODE_VERSION }}
+          cache: 'pnpm'
+      - run: pnpm i
+      - name: Test packages
+        run: pnpm -r test:e2e
+
+  type-check:
+    name: Run type checks
+    runs-on: ubuntu-20.04
+    steps:
+      - uses: actions/checkout@v4
+      - uses: pnpm/action-setup@v3
+      - uses: actions/setup-node@v4
+        with:
+          node-version: ${{ env.NODE_VERSION }}
+          cache: 'pnpm'
+      - run: pnpm i
+      - name: Generate docs types
+        working-directory: docs
+        run: pnpm astro sync
+      - name: Type check packages
+        run: pnpm typecheck
+
   pa11y:
     name: Check for accessibility issues
     runs-on: ubuntu-20.04

diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
@@ -187,6 +187,36 @@ pnpm test:coverage
 
 This will print a table to your terminal and also generate an HTML report you can load in a web browser by opening [`packages/starlight/__coverage__/index.html`](./packages/starlight/__coverage__/index.html).
 
+### End-to-end (E2E) tests
+
+Starlight also includes E2E tests in [`packages/starlight/__e2e__/`](./packages/starlight/__e2e__/), which are run using [Playwright][playwright].
+
+To run these tests, move into the Starlight package and then run `pnpm test:e2e`:
+
+```sh
+cd packages/starlight
+pnpm test:e2e
+```
+
+#### Test fixtures
+
+Each subdirectory of `packages/starlight/__e2e__/fixtures` should contain the basic files needed to run Starlight (`package.json`, `astro.config.mjs`, a content collection configuration in `src/content/config.ts` and some content to render in `src/content/docs/`).
+
+The `testFactory()` helper can be used in a test file to define the fixture which will be built and loaded in a preview server during a set of tests.
+
+```ts
+// packages/starlight/__e2e__/feature.test.ts
+import { testFactory } from './test-utils';
+
+const test = await testFactory('./fixtures/basics/');
+```
+
+This allows you to run tests against different combinations of Astro and Starlight configuration options for various content.
+
+#### When to add E2E tests?
+
+E2E are most useful for testing what happens on a page after it has been loaded by a browser. They run slower than unit tests so they should be used sparingly when unit tests aren’t sufficient.
+
 ## Translations
 
 Translations help make Starlight accessible to more people.
@@ -254,6 +284,7 @@ To add a language, you will need its BCP-47 tag and a label. See [“Adding a ne
 [gfi]: https://github.com/withastro/starlight/issues?q=is%3Aissue+is%3Aopen+label%3A%22good+first+issue%22+
 [api-docs]: https://docs.astro.build/en/reference/integrations-reference/
 [vitest]: https://vitest.dev/
+[playwright]: https://playwright.dev/
 
 ## Showcase
 

diff --git a/docs/src/content/docs/es/getting-started.mdx b/docs/src/content/docs/es/getting-started.mdx
@@ -15,7 +15,7 @@ Consulta las [instrucciones de configuración manual](/es/manual-setup/) para ag
 
 Crea un nuevo proyecto de Astro + Starlight ejecutando el siguiente comando en tu terminal:
 
-<Tabs>
+<Tabs syncKey="pkg">
 <TabItem label="npm">
 
 ```sh
@@ -52,7 +52,7 @@ Cuando trabajas localmente, el [servidor de desarrollo de Astro](https://docs.as
 
 Dentro del directorio de tu proyecto, ejecuta el siguiente comando para iniciar el servidor de desarrollo:
 
-<Tabs>
+<Tabs syncKey="pkg">
 <TabItem label="npm">
 
 ```sh
@@ -103,7 +103,7 @@ Debido a que Starlight es un software beta, habrá actualizaciones y mejoras fre
 
 Starlight es una integración Astro. Puedes actualizarlo y otros paquetes de Astro ejecutando el siguiente comando en tu terminal:
 
-<Tabs>
+<Tabs syncKey="pkg">
 <TabItem label="npm">
 
 ```sh

diff --git a/docs/src/content/docs/es/guides/components.mdx b/docs/src/content/docs/es/guides/components.mdx
@@ -84,6 +84,50 @@ El código anterior genera las siguientes pestañas en la página:
 	</TabItem>
 </Tabs>
 
+#### Pestañas sincronizadas
+
+Manten varias pestañas sincronizadas añadiendo el atributo `syncKey`.
+
+Todas las `<Tabs>` en una página con el mismo valor de `syncKey` mostrarán la misma etiqueta activa. Esto permite a tu lector elegir una vez (por ejemplo, su sistema operativo o gestor de paquetes) y ver su elección reflejada en toda la página.
+
+Para sincronizar pestañas relacionadas, añade una propiedad `syncKey` idéntica a cada componente `<Tabs>` y asegúrate de que todos usen las mismas etiquetas `<TabItem>`:
+
+```mdx 'syncKey="constellations"'
+# src/content/docs/example.mdx
+
+import { Tabs, TabItem } from '@astrojs/starlight/components';
+
+_Algunas estrellas:_
+
+<Tabs syncKey="constellations">
+	<TabItem label="Orion">Bellatrix, Rigel, Betelgeuse</TabItem>
+	<TabItem label="Gemini">Pollux, Cástor A, Cástor B</TabItem>
+</Tabs>
+
+_Algunos exoplanetas:_
+
+<Tabs syncKey="constellations">
+	<TabItem label="Orion">HD 34445 b, Gliese 179 b, Wasp-82 b</TabItem>
+	<TabItem label="Gemini">Pollux b, HAT-P-24b, HD 50554 b</TabItem>
+</Tabs>
+```
+
+El código anterior genera lo siguiente en la página:
+
+_Algunas estrellas:_
+
+<Tabs syncKey="constellations">
+	<TabItem label="Orion">Bellatrix, Rigel, Betelgeuse</TabItem>
+	<TabItem label="Gemini">Pollux, Cástor A, Cástor B</TabItem>
+</Tabs>
+
+_Algunos exoplanetas:_
+
+<Tabs syncKey="constellations">
+	<TabItem label="Orion">HD 34445 b, Gliese 179 b, Wasp-82 b</TabItem>
+	<TabItem label="Gemini">Pollux b, HAT-P-24b, HD 50554 b</TabItem>
+</Tabs>
+
 ### Tarjetas
 
 import { Card, CardGrid } from '@astrojs/starlight/components';

diff --git a/docs/src/content/docs/es/guides/css-and-tailwind.mdx b/docs/src/content/docs/es/guides/css-and-tailwind.mdx
@@ -63,7 +63,7 @@ El plugin Starlight Tailwind aplica la siguiente configuración:
 
 Empieza un nuevo proyecto en Starlight con Tailwind CSS preconfigurado usando `create astro`:
 
-<Tabs>
+<Tabs syncKey="pkg">
 <TabItem label="npm">
 
 ```sh
@@ -95,7 +95,7 @@ Si ya tienes un sitio en Starlight y quieres agregar Tailwind CSS, sigue estos p
 
 1.  Agrega la integración de Tailwind de Astro:
 
-    <Tabs>
+    <Tabs syncKey="pkg">
 
     <TabItem label="npm">
 
@@ -125,7 +125,7 @@ Si ya tienes un sitio en Starlight y quieres agregar Tailwind CSS, sigue estos p
 
 2.  Instala el plugin Starlight Tailwind:
 
-    <Tabs>
+    <Tabs syncKey="pkg">
 
     <TabItem label="npm">
 

diff --git a/docs/src/content/docs/es/guides/customization.mdx b/docs/src/content/docs/es/guides/customization.mdx
@@ -127,7 +127,7 @@ Starlight muestra una tabla de contenidos en cada página para facilitar que los
 
 De forma predeterminada, los encabezados `<h2>` y `<h3>` se incluyen en la tabla de contenidos. Puedes cambiar qué niveles de encabezados se incluyen en toda la página utilizando las opciones `minHeadingLevel` y `maxHeadingLevel` en tu configuración [global de `tableOfContents`](/es/reference/configuration/#tableofcontents). Puedes anular estas configuraciones predeterminadas en una página individual agregando las propiedades correspondientes de [`tableOfContents` en el frontmatter](/es/reference/frontmatter/#tableofcontents):
 
-<Tabs>
+<Tabs syncKey="config-type">
   <TabItem label="Frontmatter">
 
 ```md {4-6}
@@ -161,7 +161,7 @@ defineConfig({
 
 Desactiva completamente la tabla de contenidos estableciendo la opción `tableOfContents` en `false`:
 
-<Tabs>
+<Tabs syncKey="config-type">
   <TabItem label="Frontmatter">
 
 ```md {4}

diff --git a/docs/src/content/docs/es/guides/i18n.mdx b/docs/src/content/docs/es/guides/i18n.mdx
@@ -142,6 +142,34 @@ Starlight espera que crees páginas equivalentes en todos tus idiomas. Por ejemp
 
 Si no hay una traducción disponible para un idioma, Starlight mostrará a los lectores el contenido de esa página en el idioma predeterminado (establecido mediante `defaultLocale`). Por ejemplo, si aún no has creado una versión en francés de tu página Acerca de y tu idioma predeterminado es el inglés, los visitantes a `/fr/about` verán el contenido en inglés de `/en/about` con un aviso de que esta página aún no se ha traducido. Esto te ayuda a agregar contenido en tu idioma predeterminado y luego traducirlo progresivamente cuando tus traductores tengan tiempo.
 
+## Traduce el título del sitio
+
+Por defecto, Starlight usará el mismo título del sitio para todos los idiomas.
+Si necesitas personalizar el título para cada idioma, puedes pasar un objeto a [`title`](/es/reference/configuration/#title-requerido) en las opciones de Starlight:
+
+```diff lang="js"
+// astro.config.mjs
+import { defineConfig } from 'astro/config';
+import starlight from '@astrojs/starlight';
+
+export default defineConfig({
+	integrations: [
+		starlight({
+-			title: 'Mi Documentación',
++			title: {
++				es: 'Mi Documentación',
++				'zh-CN': '我的文档',
++			},
+			defaultLocale: 'es',
+			locales: {
+				es: { label: 'Español' },
+				'zh-cn': { label: '简体中文', lang: 'zh-CN' },
+			},
+		}),
+	],
+});
+```
+
 ## Traduce la UI de Starlight
 
 import LanguagesList from '~/components/languages-list.astro';

diff --git a/docs/src/content/docs/es/guides/pages.mdx b/docs/src/content/docs/es/guides/pages.mdx
@@ -105,6 +105,7 @@ Las siguientes propiedades difieren del frontmatter de Markdown:
 - La propiedad [`slug`](/es/reference/frontmatter/#slug) no es compatible y se establece automáticamente en función de la URL de la página personalizada.
 - La opción [`editUrl`](/es/reference/frontmatter/#editurl) requiere una URL para mostrar un enlace de edición.
 - La propiedad frontmatter [`sidebar`](/es/reference/frontmatter/#sidebar) para personalizar cómo aparece la página en [grupos de enlaces autogenerados](/es/reference/configuration/#sidebar) no está disponible. Las páginas que utilizan el componente `<StarlightPage />` no forman parte de una colección y no pueden ser agregadas a un grupo de barra lateral autogenerado.
+- La opción [`draft`](/es/reference/frontmatter/#draft) solo muestra un [aviso](/es/reference/overrides/#draftcontentnotice) de que la página es un borrador, pero no la excluye automáticamente de las compilaciones de producción.
 
 ##### `sidebar`
 

diff --git a/docs/src/content/docs/es/reference/configuration.mdx b/docs/src/content/docs/es/reference/configuration.mdx
@@ -24,10 +24,22 @@ Puedes pasar las siguientes opciones a la integración `starlight`.
 
 ### `title` (requerido)
 
-**tipo:** `string`
+**tipo:** `string | Record<string, string>`
 
 Establece el título de tu sitio web. Se utilizará en los metadatos y en el título de la pestaña del navegador.
 
+El valor puede ser un string o para sitios multilingües, un objeto con valores para cada idioma diferente.
+Cuando se usa la forma de objeto, las claves deben ser etiquetas BCP-47 (por ejemplo, `en`, `ar` o `zh-CN`):
+
+```ts
+starlight({
+	title: {
+		es: 'Mi encantador sitio de documentación',
+		de: 'Meine bezaubernde Dokumentationsseite',
+	},
+});
+```
+
 ### `description`
 
 **tipo:** `string`

diff --git a/docs/src/content/docs/es/reference/frontmatter.md b/docs/src/content/docs/es/reference/frontmatter.md
@@ -270,6 +270,21 @@ pagefind: false
 ---
 ```
 
+### `draft`
+
+**tipo:** `boolean`  
+**por defecto:** `false`
+
+Establece si esta página debe considerarse como un borrador y no incluirse en las [compilaciones de producción](https://docs.astro.build/es/reference/cli-reference/#astro-build) y [grupos de enlaces autogenerados](/es/guides/sidebar/#grupos-autogenerados). Establece en `true` para marcar una página como borrador y hacerla visible solo durante el desarrollo.
+
+```md
+---
+# src/content/docs/example.md
+# Excluye esta página de las compilaciones de producción
+draft: true
+---
+```
+
 ### `sidebar`
 
 **tipo:** [`SidebarConfig`](#sidebarconfig)

diff --git a/docs/src/content/docs/es/reference/overrides.md b/docs/src/content/docs/es/reference/overrides.md
@@ -51,6 +51,12 @@ Etiqueta de idioma BCP-47 para la configuración regional de esta página, por e
 
 La ruta base en la que se sirve un idioma. `undefined` para los slugs de idioma raíz.
 
+#### `siteTitle`
+
+**Tipo:** `string`
+
+El título del sitio para el idioma de esta página.
+
 #### `slug`
 
 **Tipo:** `string`
@@ -219,7 +225,7 @@ Estos componentes renderizan la barra de navegación superior de Starlight.
 **Componente por defecto:** [`Header.astro`](https://github.com/withastro/starlight/blob/main/packages/starlight/components/Header.astro)
 
 Componente de encabezado que se muestra en la parte superior de cada página.
-La implementación predeterminada muestra [`<SiteTitle />`](#sitetitle), [`<Search />`](#search), [`<SocialIcons />`](#socialicons), [`<ThemeSelect />`](#themeselect) y [`<LanguageSelect />`](#languageselect).
+La implementación predeterminada muestra [`<SiteTitle />`](#sitetitle-1), [`<Search />`](#search), [`<SocialIcons />`](#socialicons), [`<ThemeSelect />`](#themeselect) y [`<LanguageSelect />`](#languageselect).
 
 #### `SiteTitle`
 
@@ -331,6 +337,12 @@ Componente que contiene el elemento `<h1>` de la página actual.
 
 Las implementaciones deben asegurarse de establecer `id="_top"` en el elemento `<h1>` como en la implementación predeterminada.
 
+#### `DraftContentNotice`
+
+**Componente por defecto:** [`DraftContentNotice.astro`](https://github.com/withastro/starlight/blob/main/packages/starlight/components/DraftContentNotice.astro)
+
+Aviso mostrado a los usuarios durante el desarrollo cuando la página actual está marcada como borrador.
+
 #### `FallbackContentNotice`
 
 **Componente por defecto:** [`FallbackContentNotice.astro`](https://github.com/withastro/starlight/blob/main/packages/starlight/components/FallbackContentNotice.astro)

diff --git a/docs/src/content/docs/es/resources/community-content.mdx b/docs/src/content/docs/es/resources/community-content.mdx
@@ -128,5 +128,12 @@ import YouTubeGrid from '~/components/youtube-grid.astro';
 			description:
 				'Pon en marcha un nuevo sitio de Starlight en unos 5 minutos',
 		},
+		{
+			href: 'https://www.youtube.com/watch?v=12o7WxjAxjM',
+			title:
+				'Incluye la documentación de Starlight en un proyecto de Next.js con proxies',
+			description:
+				'Configura Starlight como un proyecto de subdirectorio dentro de un sitio web de Next.js',
+		},
 	]}
 />
diff --git a/docs/src/content/docs/fr/getting-started.mdx b/docs/src/content/docs/fr/getting-started.mdx
@@ -15,7 +15,7 @@ Consultez les [instructions d'installation manuelle](/fr/manual-setup/) pour ajo
 
 Créez un nouveau projet Astro + Starlight en lançant la commande suivante dans votre terminal :
 
-<Tabs>
+<Tabs syncKey="pkg">
 <TabItem label="npm">
 
 ```sh
@@ -52,7 +52,7 @@ Lorsque vous travaillez localement, [le serveur de développement d'Astro](https
 
 À l'intérieur du répertoire de votre projet, exécutez la commande suivante pour démarrer le serveur de développement :
 
-<Tabs>
+<Tabs syncKey="pkg">
 <TabItem label="npm">
 
 ```sh
@@ -103,7 +103,7 @@ Assurez-vous de mettre à jour Starlight régulièrement !
 
 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>
+<Tabs syncKey="pkg">
 <TabItem label="npm">
 
 ```sh