Merge branch 'main' into magicDGS/withastro#978

magicDGS · Nov 1, 2023 · b7bb16b · b7bb16b
2 parents 42aa535 + 92103b9
commit b7bb16b
Show file tree

Hide file tree

Showing 67 changed files with 3,960 additions and 253 deletions.
diff --git a/.changeset/four-pots-cheat.md b/.changeset/four-pots-cheat.md
@@ -0,0 +1,5 @@
+---
+"@astrojs/starlight": patch
+---
+
+Add Galician language support
diff --git a/.changeset/orange-pants-tell.md b/.changeset/orange-pants-tell.md
@@ -0,0 +1,5 @@
+---
+'@astrojs/starlight': minor
+---
+
+Adds support for adding sidebar badges to group headings
diff --git a/.changeset/thick-bats-pay.md b/.changeset/thick-bats-pay.md
@@ -0,0 +1,5 @@
+---
+'@astrojs/starlight-tailwind': patch
+---
+
+Show `tailwind.config.mjs` file in docs
diff --git a/.changeset/violet-berries-mix.md b/.changeset/violet-berries-mix.md
@@ -0,0 +1,12 @@
+---
+'@astrojs/starlight': minor
+---
+
+Support light & dark variants of the hero image.
+
+⚠️ **Potentially breaking change:** The `hero.image` schema is now slightly stricter than previously.
+
+The `hero.image.html` property can no longer be used alongside the `hero.image.alt` or `hero.image.file` properties.
+Previously, `html` was ignored when used with `file` and `alt` was ignored when used with `html`.
+Now, those combinations will throw errors.
+If you encounter errors, remove the `image.hero` property that is not in use.
diff --git a/docs/astro.config.mjs b/docs/astro.config.mjs
@@ -110,7 +110,7 @@ export default defineConfig({
 							label: 'Environmental Impact',
 							link: 'environmental-impact',
 							translations: {
-								// de: '',
+								de: 'Umweltbelastung',
 								es: 'Documentación ecológica',
 								ja: '環境への負荷',
 								fr: 'Impact environnemental',
@@ -127,7 +127,7 @@ export default defineConfig({
 							label: 'Showcase',
 							link: 'showcase',
 							translations: {
-								// de: '',
+								de: 'Schaufenster',
 								// es: '',
 								ja: 'ショーケース',
 								fr: 'Vitrine',

diff --git a/docs/src/assets/showcase/react-awesome-reveal.morello.dev.png b/docs/src/assets/showcase/react-awesome-reveal.morello.dev.png
diff --git a/docs/src/components/showcase-sites.astro b/docs/src/components/showcase-sites.astro
@@ -65,4 +65,9 @@ import FluidGrid from './fluid-grid.astro';
 		thumbnail="ai-prompt-snippets.png"
 	/>
 	<Card title="Folks Router" href="https://folksrouter.io/" thumbnail="folksrouter.io.png" />
+	<Card
+		title="React Awesome Reveal"
+		href="https://react-awesome-reveal.morello.dev/"
+		thumbnail="react-awesome-reveal.morello.dev.png"
+	/>
 </FluidGrid>
diff --git a/docs/src/components/sidebar-preview.astro b/docs/src/components/sidebar-preview.astro
@@ -29,6 +29,7 @@ function makeEntries(items: SidebarConfig): SidebarEntry[] {
 			label: item.label,
 			entries: makeEntries(item.items as SidebarConfig),
 			collapsed: item.collapsed,
+			badge: item.badge,
 		};
 	});
 }

diff --git a/docs/src/components/theme-designer.astro b/docs/src/components/theme-designer.astro
@@ -104,14 +104,14 @@ const {
 		}
 
 		#updateTailwindConfig({ dark, light }: ReturnType<typeof getPalettes>) {
-			const config = `const starlightPlugin = require('@astrojs/starlight-tailwind');
+			const config = `import starlightPlugin from '@astrojs/starlight-tailwind';
 
 // Generated color palettes
 const accent = { 200: '${dark['accent-high']}', 600: '${light.accent}', 900: '${light['accent-high']}', 950: '${dark['accent-low']}' };
 const gray = { 100: '${light['gray-7']}', 200: '${light['gray-6']}', 300: '${light['gray-5']}', 400: '${light['gray-4']}', 500: '${light['gray-3']}', 700: '${light['gray-2']}', 800: '${light['gray-1']}', 900: '${light.white}' };
 
 /** @type {import('tailwindcss').Config} */
-module.exports = {
+export default {
 	content: ['./src/**/*.{astro,html,js,jsx,md,mdx,svelte,ts,tsx,vue}'],
 	theme: {
 		extend: {

diff --git a/docs/src/components/theme-designer/preview.astro b/docs/src/components/theme-designer/preview.astro
@@ -21,9 +21,9 @@ const codeBg = light ? '--sl-color-gray-6' : '--sl-color-gray-5';
 <div class="preview-card" {...attrs}>
 	<h4>{light ? labels.lightMode : labels.darkMode}</h4>
 	<p>
-		{labels.bodyText}
-		<span class="link" style={`color:var(${linkColor})`}>{labels.linkText}</span>
-		<span class="dim">{labels.dimText}</span>
+		{labels.bodyText}{' '}
+		<span class="link" style={`color:var(${linkColor})`}>{labels.linkText}</span>{' '}
+		<span class="dim">{labels.dimText}</span>{' '}
 		<code style={`--sl-color-bg-inline-code:var(${codeBg})`}>{labels.inlineCode}</code>
 	</p>
 	<Palette {light} />

diff --git a/docs/src/content/docs/de/environmental-impact.md b/docs/src/content/docs/de/environmental-impact.md
@@ -0,0 +1,140 @@
+---
+title: Umweltfreundliche Dokumente
+description: Erfahre, wie Starlight dir helfen kann, umweltfreundlichere Dokumentationen zu erstellen und deinen ökologischen Fußabdruck zu verringern.
+---
+
+Schätzungen über die Auswirkungen der Webindustrie auf das Klima liegen zwischen [2 %][sf] und [4 % der weltweiten Kohlenstoffemissionen][bbc], was in etwa den Emissionen der Luftfahrtindustrie entspricht.
+Es gibt viele komplexe Faktoren bei der Berechnung der ökologischen Auswirkungen einer Website, aber dieser Leitfaden enthält einige Tipps, wie du den ökologischen Fußabdruck deiner Docs-Website verringern kannst.
+
+Die gute Nachricht ist, dass die Wahl von Starlight ein guter Anfang ist.
+Laut dem Website Carbon Calculator ist diese Website [sauberer als 99 % der getesteten Websiten][sl-carbon] und erzeugt 0,01g CO₂ pro Seitenbesuch.
+
+## Seitengewicht
+
+Je mehr Daten eine Website überträgt, desto mehr Energieressourcen benötigt sie.
+Im April 2023 musste ein Nutzer laut [Daten aus dem HTTP-Archiv][http] für die durchschnittliche Website mehr als 2.000 KB herunterladen.
+
+Starlight erstellt Seiten, die so leicht wie möglich sind.
+So lädt ein Benutzer beim ersten Besuch weniger als 50 KB an komprimierten Daten herunter - nur 2,5 % des Medianwerts des HTTP-Archivs.
+Mit einer guten Caching-Strategie können nachfolgende Besuche sogar nur 10 KB herunterladen.
+
+### Bilder
+
+Während Starlight eine gute Grundlage bietet, können Bilder, die du deinen Dokumentseiten hinzufügst, das Seitengewicht schnell erhöhen.
+Starlight nutzt die [optimierte Asset-Unterstützung][Assets] von Astro, um lokale Bilder in deinen Markdown- und MDX-Dateien zu optimieren.
+
+### UI-Komponenten
+
+Komponenten, die mit UI-Frameworks wie React oder Vue erstellt wurden, können leicht große Mengen an JavaScript zu einer Seite hinzufügen.
+Da Starlight auf Astro aufbaut, laden Komponenten wie diese dank [Astro Islands][islands] standardmäßig **kein clientseitiges JavaScript**.
+
+### Caching
+
+Caching wird verwendet, um zu kontrollieren, wie lange ein Browser Daten speichert und wiederverwendet, die er bereits heruntergeladen hat.
+Eine gute Caching-Strategie stellt sicher, dass ein Benutzer neue Inhalte so schnell wie möglich erhält, wenn sich diese ändern, vermeidet aber auch, dass derselbe Inhalt unnötigerweise immer wieder heruntergeladen wird, wenn er sich nicht geändert hat.
+
+Die gebräuchlichste Art, das Zwischenspeichern zu konfigurieren, ist der [`Cache-Control` HTTP-Header][cache].
+Wenn du Starlight verwendest, kannst du eine lange Cache-Zeit für alles im Verzeichnis `/_astro/` einstellen.
+Dieses Verzeichnis enthält CSS, JavaScript und andere gebündelte Inhalte, die sicher für immer zwischengespeichert werden können, wodurch unnötige Downloads vermieden werden:
+
+```
+Cache-Control: public, max-age=604800, immutable
+```
+
+Wie du das Caching konfigurierst, hängt von deinem Webhost ab. Zum Beispiel wendet Vercel diese Caching-Strategie für dich an, ohne dass eine Konfiguration erforderlich ist, während du [benutzerdefinierte Header für Netlify][ntl-headers] einstellen kannst, indem du eine `public/_headers`-Datei zu deinem Projekt hinzufügst:
+
+```
+/_astro/*
+  Cache-Control: public
+  Cache-Control: max-age=604800
+  Cache-Control: immutable
+```
+
+[cache]: https://csswizardry.com/2019/03/cache-control-for-civilians/
+[ntl-headers]: https://docs.netlify.com/routing/headers/
+
+## Stromverbrauch
+
+Die Art und Weise, wie eine Website aufgebaut ist, kann sich auf den Stromverbrauch auswirken, den sie auf dem Gerät des Benutzers benötigt.
+Durch die Verwendung von minimalem JavaScript reduziert Starlight die Rechenleistung, die das Telefon, Tablet oder der Computer eines Nutzers zum Laden und Rendern von Seiten benötigt.
+
+Sei jedoch vorsichtig, wenn du Funktionen wie analytische Tracking-Skripte oder JavaScript-lastige Inhalte wie Videoeinbettungen hinzufügst, da diese den Stromverbrauch der Seite erhöhen können.
+Wenn du Analysen benötigst, solltest du eine schlanke Option wie [Cabin][cabin], [Fathom][fathom] oder [Plausible][plausible] wählen.
+Einbettungen wie YouTube- und Vimeo-Videos können verbessert werden, indem man auf [Laden des Videos bei Benutzerinteraktion][lazy-video] wartet.
+Pakete wie [`astro-embed`][embed] können bei gängigen Diensten helfen.
+
+:::tip[Wusstest du schon?]
+Das Parsen und Kompilieren von JavaScript ist eine der aufwändigsten Aufgaben, die ein Browser zu erledigen hat.
+Verglichen mit dem Rendern eines JPEG-Bildes derselben Größe kann die [Verarbeitung von JavaScript mehr als 30 Mal so lange dauern][cost-of-js].
+:::
+
+[cabin]: https://withcabin.com/
+[fathom]: https://usefathom.com/
+[plausible]: https://plausible.io/
+[lazy-video]: https://web.dev/iframe-lazy-loading/
+[embed]: https://www.npmjs.com/package/astro-embed
+[cost-of-js]: https://medium.com/dev-channel/the-cost-of-javascript-84009f51e99e
+
+## Hosting
+
+Wo eine Website gehostet wird, kann einen großen Einfluss darauf haben, wie umweltfreundlich deine Dokumentationsseite ist.
+Rechenzentren und Serveranlagen können große ökologische Auswirkungen haben, einschließlich eines hohen Stromverbrauchs und eines intensiven Wasserverbrauchs.
+
+Wenn du dich für einen Hoster entscheidest, der erneuerbare Energien einsetzt, wird deine Website weniger Kohlenstoffemissionen verursachen. Das [Green Web Directory][gwb] ist ein Tool, das dir helfen kann, Hosting-Unternehmen zu finden.
+
+[gwb]: https://www.thegreenwebfoundation.org/directory/
+
+## Vergleiche
+
+Bist du neugierig, wie andere Docs-Frameworks im Vergleich abschneiden?
+Diese Tests mit dem [Website Carbon Calculator][wcc] vergleichen ähnliche Seiten, die mit verschiedenen Tools erstellt wurden.
+
+| Framework                   | CO₂ pro Seitenaufruf |
+| --------------------------- | -------------------- |
+| [Starlight][sl-carbon]      | 0.01g                |
+| [VitePress][vp-carbon]      | 0.05g                |
+| [Docus][dc-carbon]          | 0.05g                |
+| [Sphinx][sx-carbon]         | 0.07g                |
+| [MkDocs][mk-carbon]         | 0.10g                |
+| [Nextra][nx-carbon]         | 0.11g                |
+| [docsify][dy-carbon]        | 0.11g                |
+| [Docusaurus][ds-carbon]     | 0.24g                |
+| [Read the Docs][rtd-carbon] | 0.24g                |
+| [GitBook][gb-carbon]        | 0.71g                |
+
+<small>Daten erhoben am 14. Mai 2023. Klicke auf einen Link, um aktuelle Zahlen zu sehen.</small>
+
+[sl-carbon]: https://www.websitecarbon.com/website/starlight-astro-build-getting-started/
+[vp-carbon]: https://www.websitecarbon.com/website/vitepress-dev-guide-what-is-vitepress/
+[dc-carbon]: https://www.websitecarbon.com/website/docus-dev-introduction-getting-started/
+[sx-carbon]: https://www.websitecarbon.com/website/sphinx-doc-org-en-master-usage-quickstart-html/
+[mk-carbon]: https://www.websitecarbon.com/website/mkdocs-org-getting-started/
+[nx-carbon]: https://www.websitecarbon.com/website/nextra-site-docs-docs-theme-start/
+[dy-carbon]: https://www.websitecarbon.com/website/docsify-js-org/
+[ds-carbon]: https://www.websitecarbon.com/website/docusaurus-io-docs/
+[rtd-carbon]: https://www.websitecarbon.com/website/docs-readthedocs-io-en-stable-index-html/
+[gb-carbon]: https://www.websitecarbon.com/website/docs-gitbook-com/
+
+## Weitere Ressourcen
+
+### Werkzeuge
+
+- [Website Carbon Calculator][wcc]
+- [GreenFrame](https://greenframe.io/)
+- [Ecograder](https://ecograder.com/)
+- [WebPageTest Kohlenstoffkontrolle](https://www.webpagetest.org/carbon-control/)
+- [Ecoping](https://ecoping.earth/)
+
+### Artikel und Vorträge
+
+- ["Building a greener web"](https://youtu.be/EfPoOt7T5lg), Vortrag von Michelle Barker
+- ["Sustainable Web Development Strategies Within An Organization"](https://www.smashingmagazine.com/2022/10/sustainable-web-development-strategies-organization/), Artikel von Michelle Barker
+- ["A sustainable web for everyone"](https://2021.stateofthebrowser.com/speakers/tom-greenwood/), Vortrag von Tom Greenwood
+- ["How Web Content Can Affect Power Usage"](https://webkit.org/blog/8970/how-web-content-can-affect-power-usage/), Artikel von Benjamin Poulain und Simon Fraser
+
+[sf]: https://www.sciencefocus.com/science/what-is-the-carbon-footprint-of-the-internet/
+[bbc]: https://www.bbc.com/future/article/20200305-why-your-internet-habits-are-not-as-clean-as-you-think
+[http]: https://httparchive.org/reports/state-of-the-web
+[assets]: https://docs.astro.build/en/guides/assets/
+[islands]: https://docs.astro.build/en/concepts/islands/
+[wcc]: https://www.websitecarbon.com/
diff --git a/docs/src/content/docs/de/getting-started.mdx b/docs/src/content/docs/de/getting-started.mdx
@@ -38,7 +38,7 @@ yarn create astro --template starlight
 </TabItem>
 </Tabs>
 
-Damit wird ein neues [Projektverzeichnis](/de/guides/project-structure/) mit allen erforderlichen Dateien und Konfigurationen für deine Webseite erstellt.
+Damit wird ein neues [Projektverzeichnis](/de/guides/project-structure/) mit allen erforderlichen Dateien und Konfigurationen für deine Website erstellt.
 
 :::tip[In Aktion sehen]
 Probiere Starlight in deinem Browser aus:
@@ -55,7 +55,7 @@ Starlight unterstützt das Erstellen von Inhalten in Markdown und MDX. (Du kanns
 
 ### Seiten hinzufügen
 
-Füge neue Seiten zu deiner Webseite automatisch hinzu, indem du `.md` oder `.mdx` Dateien in `src/content/docs/` erstellst. Erstelle Unterordner, um deine Dateien zu organisieren und mehrere Pfadsegmente zu erstellen:
+Füge neue Seiten zu deiner Website automatisch hinzu, indem du `.md` oder `.mdx` Dateien in `src/content/docs/` erstellst. Erstelle Unterordner, um deine Dateien zu organisieren und mehrere Pfadsegmente zu erstellen:
 
 ```
 src/content/docs/hello-world.md => your-site.com/hello-world
@@ -75,15 +75,15 @@ description: This is a page in my Starlight-powered site
 
 Wenn du etwas Wichtiges vergisst, wird Starlight dich daran erinnern.
 
-## Veröffentlichung deiner Starlight Webseite
+## Veröffentlichung deiner Starlight-Website
 
-Sobald du deine Starlight Webseite erstellt und angepasst hast, kannst du sie auf einen Webserver oder Hosting-Plattform deiner Wahl veröffentlichen, einschließlich Netlify, Vercel, GitHub Pages und vielen mehr.
+Sobald du deine Starlight Website erstellt und angepasst hast, kannst du sie auf einen Webserver oder Hosting-Plattform deiner Wahl veröffentlichen, einschließlich Netlify, Vercel, GitHub Pages und vielen mehr.
 
-[Lerne mehr über die Veröffentlichung einer Astro Webseite in der Astro Dokumentation.](https://docs.astro.build/de/guides/deploy/)
+[Lerne mehr über die Veröffentlichung einer Astro-Website in der Astro-Dokumentation.](https://docs.astro.build/de/guides/deploy/)
 
 ## Starlight aktualisieren
 
-:::tip
+:::tip[Tipp]
 Da es sich bei Starlight um eine Beta-Software handelt, wird es regelmäßig Updates und Verbesserungen geben. Achte darauf Starlight regelmäßig zu aktualisieren!
 :::
 
@@ -124,6 +124,6 @@ Sowohl die Starlight [Projektkonfiguration](/reference/configuration/) als auch
 
 In der wachsenden Liste der Anleitungen in der Seitenleiste findest du Hilfe beim Hinzufügen von Inhalten und beim Anpassen deiner Starlight-Website.
 
-Wenn du keine Antwort in dieser Dokumentation finden kannst, besuche bitte die [Astro Docs](https://docs.astro.build) für die vollständige Astro-Dokumentation. Deine Frage kann vielleicht beantwortet werden, wenn du verstehst, wie Astro im Allgemeinen funktioniert.
+Wenn du keine Antwort in dieser Dokumentation finden kannst, besuche bitte die [Astro Docs](https://docs.astro.build/de/) für die vollständige Astro-Dokumentation. Deine Frage kann vielleicht beantwortet werden, wenn du verstehst, wie Astro im Allgemeinen funktioniert.
 
-Du kannst auch im [Astro Discord](https://astro.build/chat/) Hilfe von unserer aktiven, freundlichen Community bekommen. Du kannst Fragen in unserem `#Support`-Forum stellen oder unseren speziellen `#starlight`-Channel besuchen, um aktuelle Entwicklungen und mehr zu diskutieren.
+Du kannst auch nach bekannten [Starlight-Problemen auf GitHub](https://github.com/withastro/starlight/issues) suchen und im [Astro Discord](https://astro.build/chat/) Hilfe von unserer aktiven, freundlichen Community erhalten! Du kannst Fragen in unserem `#Support`-Forum stellen oder unseren speziellen `#starlight`-Channel besuchen, um aktuelle Entwicklungen und mehr zu diskutieren.