@@ -2,7 +2,7 @@
 # https://help.github.com/en/articles/about-github-actions
 # https://help.github.com/en/articles/workflow-syntax-for-github-actions
 
-name: Install Dependencies, Lint
+name: Validate Docs
 
 on: [pull_request]
 
@@ -13,22 +13,30 @@ jobs:
     strategy:
       matrix:
         node_version: [20]
+        # Build processes work differently across operating systems, so the
+        # checks run on each one to make sure anyone can contribute to the
+        # docs.
         os: [windows-latest, macOS-latest]
 
     steps:
-    - uses: actions/checkout@v4
-    - name: Use Node.js ${{ matrix.node_version }}
-      uses: actions/setup-node@v4
+    - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+    - name: ⚙️ Use Node.js ${{ matrix.node_version }}
+      uses: actions/setup-node@820762786026740c76f36085b0efc47a31fe5020 # v7.0.0
       with:
         node-version: ${{ matrix.node_version }}
-    - name: Install Dependencies
+    - name: 🕸️ Install Dependencies
       run: npm ci --legacy-peer-deps
-    - name: Lint
+    - name: 🖌️ Lint
       run: npm run lint
-    - name: Spell Check
+    - name: Test
+      run: npm run test
+    - name: 🔤 Spell Check
       run: npm run spellcheck
+    - uses: ./.github/workflows/actions/check-translations
     # Lint and spell check changes should be pushed
     # to the branch before the branch is merge eligible.
-    - name: Check Diff
+    #
+    # The translation keys check should not produce any changes.
+    - name: 🔍 Check Diff
       run: git diff --exit-code
       shell: bash
@@ -0,0 +1,20 @@
+name: 'Check Translations'
+description: 'Validates the translated locales without building them'
+runs:
+  using: 'composite'
+  steps:
+    # Surfaces failures unique to a translated locale, such as duplicate
+    # translation keys, while the changes are still in review. Previews only
+    # build the default locale, so translated locale issues would not surface
+    # until after merging into main.
+    #
+    # The sidebars reference the native and CLI docs, which are generated rather
+    # than committed, so those have to exist before the translations can be
+    # extracted.
+    - name: 🇯🇵 Extract Translations
+      shell: bash
+      run: |
+        trap 'rm -rf i18n' EXIT
+        node scripts/native.mjs
+        node scripts/cli.mjs
+        npx docusaurus write-translations --locale ja
@@ -1,13 +1,31 @@
-src/theme/DocItem
-src/theme/DocRoot
+# Ejected components keep upstream's formatting so they stay diffable against
+# @docusaurus/theme-classic. Refer to `src/theme/README.md`.
+# Wrapped components are our own code, so they follow the repo's formatting.
+src/theme/DocItem/Layout/index.tsx
+src/theme/EditMetaRow/index.tsx
+src/theme/Icon/Edit/index.tsx
+src/theme/Icon/Language/index.tsx
+src/theme/Layout/index.tsx
+src/theme/NavbarItem/LocaleDropdownNavbarItem/index.tsx
+src/theme/prism-include-languages.ts
+
 legacy-stencil-components
 scripts/bak
 
 docs/api
 docs/native
 versioned_docs/version-v*/native
 docs/cli/commands
+# Each definition in these files is one line of prose inside a JSX <section>.
+# Prettier's mdx parser reflows those children and moves link text onto its own
+# line, which MDX then wraps in a paragraph, rendering invalid HTML such as
+# <a><p>Android SDK</p></a>. Formatting these files reintroduces that markup.
 docs/reference/glossary.md
+versioned_docs/version-v*/reference/glossary.md
+
+# Archived versions
+versioned_docs/version-v5
+versioned_docs/version-v6
 
 static/code/stackblitz
 
 
@@ -19,6 +19,7 @@ Thanks for your interest in contributing to Ionic's documentation! :tada: Check
 - [Reporting Issues](#reporting-issues)
 - [Pull Request Guidelines](#pull-request-guidelines)
 - [Deploying](#deploying)
+  - [Archiving a Version](#archiving-a-version)
 - [License](#license)
 
 ---
@@ -34,6 +35,42 @@ npm install
 npm start
 ```
 
+#### GitHub Token
+
+The documentation build requires a GitHub Personal Access Token to fetch Ionic Framework release notes. The build will still work locally without it (release notes will be empty), but it's required for Vercel preview and production builds.
+
+**Local Development:**
+
+1. Create a [fine-grained Personal Access Token](https://github.com/settings/personal-access-tokens/new) with:
+
+   - **Repository access**: Public repositories (read-only)
+   - **Expiration**: 366 days (update annually)
+
+2. Add the token to your shell profile (`~/.zshrc`, `~/.bashrc`, etc.):
+
+   ```sh
+   export GITHUB_TOKEN=github_pat_...
+   ```
+
+3. Reload your shell or run `source ~/.zshrc` (or equivalent)
+
+**Vercel:**
+
+1. Create a [fine-grained Personal Access Token](https://github.com/settings/personal-access-tokens/new) with the same settings as above, but with:
+
+   - **Owner**: ionic-team organization (not your personal account)
+
+2. Add the token to Vercel project settings:
+
+   - Go to your project on Vercel
+   - Navigate to **Settings → Environment Variables**
+   - Add `GITHUB_TOKEN` with the token value
+   - Select Production and Preview environments
+
+3. Redeploy the project for the token to take effect
+
+Without the token, the build will fail with an error message indicating the token is missing.
+
 ### Linting Documentation
 
 This repository uses [Prettier](https://prettier.io/), an opinionated code formatter, in order to keep consistent formatting throughout the documentation. Run the following command to automatically fix all formatting, and then push any changes:
@@ -175,6 +212,33 @@ When submitting pull requests, please keep the scope of your change contained to
 
 The Ionic documentation's `main` branch is deployed automatically and separately from the [Ionic site](https://github.com/ionic-team/ionic-site) itself. The Ionic site then uses a proxy for paths under `/docs` to request the deployed documentation.
 
+### Archiving a Version
+
+Archived versions are served from a frozen Vercel deployment instead of being rebuilt on every `main` deploy, which keeps build times and memory usage low. Two files control this:
+
+- [`versions.json`](./versions.json): lists the versions Docusaurus rebuilds on every deploy.
+- [`versionsArchived.json`](./versionsArchived.json): maps each archived version to the frozen deployment URL the version picker links to.
+
+The archived URL has to point at a build that _included_ the version, so you build it first, then move it to `versionsArchived.json`:
+
+1. **Build the version.** Make sure it is in `versions.json`. If you are refreshing an already-archived version, move it out of `versionsArchived.json` and back into `versions.json`. Commit, push and let Vercel deploy.
+2. **Promote the deployment.** In the Vercel dashboard, open that deployment and **Promote to Production** so it does not get cleaned up. Wait for the build to finish before pushing again, or it may get canceled.
+3. **Copy its URL.** Use the deployment's unique `ionic-docs-<hash>-ionic1.vercel.app` URL, not the branch or production alias.
+4. **Archive it.** Remove the version from `versions.json`, then add it to `versionsArchived.json` with `/docs/<version>` appended and no trailing slash (a trailing slash causes a brief 404 flash):
+
+   ```json
+   {
+     "v6": "https://ionic-docs-<hash>-ionic1.vercel.app/docs/v6"
+   }
+   ```
+
+5. **Open a PR.** Once merged, the version picker links to the archive and `main` stops building that version.
+
+Removed versions keep their `versioned_docs/` and `versioned_sidebars/` content, so they can be rebuilt anytime by adding them back to `versions.json`.
+
+> [!NOTE]
+> Ionic v3 and v4 use other build tools and are not managed here.
+
 ---
 
 ## License
 
@@ -26,7 +26,7 @@ Once you've generated your playground, you need to add it to the main markdown f
 ```
 ## Feature
 
-import Feature from '@site/static/usage/v8/button/feature/index.md';
+import Feature from '@site/static/usage/v9/button/feature/index.md';
 
 <Feature />
 ```
@@ -4,7 +4,7 @@ to: "<%= `static/usage/v${version}/${name}/${path}/angular/example_component_ts.
 ---
 ```ts
 import { Component } from '@angular/core';
-import { <%= pascalComponent %> } from '@ionic/angular/standalone';
+import { <%= pascalComponent %> } from '@ionic/angular';
 
 @Component({
   selector: 'app-example',
 
@@ -54,8 +54,8 @@ module.exports = {
               type: 'select',
               name: 'version',
               message: 'Select the Ionic Framework version for the playground',
-              initial: '8',
-              choices: ['6', '7', '8'],
+              initial: '9',
+              choices: ['6', '7', '8', '9'],
             },
             {
               type: 'toggle',
 
@@ -2,7 +2,7 @@
 arbitrary: <% pascalComponent = h.changeCase.pascal(component) %>
 to: "<%= `static/usage/v${version}/${name}/${path}/vue.md` %>"
 ---
-```html
+```vue
 <template>
   <<%= component %>></<%= component %>>
 </template>
 
@@ -14,7 +14,7 @@ Vetur
 Wistia
 WCAG
 CDK
-
+browserslistrc
 actionsheet
 fabs
 datetime
@@ -26,17 +26,20 @@ searchbars
 sidemenu
 textarea
 textareas
-
+ionicframework
 appstore
 authed
 autogrow
 automations
 autoplay
 Callout
+codemods
 comparewith
 composables
 engageable
 flexbox
+fontawesome
+fortawesome
 frontmatter
 fullscreen
 geolocation
@@ -58,11 +61,15 @@ preconfigured
 preflighted
 proxying
 quickstart
+remixicon
 retargeted
 runtimes
 scroller
 subcomponent
 subcomponents
+subpath
+subpaths
+svgs
 swipeable
 templating
 transpiling
@@ -83,6 +90,3 @@ msallowfullscreen
 oallowfullscreen
 webkitallowfullscreen
 webnative
-
-browserslistrc
-ionicframework