Merge branch 'main' into feat/add-badge-to-linkcard

.changeset/config.json

@@ -9,7 +9,7 @@
   "access": "public",
   "baseBranch": "main",
   "updateInternalDependencies": "patch",
-  "ignore": ["starlight-docs", "@example/*", "docs-i18n-tracker"],
+  "ignore": ["starlight-docs", "@example/*"],
   "___experimentalUnsafeOptions_WILL_CHANGE_IN_PATCH": {
     "onlyUpdatePeerDependentsWhenOutOfRange": true
   }

.git-blame-ignore-revs

@@ -0,0 +1,5 @@
+# Apply with:
+# `git config --local blame.ignoreRevsFile .git-blame-ignore-revs`
+
+# [Add Prettier and format files](https://github.com/withastro/starlight/pull/393)
+9b172f5ee09697d80f301e9b70aca1946419ce24

.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,15 @@ 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/**/*
+  - docs/src/content/docs/da/**/*
+  - docs/src/content/docs/uk/**/*
 
 '🌟 core':
   - packages/starlight/**

.github/workflows/ci.yml

@@ -73,3 +73,28 @@ jobs:
       - name: Build docs site
         working-directory: ./docs
         run: pnpm build
+
+  links:
+    name: Check for broken links
+    runs-on: ubuntu-20.04
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v3
+
+      - name: Setup PNPM
+        uses: pnpm/action-setup@v2
+
+      - name: Setup Node
+        uses: actions/setup-node@v3
+        with:
+          node-version: ${{ env.NODE_VERSION }}
+          cache: 'pnpm'
+
+      - name: Install Dependencies
+        run: pnpm i
+
+      - name: Build docs site and check links
+        working-directory: ./docs
+        run: pnpm build
+        env:
+          CHECK_LINKS: true

.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

.npmrc

@@ -1,2 +1,3 @@
 prefer-workspace-packages=true
 link-workspace-packages=true
+shell-emulator=true

.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
@@ -107,6 +116,20 @@ You should then be able to open <http://localhost:4321> and see your changes.
 > **Note**
 > Changes to the Starlight integration will require you to quit and restart the dev server to take effect.
 
+### Check for broken links in the docs site
+
+When adding or translating content in the Starlight docs site, you can check all internal links are valid.
+All GitHub PRs are checked this way automatically, but testing locally can help if you want to confirm changes are correct before committing them.
+
+To do this, move into the `docs/` directory from the root of the repo and then build the site with the `CHECK_LINKS` environment variable:
+
+```sh
+cd docs
+CHECK_LINKS=true pnpm build
+```
+
+If there are any broken links, the build will fail and log which pages need to be fixed.
+
 ### Unit tests
 
 The Starlight package includes unit tests in [`packages/starlight/__tests__/`](./packages/starlight/__tests__/), which are run using [Vitest][vitest].
@@ -125,7 +148,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({
@@ -189,6 +212,18 @@ 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 to the `locales` config in `docs/lunaria.config.json`
+- 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.
@@ -206,6 +241,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