Merge branch 'main' into hd-feat-tabs-sync

* main: (440 commits)
  i18n(fr): update `getting-started.mdx` (withastro#1245)
  [ci] format
  docs(showcase): add csmos.space (withastro#1269)
  [ci] format
  docs: add SiteOne Crawler to showcase (withastro#1264)
  Fix formatting
  [ci] format
  docs(i18n): Add Indonesian translation for site search documentation (withastro#1250)
  i18n(es): fix typo (withastro#1246)
  i18n(ja): Update getting-started.mdx (withastro#1252)
  i18n(es): Update `getting-started.mdx` (withastro#1247)
  i18n(ko-KR): update `getting-started.mdx` (withastro#1248)
  Update upgrade instructions to show new `@astrojs/upgrade` (withastro#1241)
  [ci] format
  [ci] release (withastro#1240)
  i18n(ru): Fix typo in `i18n.untranslatedContent` (withastro#1243)
  Fix timezone-reliance in LastUpdated (withastro#1170)
  Prefetch links on hover by default (withastro#1242)
  Add support for Astro v4, drop support for Astro v3 (withastro#1238)
  Add Matrix social icon (withastro#1203)
  ...

.github/ISSUE_TEMPLATE/---02-feature-request.yml → .github/DISCUSSION_TEMPLATE/feature-requests.yml

@@ -1,7 +1,3 @@
-name: Feature Request
-description: Suggest an improvement you’d like to see added to Starlight
-labels: []
-assignees: []
 body:
   - type: markdown
     attributes:
@@ -46,5 +42,5 @@ body:
       label: Participation
       description: Let us know if your interested in contributing this feature yourself.
       options:
-        - label: I am willing to submit a pull request for this issue.
+        - label: I am willing to submit a pull request for this feature.
           required: false

.github/ISSUE_TEMPLATE/---01-bug-report.yml

@@ -58,6 +58,8 @@ body:
       label: Link to Minimal Reproducible Example
       description: 'Use [astro.new](https://astro.new) to create a minimal reproduction of the problem. **A minimal reproduction is required** so that others can help debug your issue. If a report is vague (e.g. just a generic error message) and has no reproduction, it may be auto-closed. Not sure how to create a minimal example? [Read our guide](https://docs.astro.build/en/guides/troubleshooting/#creating-minimal-reproductions)'
       placeholder: 'https://stackblitz.com/abcd1234'
+    validations:
+      required: true
   - type: checkboxes
     id: will-pr
     attributes:

.github/ISSUE_TEMPLATE/config.yml

@@ -1,5 +1,8 @@
 blank_issues_enabled: false
 contact_links:
+  - name: 💡 Feature Request
+    url: https://github.com/withastro/starlight/discussions/new?category=feature-requests
+    about: Suggest an improvement you’d like to see added to Starlight
   - name: 👾 Chat
     url: https://astro.build/chat
     about: Our Discord server is active, come join us!

.github/PULL_REQUEST_TEMPLATE.md

@@ -1,14 +1,5 @@
 <!-- Thank you for opening a PR! We really appreciate you taking the time to help out 🙌 -->
 
-#### What kind of changes does this PR include?
-
-<!-- Delete any that don’t apply -->
-
-- Minor content fixes (broken links, typos, etc.)
-- Changes or translations of Starlight docs site content
-- Changes to Starlight code
-- Something else!
-
 #### Description
 
 - Closes # <!-- Add an issue number if this PR will close it. -->

.github/labeler.yml

@@ -9,9 +9,13 @@ i18n:
   - docs/src/content/docs/fr/**/*
   - docs/src/content/docs/it/**/*
   - docs/src/content/docs/ja/**/*
-  - docs/src/content/docs/zh/**/*
+  - docs/src/content/docs/zh-cn/**/*
   - docs/src/content/docs/pt-br/**/*
   - docs/src/content/docs/ko/**/*
+  - docs/src/content/docs/ru/**/*
+  - docs/src/content/docs/id/**/*
+  - docs/src/content/docs/tr/**/*
+  - docs/src/content/docs/hi/**/*
 
 '🌟 core':
   - packages/starlight/**

.github/workflows/ci.yml

@@ -87,3 +87,20 @@ jobs:
       - name: Build docs site
         working-directory: ./docs
         run: pnpm build
+
+  docs-i18n-tracker-smoke:
+    name: Docs i18n tracker builds
+    runs-on: ubuntu-20.04
+    steps:
+      - uses: actions/checkout@v3
+        with:
+          fetch-depth: 0
+      - uses: pnpm/action-setup@v2
+      - uses: actions/setup-node@v3
+        with:
+          node-version: ${{ env.NODE_VERSION }}
+          cache: 'pnpm'
+      - run: pnpm i
+      - name: Build docs i18n tracker
+        working-directory: ./docs-i18n-tracker
+        run: pnpm build

.github/workflows/size-limit.yml

@@ -10,17 +10,28 @@ concurrency:
   cancel-in-progress: true
 
 jobs:
+  # This basic check runs size-limit for the current branch.
+  # It will fail if the branch pushes the size over the specified budget.
+  size-limit-basic:
+    if: ${{ github.event.pull_request.head.repo.full_name != 'withastro/starlight' }}
+    name: Check build output is within performance budget (forks)
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: pnpm/action-setup@v2
+      - run: pnpm i
+      - run: 'pnpm build:examples'
+      - run: pnpm size
+
+  # This check cannot run in forks, so is only run for PRs from this repo.
+  # It will run size-limit for both `main` and the PR branch and comment in the PR with changes.
   size-limit:
     if: ${{ github.event.pull_request.head.repo.full_name == 'withastro/starlight' }}
     name: Check build output is within performance budget
     runs-on: ubuntu-latest
     steps:
-      - name: Checkout
-        uses: actions/checkout@v3
-
-      - name: Setup PNPM
-        uses: pnpm/action-setup@v2
-
+      - uses: actions/checkout@v4
+      - uses: pnpm/action-setup@v2
       - name: Run size-limit
         uses: andresz1/size-limit-action@dd31dce7dcc72a041fd3e49abf0502b13fc4ce05
         with:

.github/workflows/welcome-bot.yml

@@ -0,0 +1,32 @@
+name: WelcomeBot
+
+on:
+  pull_request_target:
+    branches: [main]
+    types: [opened]
+
+permissions:
+  pull-requests: write
+
+jobs:
+  welcome:
+    name: Welcome First-Time Contributors
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v3
+      - uses: zephyrproject-rtos/action-first-interaction@7e6446f8439d8b4399169880c36a3a12b5747699
+        with:
+          repo-token: ${{ secrets.FREDKBOT_GITHUB_TOKEN }}
+          pr-opened-message: |
+            Hello! Thank you for opening your **first PR** to Starlight! ✨
+
+            Here’s what will happen next:
+
+            1. Our GitHub bots will run to check your changes.
+               If they spot any issues you will see some error messages on this PR.
+               Don’t hesitate to ask any questions if you’re not sure what these mean!
+
+            2. In a few minutes, you’ll be able to see a preview of your changes on Vercel 🤩
+
+            3. One or more of our maintainers will take a look and may ask you to make changes.
+               We try to be responsive, but don’t worry if this takes a few days.

.gitignore

@@ -16,3 +16,6 @@ pnpm-debug.log*
 
 # Vitest
 __coverage__/
+
+# Vercel output
+.vercel

.prettierignore

@@ -10,4 +10,7 @@
 .changeset
 
 # Files
-pnpm-lock.yaml
+pnpm-lock.yaml
+
+# Test snapshots
+**/__tests__/**/snapshots

CONTRIBUTING.md

@@ -89,6 +89,15 @@ You can [develop locally](#developing-locally) or use an online coding developme
 
 The dev container used for GitHub Codespaces can also be used with [other supporting tools](https://containers.dev/supporting), including VS Code.
 
+### Making a Pull Request
+
+When making a pull request containing changes impacting users to Starlight or any related packages (`packages/*`), be sure to [add a changeset](https://github.com/changesets/changesets/blob/main/docs/adding-a-changeset.md#i-am-in-a-multi-package-repository-a-mono-repo) that will describe the changes to users.
+Documentation-only (`docs/*`) and non-package (`examples/*`) changes do not need changesets.
+
+```sh
+pnpm exec changeset
+```
+
 ## Testing
 
 ### Testing visual changes while you work
@@ -125,7 +134,7 @@ This will run tests and then listen for changes, re-running tests when files cha
 A lot of Starlight code relies on Vite virtual modules provided either by Astro or by Starlight itself. Each subdirectory of `packages/starlight/__tests__/` should contain a `vitest.config.ts` file that uses the `defineVitestConfig()` helper to define a valid test environment for tests in that directory. This helper takes a single argument, which provides a Starlight user config object:
 
 ```ts
-// packages/starlight/__tests/basics/vitest.config.ts
+// packages/starlight/__tests__/basics/vitest.config.ts
 import { defineVitestConfig } from '../test-config';
 
 export default defineVitestConfig({
@@ -219,6 +228,17 @@ Help out by:
 
 Visit **<https://i18n.starlight.astro.build>** to track translation progress for the currently supported languages.
 
+#### Adding a new language to Starlight’s docs
+
+To add a language, you will need its BCP-47 tag and a label. See [“Adding a new language”](https://github.com/withastro/docs/blob/main/contributor-guides/translating-astro-docs.md#adding-a-new-language) in the Astro docs repo for some helpful tips around choosing these.
+
+- Add your language to the `locales` config in `docs/astro.config.mjs`
+- Add your language’s subtag to the i18n label config in `.github/labeler.yml`
+- Add your language to the `pa11y` script’s `--sitemap-exclude` flag in `package.json`
+- Create the first translated page for your language.  
+   This must be the Starlight landing page: `docs/src/content/docs/{language}/index.mdx`.
+- Open a pull request on GitHub to add your changes to Starlight!
+
 ## Understanding Starlight
 
 - Starlight is built as an Astro integration.
@@ -236,6 +256,10 @@ Visit **<https://i18n.starlight.astro.build>** to track translation progress for
 - Components that require JavaScript for their functionality are all written without a UI framework, most often as custom elements.
   This helps keep Starlight lightweight and makes it easier for a user to choose to add components from a framework of their choice to their project.
 
+- Components that require client-side JavaScript or CSS should use JavaScript/CSS features that are well-supported by browsers.
+
+  You can find a list of supported browsers and their versions using this [browserslist query](https://browsersl.ist/#q=%3E+0.5%25%2C+not+dead%2C+Chrome+%3E%3D+88%2C+Edge+%3E%3D+88%2C+Firefox+%3E%3D+98%2C+Safari+%3E%3D+15.4%2C+iOS+%3E%3D+15.4%2C+not+op_mini+all). To check whether or not a feature is supported, you can visit the [Can I use](https://caniuse.com) website and search for the feature.
+
 [discord]: https://astro.build/chat
 [issues]: https://github.com/withastro/starlight/issues
 [sl]: https://github.com/withastro/starlight/pulls

docs-i18n-tracker/lib/translation-status/builder.ts

@@ -253,10 +253,13 @@ export class TranslationStatusBuilder {
 		subpath: string;
 		query?: string;
 	}) {
+		// this is a hack to get the correct URL for the docs repo
+		// like zh-CN -> zh-cn pt-BR -> pt-br
+		const lowerLang = lang.toLowerCase();
 		const noDotSrcDir = this.pageSourceDir.replace(/^\.+\//, '');
 		const isSrcLang = lang === this.sourceLanguage;
 		return `https://github.com/${this.githubRepo}/${type}/${refName}/${noDotSrcDir}${
-			isSrcLang ? '' : `/${lang}`
+			isSrcLang ? '' : `/${lowerLang}`
 		}/${subpath}${query}`;
 	}
 

docs/astro.config.mjs

@@ -9,15 +9,25 @@ export const locales = {
 	fr: { label: 'Français', lang: 'fr' },
 	it: { label: 'Italiano', lang: 'it' },
 	id: { label: 'Bahasa Indonesia', lang: 'id' },
-	zh: { label: '简体中文', lang: 'zh' },
+	'zh-cn': { label: '简体中文', lang: 'zh-CN' },
 	'pt-br': { label: 'Português do Brasil', lang: 'pt-BR' },
 	ko: { label: '한국어', lang: 'ko' },
+	tr: { label: 'Türkçe', lang: 'tr' },
+	ru: { label: 'Русский', lang: 'ru' },
+	hi: { label: 'हिंदी', lang: 'hi' },
 };
 
-const site = 'https://starlight.astro.build/';
+/* https://vercel.com/docs/projects/environment-variables/system-environment-variables#system-environment-variables */
+const VERCEL_PREVIEW_SITE =
+	process.env.VERCEL_ENV !== 'production' &&
+	process.env.VERCEL_URL &&
+	`https://${process.env.VERCEL_URL}`;
+
+const site = VERCEL_PREVIEW_SITE || 'https://starlight.astro.build/';
 
 export default defineConfig({
 	site,
+	trailingSlash: 'always',
 	integrations: [
 		starlight({
 			title: 'Starlight',
@@ -63,9 +73,12 @@ export default defineConfig({
 						fr: 'Commencez ici',
 						it: 'Inizia qui',
 						id: 'Mulai dari sini',
-						zh: '从这里开始',
+						'zh-CN': '从这里开始',
 						'pt-BR': 'Comece Aqui',
 						ko: '여기서부터',
+						tr: 'Buradan Başlayın',
+						ru: 'Начать отсюда',
+						hi: 'यहाँ से शुरू करे',
 					},
 					items: [
 						{
@@ -78,9 +91,12 @@ export default defineConfig({
 								fr: 'Mise en route',
 								it: 'Iniziamo',
 								id: 'Memulai',
-								zh: '开始使用',
+								'zh-CN': '开始使用',
 								'pt-BR': 'Introdução',
 								ko: '시작하기',
+								tr: 'Başlarken',
+								ru: 'Введение',
+								hi: 'पहले कदम',
 							},
 						},
 						{
@@ -93,37 +109,46 @@ export default defineConfig({
 								fr: 'Installation manuelle',
 								// it: 'Manual Setup',
 								id: 'Instalasi Manual',
-								zh: '手动配置',
+								'zh-CN': '手动配置',
 								'pt-BR': 'Instalação Manual',
 								ko: '수동으로 설정하기',
+								tr: 'Elle Kurulum',
+								ru: 'Установка вручную',
+								hi: 'मैनुअल सेटअप',
 							},
 						},
 						{
 							label: 'Environmental Impact',
 							link: 'environmental-impact',
 							translations: {
-								// de: '',
+								de: 'Umweltbelastung',
 								es: 'Documentación ecológica',
 								ja: '環境への負荷',
 								fr: 'Impact environnemental',
 								it: 'Impatto ambientale',
 								id: 'Dampak terhadap lingkungan',
-								zh: '环境影响',
+								'zh-CN': '环境影响',
 								'pt-BR': 'Impacto Ambiental',
 								ko: '환경적 영향',
+								tr: 'Çevre Etkisi',
+								ru: 'Влияние на окружающую среду',
+								hi: 'पर्यावरणीय प्रभाव',
 							},
 						},
 						{
 							label: 'Showcase',
 							link: 'showcase',
 							translations: {
-								// de: '',
+								de: 'Schaufenster',
 								// es: '',
 								ja: 'ショーケース',
 								fr: 'Vitrine',
 								// it: '',
 								id: 'Galeri',
 								ko: '쇼케이스',
+								tr: 'Vitrin',
+								ru: 'Примеры',
+								hi: 'प्रदर्शन',
 							},
 						},
 					],
@@ -136,10 +161,13 @@ export default defineConfig({
 						ja: 'ガイド',
 						fr: 'Guides',
 						it: 'Guide',
-						id: 'Petunjuk Penggunaan',
-						zh: '指南',
+						id: 'Panduan',
+						'zh-CN': '指南',
 						'pt-BR': 'Guias',
 						ko: '가이드',
+						tr: 'Rehber',
+						ru: 'Руководства',
+						hi: 'गाइड',
 					},
 					autogenerate: { directory: 'guides' },
 				},
@@ -152,14 +180,16 @@ export default defineConfig({
 						fr: 'Référence',
 						it: 'Riferimenti',
 						id: 'Referensi',
-						zh: '参考',
+						'zh-CN': '参考',
 						'pt-BR': 'Referência',
 						ko: '참조',
+						tr: 'Referanslar',
+						ru: 'Справочник',
+						hi: 'संदर्भ',
 					},
 					autogenerate: { directory: 'reference' },
 				},
 			],
-			lastUpdated: true,
 		}),
 	],
 });