Merge branch 'main' into hd-pagefind-1-1-0

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

Hide file tree

Showing 163 changed files with 2,921 additions and 1,729 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/.github/workflows/lunaria.yml b/.github/workflows/lunaria.yml
@@ -0,0 +1,46 @@
+name: Lunaria
+
+on:
+  # Trigger the workflow every time a pull request is opened or synchronized at the target `main` branch
+  pull_request_target:
+    types: [opened, synchronize]
+    branches: [main]
+    paths:
+      - 'docs/**'
+
+# Allow this job to clone the repository and comment on the pull request
+permissions:
+  contents: read
+  pull-requests: write
+
+jobs:
+  lunaria-overview:
+    name: Generate Lunaria Overview
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+        with:
+          # Necessary for Lunaria to work properly
+          # Makes the action clone the entire git history
+          fetch-depth: 0
+
+      - name: Setup PNPM
+        uses: pnpm/action-setup@v3
+
+      - name: Setup Node
+        uses: actions/setup-node@v4
+        with:
+          node-version: 20
+          cache: pnpm
+
+      - name: Install dependencies
+        run: pnpm install
+        shell: bash
+
+      - name: Generate Lunaria Overview
+        uses: yanthomasdev/lunaria-action@f60cb4c257e95ab41fc44356c4a852fe614e3bb4
+        with:
+          token: ${{ secrets.FREDKBOT_GITHUB_TOKEN }}
+          working-directory: docs
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/lunaria.config.json b/docs/lunaria.config.json
@@ -73,7 +73,8 @@
   "files": [
     {
       "location": "src/content/docs/**/*.{md,mdx}",
-      "pattern": "src/content/docs/@lang/@path"
+      "pattern": "src/content/docs/@lang/@path",
+      "type": "universal"
     }
   ],
   "dashboard": {

diff --git a/docs/package.json b/docs/package.json
@@ -16,7 +16,7 @@
   "dependencies": {
     "@astro-community/astro-embed-youtube": "^0.4.4",
     "@astrojs/starlight": "workspace:*",
-    "@lunariajs/core": "^0.0.25",
+    "@lunariajs/core": "^0.0.32",
     "@types/culori": "^2.0.0",
     "astro": "^4.3.5",
     "culori": "^3.2.0",

diff --git a/docs/src/assets/showcase/truecharts.org.png b/docs/src/assets/showcase/truecharts.org.png
diff --git a/docs/src/components/showcase-sites.astro b/docs/src/components/showcase-sites.astro
@@ -126,4 +126,5 @@ import FluidGrid from './fluid-grid.astro';
 		href="https://docs.fontawesome.com/"
 		thumbnail="docs.fontawesome.com.png"
 	/>
+	<Card title="TrueCharts" href="https://truecharts.org/" thumbnail="truecharts.org.png" />
 </FluidGrid>
diff --git a/docs/src/components/sidebar-preview.astro b/docs/src/components/sidebar-preview.astro
@@ -17,7 +17,10 @@ function makeEntries(items: SidebarConfig): SidebarEntry[] {
 			return {
 				type: 'link',
 				label: item.label,
-				href: item.link,
+				// Empty hrefs are used to represent internal links that do not exist in the Starlight
+				// docs. Using a non-existing anchor link like `#_` will not trigger a page reload or any
+				// scrolling.
+				href: item.link.length > 0 ? item.link : '#_',
 				isCurrent: false,
 				badge: item.badge,
 				attrs: item.attrs ?? {},

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`