chore(docs): pin an explicit id on every heading

cspell.json

@@ -10,7 +10,9 @@
   "ignoreRegExpList": [
     "/(```+)[\\s\\S]+?\\1/g",
     "`([^`]*)`",
-    "/:[a-zA-Z0-9-_\\+]+:/g"
+    "/:[a-zA-Z0-9-_\\+]+:/g",
+    // Pinned heading ids, as in `## Using isOpen {/* #using-isopen */}`.
+    "/\\{\\/\\*\\s*#[a-z0-9-]+\\s*\\*\\/\\}/g"
   ],
   "ignorePaths": [
     "docs/cli",

docs/angular/add-to-existing.mdx

@@ -22,7 +22,7 @@ This guide uses `.css` file extensions for stylesheets. If you created your Angu
 
 :::
 
-## Setup
+## Setup {/* #setup */}
 
 :::info
 
@@ -32,7 +32,7 @@ This guide follows the structure of an Angular app created with the Angular CLI.
 
 You can add Ionic Angular to your existing Angular project using the Angular CLI's `ng add` feature or by installing it manually.
 
-### Using ng add
+### Using ng add {/* #using-ng-add */}
 
 The easiest way to add Ionic Angular is to use the Angular CLI's `ng add` feature:
 
@@ -42,17 +42,17 @@ ng add @ionic/angular
 
 This will install the `@ionic/angular` package and automatically configure the necessary imports and styles.
 
-### Manual Installation
+### Manual Installation {/* #manual-installation */}
 
 If you prefer to install Ionic Angular manually, you can follow these steps:
 
-#### 1. Install the Package
+#### 1. Install the Package {/* #1-install-the-package */}
 
 ```bash
 npm install @ionic/angular
 ```
 
-#### 2. Add Ionic Framework Stylesheets
+#### 2. Add Ionic Framework Stylesheets {/* #2-add-ionic-framework-stylesheets */}
 
 Replace the existing `styles` array in `angular.json` with the following:
 
@@ -80,7 +80,7 @@ While `core.css` is required, `normalize.css`, `structure.css`, and `typography.
 
 :::
 
-#### 3. Configure Ionic Angular
+#### 3. Configure Ionic Angular {/* #3-configure-ionic-angular */}
 
 Update `src/app/app.config.ts` to include `provideIonicAngular`:
 
@@ -98,7 +98,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](/angular/zoneless.mdx) for details.
 
-## Using Individual Components
+## Using Individual Components {/* #using-individual-components */}
 
 After completing the setup above, you can start using Ionic components in your existing Angular app. Here's an example of how to use them:
 
@@ -125,11 +125,11 @@ export class App {}
 
 Visit the [components](/components.mdx) page for all of the available Ionic components.
 
-## Using Ionic Pages
+## Using Ionic Pages {/* #using-ionic-pages */}
 
 If you want to use Ionic pages with full navigation and page transitions, follow these additional setup steps.
 
-#### 1. Add Additional Ionic Framework Stylesheets
+#### 1. Add Additional Ionic Framework Stylesheets {/* #1-add-additional-ionic-framework-stylesheets */}
 
 Replace the existing `styles` array in `angular.json` with the following:
 
@@ -174,7 +174,7 @@ Replace the existing `styles` array in `angular.json` with the following:
 
 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
+#### 2. Set up Theming {/* #2-set-up-theming */}
 
 Create a `src/theme/variables.css` file with the following content:
 
@@ -193,7 +193,7 @@ Create a `src/theme/variables.css` file with the following content:
 
 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
+#### 3. Update the App Component {/* #3-update-the-app-component */}
 
 Update `src/app/app.html` to the following:
 
@@ -218,7 +218,7 @@ import { IonApp, IonRouterOutlet } from '@ionic/angular';
 export class App {}
 ```
 
-#### 4. Create a Home Page
+#### 4. Create a Home Page {/* #4-create-a-home-page */}
 
 Start by adding a template at `src/app/home/home.html`:
 
@@ -293,7 +293,7 @@ Finally, add a `src/app/home/home.css` file:
 }
 ```
 
-#### 5. Set up Routing
+#### 5. Set up Routing {/* #5-set-up-routing */}
 
 Update `src/app/app.routes.ts` to add a `home` route:
 
@@ -316,7 +316,7 @@ export const routes: Routes = [
 
 You're all set! Your Ionic Angular app is now configured with full Ionic page support. Run `ng serve` to start your development server and view your app.
 
-## Next Steps
+## Next Steps {/* #next-steps */}
 
 Now that you have Ionic Angular integrated into your project, check out:
 

docs/angular/build-options.mdx

@@ -7,15 +7,15 @@ Developers have two options for using Ionic components: Standalone or Modules. T
 
 The Standalone approach uses modern Angular APIs and is the recommended way to build Ionic applications. The Modules approach, including `IonicModule`, is **deprecated** and will be removed in a future major release. New projects should use the Standalone approach. Existing apps will continue to work but should plan to migrate. Refer to [Migrating from Modules to Standalone](#migrating-from-modules-to-standalone) for migration guidance.
 
-## Standalone
+## Standalone {/* #standalone */}
 
 :::info
 
 Ionic UI components as Angular standalone components is supported starting in Ionic v7.5.
 
 :::
 
-### Overview
+### Overview {/* #overview */}
 
 Developers can use Ionic components as standalone components to take advantage of treeshaking and newer Angular features. This option involves importing specific Ionic components in the Angular components you want to use them in. Developers can use Ionic standalone components even if their Angular application is NgModule-based.
 
@@ -37,7 +37,7 @@ Ionic ships standalone components from a single entry point (`@ionic/angular`).
 
 :::
 
-### Usage with Standalone-based Applications
+### Usage with Standalone-based Applications {/* #usage-with-standalone-based-applications */}
 
 :::warning
 
@@ -206,7 +206,7 @@ Ionic Angular's standalone components use ES Modules. As a result, developers us
 </TabItem>
 </Tabs>
 
-### Usage with NgModule-based Applications
+### Usage with NgModule-based Applications {/* #usage-with-ngmodule-based-applications */}
 
 :::warning
 
@@ -371,15 +371,15 @@ Ionic Angular's standalone components use ES Modules. As a result, developers us
 </TabItem>
 </Tabs>
 
-## Modules
+## Modules {/* #modules */}
 
 :::warning[Deprecation Notice]
 
 The Modules approach, including `IonicModule`, is **deprecated** and will be removed in a future major release. Existing applications will continue to work during the deprecation period but should migrate using the [Standalone migration guide](#migrating-from-modules-to-standalone). New applications should use the [Standalone](#standalone) approach.
 
 :::
 
-### Overview
+### Overview {/* #overview-1 */}
 
 Developers can also use the Modules approach by importing `IonicModule` and calling `IonicModule.forRoot()` in the `imports` array in `app.module.ts`. This registers a version of Ionic where Ionic components will be lazily loaded at runtime.
 
@@ -392,7 +392,7 @@ Developers can also use the Modules approach by importing `IonicModule` and call
 1. Lazily loading Ionic components means that the compiler does not know which components are needed at build time. This means your final application bundle may be much larger than it needs to be.
 2. Developers are unable to use newer Angular features such as [ESBuild](https://angular.io/guide/esbuild).
 
-### Usage
+### Usage {/* #usage */}
 
 In the example below, we are using `IonicModule` to create a lazily loaded version of Ionic. We can then reference any Ionic component without needing to explicitly import it.
 
@@ -412,7 +412,7 @@ import { AppComponent } from './app.component';
 export class AppModule {}
 ```
 
-## Migrating from Modules to Standalone
+## Migrating from Modules to Standalone {/* #migrating-from-modules-to-standalone */}
 
 :::tip
 
@@ -428,7 +428,7 @@ Migrating to Ionic standalone components must be done all at the same time and c
 
 Developers are encouraged to try the [automated migration utility](https://github.com/ionic-team/ionic-angular-standalone-codemods), though they can also follow the steps below if they would like to manually migrate their applications.
 
-### Standalone-based Applications
+### Standalone-based Applications {/* #standalone-based-applications */}
 
 Follow these steps if your Angular application is already using the standalone architecture, and you want to use Ionic UI components as standalone components too.
 
@@ -551,7 +551,7 @@ export class TestComponent {}
 }
 ```
 
-### NgModule-based Applications
+### NgModule-based Applications {/* #ngmodule-based-applications */}
 
 Follow these steps if your Angular application is still using the NgModule architecture, but you want to adopt Ionic UI components as standalone components now.
 

docs/angular/injection-tokens.mdx

@@ -13,7 +13,7 @@ sidebar_label: Injection Tokens
 
 Ionic provides Angular injection tokens that allow you to access Ionic elements through Angular's dependency injection system. This provides a more Angular-idiomatic way to interact with Ionic components programmatically.
 
-## Benefits
+## Benefits {/* #benefits */}
 
 Using injection tokens provides several advantages:
 
@@ -22,13 +22,13 @@ Using injection tokens provides several advantages:
 - **Simplified Code**: Eliminates the need for `ViewChild` queries or manual element references
 - **Better Testing**: Easier to mock and test components that use injection tokens
 
-## IonModalToken
+## IonModalToken {/* #ionmodaltoken */}
 
 The `IonModalToken` injection token allows you to inject a reference to the current modal element directly into your Angular components. This is particularly useful when you need to programmatically control modal behavior, listen to modal events, or access modal properties.
 
 Starting in `@ionic/angular` v8.7.0, you can use this injection token to streamline modal interactions in your Angular applications.
 
-### Basic Usage
+### Basic Usage {/* #basic-usage */}
 
 To use the `IonModalToken`, inject it into your component's constructor:
 
@@ -60,7 +60,7 @@ export class ModalComponent {
 }
 ```
 
-### Listening to Modal Events
+### Listening to Modal Events {/* #listening-to-modal-events */}
 
 You can use the injected modal reference to listen to modal lifecycle events:
 
@@ -102,7 +102,7 @@ export class ModalComponent implements OnInit {
 }
 ```
 
-### Accessing Modal Properties
+### Accessing Modal Properties {/* #accessing-modal-properties */}
 
 The injected modal reference provides access to all modal properties and methods:
 
@@ -143,7 +143,7 @@ export class ModalComponent implements OnInit {
 }
 ```
 
-### Opening a Modal with Injection Token Content
+### Opening a Modal with Injection Token Content {/* #opening-a-modal-with-injection-token-content */}
 
 When opening a modal that uses the injection token, you can pass the component directly to the modal controller:
 

docs/angular/lifecycle.mdx

@@ -15,7 +15,7 @@ This guide covers how the page life cycle works in an app built with Ionic and A
 
 ![Flowchart illustrating the Ionic page life cycle events and their sequence.](/img/guides/lifecycle/ioniclifecycle.png 'Ionic Lifecycle Diagram')
 
-## Angular Life Cycle Events
+## Angular Life Cycle Events {/* #angular-life-cycle-events */}
 
 Ionic embraces the life cycle events provided by Angular. The two Angular events you will find using the most are:
 
@@ -36,7 +36,7 @@ On **Angular 18 through 21** this only affects you if you set `OnPush` on those
 
 :::
 
-## Ionic Page Events
+## Ionic Page Events {/* #ionic-page-events */}
 
 In addition to the Angular life cycle events, Ionic Angular provides a few additional events that you can use:
 
@@ -55,7 +55,7 @@ For `ionViewWillLeave` and `ionViewDidLeave`, `ionViewWillLeave` gets called dir
 
 ![Animated GIF showing Ionic page life cycle events in a console log as a page transition occurs.](/img/guides/lifecycle/ioniclifecycle.gif 'Ionic Lifecycle Animation')
 
-## How Ionic Handles the Life of a Page
+## How Ionic Handles the Life of a Page {/* #how-ionic-handles-the-life-of-a-page */}
 
 Ionic has its router outlet, called `<ion-router-outlet />`. This outlet extends Angular's `<router-outlet />` with some additional functionality to enable better experiences for mobile devices.
 
@@ -70,7 +70,7 @@ Because of this special handling, the `ngOnInit` and `ngOnDestroy` methods might
 
 `ngOnInit` will only fire each time the page is freshly created, but not when navigated back to the page. For instance, navigating between each page in a tabs interface will only call each page's `ngOnInit` method once, but not on subsequent visits. `ngOnDestroy` will only fire when a page "popped".
 
-## Route Guards
+## Route Guards {/* #route-guards */}
 
 In Ionic 3, there were a couple of additional life cycle methods that were useful to control when a page could be entered (`ionViewCanEnter`) and left (`ionViewCanLeave`). These could be used to protect pages from unauthorized users and to keep a user on a page when you don't want them to leave (like during a form fill).
 
@@ -97,7 +97,7 @@ To use this guard, add it to the appropriate param in the route definition:
 
 For more info on how to use route guards, go to Angular's [router documentation](https://angular.io/guide/router).
 
-## Guidance for Each Life Cycle Method
+## Guidance for Each Life Cycle Method {/* #guidance-for-each-life-cycle-method */}
 
 Below are some tips on use cases for each of the life cycle events.