chore: merge main into major-10.0

.github/workflows/CI.yml

@@ -6,39 +6,86 @@ name: Validate Docs
 
 on: [pull_request]
 
+# A new push supersedes the run before it.
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
+env:
+  NODE_VERSION: 24
+
 jobs:
-  test:
-    name: Test on ${{ matrix.os }}
-    runs-on: ${{ matrix.os }}
-    strategy:
-      matrix:
-        # 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]
+  # Needs no dependencies, so it reports in seconds rather than queueing behind
+  # npm ci and lint.
+  admonitions:
+    name: Check Admonitions
+    runs-on: ubuntu-latest
+
+    steps:
+    - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+      with:
+        # The check diffs against the pull request base, so it needs history.
+        fetch-depth: 0
+    - uses: ./.github/workflows/actions/check-admonitions
+
+  # These produce the same verdict on any operating system, so they run once.
+  checks:
+    name: Checks
+    runs-on: ubuntu-latest
 
     steps:
     - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
     - name: ⚙️ Use Node.js
       uses: actions/setup-node@820762786026740c76f36085b0efc47a31fe5020 # v7.0.0
       with:
-        node-version: 24
+        node-version: ${{ env.NODE_VERSION }}
+        cache: npm
     - name: 🕸️ Install Dependencies
       run: npm ci
-    - name: 🖌️ Lint
-      run: npm run lint
     - name: Test
       run: npm run test
     - name: 🧩 Typecheck
       run: npm run typecheck
     - name: 🔤 Spell Check
       run: npm run spellcheck
-    - uses: ./.github/workflows/actions/check-admonitions
     - uses: ./.github/workflows/actions/check-translations
-    # Lint and spell check changes should be pushed
-    # to the branch before the branch is merge eligible.
-    #
-    # The translation keys check should not produce any changes.
+
+  cross-platform:
+    name: Cross-platform on ${{ matrix.os }}
+    runs-on: ${{ matrix.os }}
+    strategy:
+      matrix:
+        # Prettier rewrites line endings, so Lint is the one check whose
+        # verdict depends on the operating system.
+        os: [windows-latest, macOS-latest]
+
+    steps:
+    - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+    - name: ⚙️ Use Node.js
+      uses: actions/setup-node@820762786026740c76f36085b0efc47a31fe5020 # v7.0.0
+      with:
+        node-version: ${{ env.NODE_VERSION }}
+        cache: npm
+    - name: 🕸️ Install Dependencies
+      run: npm ci
+    - name: 🖌️ Lint
+      run: npm run lint
+    # Lint changes should be pushed to the branch before the branch is merge
+    # eligible.
     - name: 🔍 Check Diff
       run: git diff --exit-code
       shell: bash
+
+  verify:
+    # The one required check on main and the feature branches, so the jobs
+    # above can change without touching the protection rules. Renaming this
+    # blocks merges until those rules are updated to match.
+    name: Verify
+    if: ${{ always() }}
+    needs: [admonitions, checks, cross-platform]
+    runs-on: ubuntu-latest
+
+    steps:
+    - name: Check job status
+      if: ${{ contains(needs.*.result, 'failure') || contains(needs.*.result, 'cancelled') }}
+      run: exit 1

.github/workflows/actions/check-admonitions/action.yml

@@ -15,17 +15,14 @@ runs:
     # Only the files the pull request touches are checked, so an existing
     # page is never anyone else's problem to fix.
     #
-    # The event payload has no file list, so the changed files come from a
-    # diff. The checkout is shallow and the base commit is fetched here
-    # rather than through `fetch-depth` on the checkout, which would pull
-    # the full history for every step in the job just to serve this one.
+    # The caller has to check out with `fetch-depth: 0`, which a composite
+    # action cannot require for itself.
     - name: 🔎 Check Admonitions
       shell: bash
       env:
         BASE_SHA: ${{ github.event.pull_request.base.sha }}
         CHANGED_FILES: ${{ runner.temp }}/changed-files.txt
       run: |
-        git fetch --quiet --no-tags --depth=1 origin "$BASE_SHA"
         git diff --name-only --diff-filter=ACMR "$BASE_SHA" HEAD > "$CHANGED_FILES"
         node <<'JS'
         const { readFileSync } = require('fs');

docs/angular/add-to-existing.mdx

@@ -14,7 +14,7 @@ import DocsCards from '@components/global/DocsCards';
   />
 </head>
 
-This guide covers how to add Ionic Angular to an existing Angular project. If you're looking to start a new project from scratch, check out the [Ionic Angular Quickstart](/docs/angular/quickstart.mdx) guide. For an overview of how Ionic Angular works with Angular, including version support and tooling, check out the [Ionic Angular Overview](/docs/angular/overview.mdx).
+This guide covers how to add Ionic Angular to an existing Angular project. If you're looking to start a new project from scratch, check out the [Ionic Angular Quickstart](/angular/quickstart.mdx) guide. For an overview of how Ionic Angular works with Angular, including version support and tooling, check out the [Ionic Angular Overview](/angular/overview.mdx).
 
 :::tip
 
@@ -76,7 +76,7 @@ Replace the existing `styles` array in `angular.json` with the following:
 
 :::info
 
-While `core.css` is required, `normalize.css`, `structure.css`, and `typography.css` are recommended but not required. They normalize cross-browser differences, ensure proper scrolling behavior, and provide consistent typography and form styling. Without them, you may need to handle these concerns yourself. For more details, refer to [Global Stylesheets](/docs/layout/global-stylesheets.mdx).
+While `core.css` is required, `normalize.css`, `structure.css`, and `typography.css` are recommended but not required. They normalize cross-browser differences, ensure proper scrolling behavior, and provide consistent typography and form styling. Without them, you may need to handle these concerns yourself. For more details, refer to [Global Stylesheets](/layout/global-stylesheets.mdx).
 
 :::
 
@@ -96,7 +96,7 @@ export const appConfig: ApplicationConfig = {
 };
 ```
 
-This reflects the Angular 21 and 22 scaffold, which is zoneless by default. If your existing app is on Angular 18 through 20, it still has `provideZoneChangeDetection({ eventCoalescing: true })`; keep that provider and add `provideIonicAngular({})` alongside it. Refer to [Zoneless Change Detection](/docs/angular/zoneless.mdx) for details.
+This reflects the Angular 21 and 22 scaffold, which is zoneless by default. If your existing app is on Angular 18 through 20, it still has `provideZoneChangeDetection({ eventCoalescing: true })`; keep that provider and add `provideIonicAngular({})` alongside it. Refer to [Zoneless Change Detection](/angular/zoneless.mdx) for details.
 
 ## Using Individual Components
 
@@ -123,7 +123,7 @@ import { IonButton, IonDatetime } from '@ionic/angular';
 export class App {}
 ```
 
-Visit the [components](/docs/components.mdx) page for all of the available Ionic components.
+Visit the [components](/components.mdx) page for all of the available Ionic components.
 
 ## Using Ionic Pages
 
@@ -172,7 +172,7 @@ Replace the existing `styles` array in `angular.json` with the following:
 ]
 ```
 
-These stylesheets set up the overall page structure and provide [CSS utilities](/docs/layout/css-utilities.mdx) for faster development. Some stylesheets are optional. For details on which stylesheets are required, check out [Global Stylesheets](/docs/layout/global-stylesheets.mdx).
+These stylesheets set up the overall page structure and provide [CSS utilities](/layout/css-utilities.mdx) for faster development. Some stylesheets are optional. For details on which stylesheets are required, check out [Global Stylesheets](/layout/global-stylesheets.mdx).
 
 #### 2. Set up Theming
 
@@ -191,7 +191,7 @@ Create a `src/theme/variables.css` file with the following content:
 @import '@ionic/angular/css/palettes/dark.system.css';
 ```
 
-This file enables [dark mode support](/docs/theming/dark-mode.mdx) for your Ionic app when the system is set to prefer a dark appearance. You can customize the theming behavior by uncommenting different dark palette imports or adding custom CSS variables.
+This file enables [dark mode support](/theming/dark-mode.mdx) for your Ionic app when the system is set to prefer a dark appearance. You can customize the theming behavior by uncommenting different dark palette imports or adding custom CSS variables.
 
 #### 3. Update the App Component
 
@@ -326,11 +326,11 @@ Now that you have Ionic Angular integrated into your project, check out:
   <p>Discover how to handle routing and navigation in Ionic Angular apps using the Angular Router.</p>
 </DocsCard>
 
-<DocsCard header="Components" href="/docs/components" icon="/icons/guide-components-icon.png">
+<DocsCard header="Components" href="/components" icon="/icons/guide-components-icon.png">
   <p>Explore Ionic's rich library of UI components for building beautiful apps.</p>
 </DocsCard>
 
-<DocsCard header="Theming" href="/docs/theming/basics" icon="/icons/guide-theming-icon.png">
+<DocsCard header="Theming" href="/theming/basics" icon="/icons/guide-theming-icon.png">
   <p>Learn how to customize the look and feel of your app with Ionic's powerful theming system.</p>
 </DocsCard>
 

docs/angular/lifecycle.mdx

@@ -32,7 +32,7 @@ If your pages keep state in plain fields rather than signals, the component host
 
 On **Angular 18 through 21** this only affects you if you set `OnPush` on those components yourself, because a component that does not declare a strategy is eager.
 
-**Angular 22** makes `OnPush` the default for components that do not declare one, so refer to [Change detection on Angular 22](/docs/angular/zoneless.mdx#change-detection-on-angular-22) for what your app shell has to declare.
+**Angular 22** makes `OnPush` the default for components that do not declare one, so refer to [Change detection on Angular 22](/angular/zoneless.mdx#change-detection-on-angular-22) for what your app shell has to declare.
 
 :::
 

docs/angular/navigation.mdx

@@ -231,7 +231,7 @@ The application history in this example has the following path:
 
 `Accessibility` --> `VoiceOver` --> `Speech`
 
-When we press the back button, we follow that same routing path except in reverse. Linear routing is helpful in that it allows for simple and predictable routing behaviors. It also means we can use router Angular Router APIs such as [LocationStrategy.historyGo()](#navigating-using-locationstrategy).
+When we press the back button, we follow that same routing path except in reverse. Linear routing is helpful in that it allows for simple and predictable routing behaviors. It also means we can use router Angular Router APIs such as [LocationStrategy.historyGo()](#navigating-using-locationstrategyhistorygo).
 
 The downside of linear routing is that it does not allow for complex user experiences such as tab views. This is where non-linear routing comes into play.
 

docs/angular/overview.mdx

@@ -18,7 +18,7 @@ import DocsCards from '@components/global/DocsCards';
 
 ## Angular Version Support
 
-Ionic Angular v9 supports Angular versions 18 through 22. For detailed information on supported versions and our support policy, refer to the [Ionic Angular Support Policy](/docs/reference/support#ionic-angular).
+Ionic Angular v9 supports Angular versions 18 through 22. For detailed information on supported versions and our support policy, refer to the [Ionic Angular Support Policy](/reference/support.mdx#ionic-angular).
 
 ## Angular Tooling
 
@@ -56,11 +56,11 @@ $ ionic serve █
   <p>Discover how to handle routing and navigation in Ionic Angular apps using the Angular Router.</p>
 </DocsCard>
 
-<DocsCard header="Components" href="/docs/components" icon="/icons/guide-components-icon.png">
+<DocsCard header="Components" href="/components" icon="/icons/guide-components-icon.png">
   <p>Explore Ionic's rich library of UI components for building beautiful apps.</p>
 </DocsCard>
 
-<DocsCard header="Theming" href="/docs/theming/basics" icon="/icons/guide-theming-icon.png">
+<DocsCard header="Theming" href="/theming/basics" icon="/icons/guide-theming-icon.png">
   <p>Learn how to customize the look and feel of your app with Ionic's powerful theming system.</p>
 </DocsCard>
 

docs/angular/quickstart.mdx

@@ -174,17 +174,17 @@ And the template, in the `home.page.html` file, uses those components:
 </ion-content>
 ```
 
-This creates a page with a header and scrollable content area. The second header shows a [collapsible large title](/docs/api/title.mdx#collapsible-large-titles) that displays on iOS devices when at the top of the content, then condenses to show the smaller title in the first header when scrolling down.
+This creates a page with a header and scrollable content area. The second header shows a [collapsible large title](/api/title.mdx#collapsible-large-titles) that displays on iOS devices when at the top of the content, then condenses to show the smaller title in the first header when scrolling down.
 
 :::tip[Learn More]
 
-For detailed information about Ionic layout components, refer to the [Header](/docs/api/header.mdx), [Toolbar](/docs/api/toolbar.mdx), [Title](/docs/api/title.mdx), and [Content](/docs/api/content.mdx) documentation.
+For detailed information about Ionic layout components, refer to the [Header](/api/header.mdx), [Toolbar](/api/toolbar.mdx), [Title](/api/title.mdx), and [Content](/api/content.mdx) documentation.
 
 :::
 
 ## Add an Ionic Component
 
-You can enhance your Home page with more Ionic UI components. For example, add a [Button](/docs/api/button.mdx) at the end of the `ion-content`:
+You can enhance your Home page with more Ionic UI components. For example, add a [Button](/api/button.mdx) at the end of the `ion-content`:
 
 ```html title="src/app/home/home.page.html"
 <ion-content>
@@ -215,7 +215,7 @@ ionic generate page new
 
 A route will be automatically added to `app.routes.ts`.
 
-In `new.page.html`, you can add a [Back Button](/docs/api/back-button.mdx) to the [Toolbar](/docs/api/toolbar.mdx):
+In `new.page.html`, you can add a [Back Button](/api/back-button.mdx) to the [Toolbar](/api/toolbar.mdx):
 
 ```html title="src/app/new/new.page.html"
 <ion-header [translucent]="true">
@@ -262,7 +262,7 @@ import { RouterLink } from '@angular/router';
 
 :::info
 
-Navigating can also be performed using Angular's Router service. Refer to the [Angular Navigation documentation](/docs/angular/navigation.mdx#navigating-to-different-routes) for more information.
+Navigating can also be performed using Angular's Router service. Refer to the [Angular Navigation documentation](/angular/navigation.mdx#navigating-to-different-routes) for more information.
 
 :::
 
@@ -307,7 +307,7 @@ export class NewPage implements OnInit {
 
 Alternatively, you can register icons in `app.component.ts` to use them throughout your app.
 
-For more information, refer to the [Icon documentation](/docs/api/icon.mdx) and the [Ionicons documentation](https://ionic.io/ionicons/).
+For more information, refer to the [Icon documentation](/api/icon.mdx) and the [Ionicons documentation](https://ionic.io/ionicons/).
 
 ## Call Component Methods
 
@@ -393,7 +393,7 @@ To call methods on Ionic components:
 1. Create a `ViewChild` reference for the component
 2. Call the method directly on the component instance
 
-You can find available methods for each component in the [Methods](/docs/api/content.mdx#methods) section of their API documentation.
+You can find available methods for each component in the [Methods](/api/content.mdx#methods) section of their API documentation.
 
 ## Run on a Device
 
@@ -432,11 +432,11 @@ This guide covered the basics of creating an Ionic Angular app, adding navigatio
   <p>Discover how to handle routing and navigation in Ionic Angular apps using the Angular Router.</p>
 </DocsCard>
 
-<DocsCard header="Components" href="/docs/components" icon="/icons/guide-components-icon.png">
+<DocsCard header="Components" href="/components" icon="/icons/guide-components-icon.png">
   <p>Explore Ionic's rich library of UI components for building beautiful apps.</p>
 </DocsCard>
 
-<DocsCard header="Theming" href="/docs/theming/basics" icon="/icons/guide-theming-icon.png">
+<DocsCard header="Theming" href="/theming/basics" icon="/icons/guide-theming-icon.png">
   <p>Learn how to customize the look and feel of your app with Ionic's powerful theming system.</p>
 </DocsCard>
 

docs/angular/your-first-app.mdx

@@ -38,7 +38,7 @@ Highlights include:
 
 - One Angular-based codebase that runs on the web, iOS, and Android using Ionic Framework [UI components](../components.mdx).
 - Deployed as a native iOS and Android mobile app using [Capacitor](https://capacitorjs.com), Ionic's official native app runtime.
-- Photo Gallery functionality powered by the Capacitor [Camera](../native/camera.mdx), [Filesystem](../native/filesystem.mdx), and [Preferences](../native/preferences.mdx) APIs.
+- Photo Gallery functionality powered by the Capacitor [Camera](/native/camera.mdx), [Filesystem](/native/filesystem.mdx), and [Preferences](/native/preferences.mdx) APIs.
 
 Find the [complete app code](https://github.com/ionic-team/tutorial-photo-gallery-angular) referenced in this guide on GitHub.
 
@@ -104,7 +104,7 @@ npm install @capacitor/camera @capacitor/preferences @capacitor/filesystem
 
 ### PWA Elements
 
-Some Capacitor plugins, including the [Camera API](../native/camera.mdx), provide the web-based functionality and UI via the Ionic [PWA Elements library](https://github.com/ionic-team/pwa-elements).
+Some Capacitor plugins, including the [Camera API](/native/camera.mdx), provide the web-based functionality and UI via the Ionic [PWA Elements library](https://github.com/ionic-team/pwa-elements).
 
 It's a separate dependency, so install it next:
 

docs/angular/your-first-app/2-taking-photos.mdx

@@ -11,7 +11,7 @@ sidebar_label: Taking Photos
   />
 </head>
 
-Now for the fun part - adding the ability to take photos with the device’s camera using the Capacitor [Camera API](../../native/camera.mdx). We’ll begin with building it for the web, then make some small tweaks to make it work on mobile (iOS and Android).
+Now for the fun part - adding the ability to take photos with the device’s camera using the Capacitor [Camera API](/native/camera.mdx). We’ll begin with building it for the web, then make some small tweaks to make it work on mobile (iOS and Android).
 
 ## Photo Service
 

docs/angular/your-first-app/3-saving-photos.mdx

@@ -86,7 +86,7 @@ export interface UserPhoto {
 }
 ```
 
-We'll use the Capacitor [Filesystem API](../../native/filesystem.mdx) to save the photo. First, convert the photo to base64 format.
+We'll use the Capacitor [Filesystem API](/native/filesystem.mdx) to save the photo. First, convert the photo to base64 format.
 
 Then, pass the data to the Filesystem's `writeFile` method. Recall that we display photos by setting the image's source path (`src`) to the `webviewPath` property. So, set the `webviewPath` and return the new `Photo` object.
 

docs/angular/your-first-app/4-loading-photos.mdx

@@ -13,7 +13,7 @@ sidebar_label: Loading Photos
 
 We’ve implemented photo taking and saving to the filesystem. There’s one last piece of functionality missing: the photos are stored in the filesystem, but we need a way to save pointers to each file so that they can be displayed again in the photo gallery.
 
-Fortunately, this is easy: we’ll leverage the Capacitor [Preferences API](../../native/preferences.mdx) to store our array of Photos in a key-value store.
+Fortunately, this is easy: we’ll leverage the Capacitor [Preferences API](/native/preferences.mdx) to store our array of Photos in a key-value store.
 
 ## Preferences API