fix(docs-infra): update docs-alert and re-enable tests (angular#60827)

alan-agius4 · kirjs · commit 654e6da58811 · 2025-04-10T11:21:12.000-04:00
Before this commit, the docs-alert tests were failing. This also ensures that `NOTE:` is always capitalized. PR Close angular#60827
diff --git a/adev/README.md b/adev/README.md
@@ -20,7 +20,7 @@ cd angular
 yarn
 
 # Build and run local dev server
-# Note: Initial build will take some time
+# NOTE: Initial build will take some time
 yarn docs
 ```
 
diff --git a/adev/shared-docs/pipeline/guides/extensions/docs-alert.ts b/adev/shared-docs/pipeline/guides/extensions/docs-alert.ts
@@ -10,12 +10,12 @@ import {RendererThis, Token, TokenizerThis, Tokens} from 'marked';
 
 /** Enum of all available alert severities. */
 export enum AlertSeverityLevel {
-  Note = 'NOTE',
-  Tip = 'TIP',
+  NOTE = 'NOTE',
+  TIP = 'TIP',
   TODO = 'TODO',
   QUESTION = 'QUESTION',
-  Summary = 'SUMMARY',
-  TLDR = 'TLDR',
+  SUMMARY = 'SUMMARY',
+  TLDR = 'TL;DR',
   CRITICAL = 'CRITICAL',
   IMPORTANT = 'IMPORTANT',
   HELPFUL = 'HELPFUL',
@@ -39,14 +39,14 @@ export const docsAlertExtension = {
   level: 'block' as const,
   tokenizer(this: TokenizerThis, src: string): DocsAlertToken | undefined {
     let match: DocsAlert | undefined;
-    for (let level of Object.values(AlertSeverityLevel)) {
+    for (const key of Object.keys(AlertSeverityLevel)) {
       // Capture group 1: all alert text content after the severity level
-      const rule = new RegExp('^s*' + level + ': (.*?)\n(\n|$)', 's');
+      const rule = new RegExp('^s*' + key + ': (.*?)\n(\n|$)', 's');
       const possibleMatch = rule.exec(src);
 
       if (possibleMatch?.[1]) {
         match = {
-          severityLevel: level,
+          severityLevel: key,
           alert: possibleMatch,
         };
       }
@@ -57,12 +57,11 @@ export const docsAlertExtension = {
         type: 'docs-alert',
         raw: match.alert[0],
         body: match.alert[1].trim(),
-        severityLevel: match.severityLevel,
+        severityLevel: match.severityLevel.toLowerCase(),
         tokens: [],
       };
-      token.body = `**${
-        token.severityLevel === AlertSeverityLevel.TLDR ? 'TL;DR' : token.severityLevel
-      }:** ${token.body}`;
+
+      token.body = `**${AlertSeverityLevel[match.severityLevel as keyof typeof AlertSeverityLevel]}:** ${token.body}`;
       this.lexer.blockTokens(token.body, token.tokens);
       return token;
     }
diff --git a/adev/shared-docs/pipeline/guides/testing/docs-alert/docs-alert.md b/adev/shared-docs/pipeline/guides/testing/docs-alert/docs-alert.md
@@ -1,4 +1,4 @@
-Note: Use Note for ancillary/additional information that's not _essential_ to the main text.
+NOTE: Use Note for ancillary/additional information that's not _essential_ to the main text.
 This is a multiline note
 
 TIP: Use Tip to call out a specific task/action users can perform, or a fact that plays directly into a task/action.
diff --git a/adev/shared-docs/pipeline/guides/testing/docs-alert/docs-alert.spec.ts b/adev/shared-docs/pipeline/guides/testing/docs-alert/docs-alert.spec.ts
@@ -13,8 +13,7 @@ import {JSDOM} from 'jsdom';
 import {AlertSeverityLevel} from '../../../guides/extensions/docs-alert';
 import {parseMarkdown} from '../../../guides/parse';
 
-// TODO: Fix these tests.
-xdescribe('markdown to html', () => {
+describe('markdown to html', () => {
   let markdownDocument: DocumentFragment;
 
   beforeAll(async () => {
@@ -25,15 +24,10 @@ xdescribe('markdown to html', () => {
     markdownDocument = JSDOM.fragment(await parseMarkdown(markdownContent, {}));
   });
 
-  for (let level in AlertSeverityLevel) {
-    it(`should create a docs-alert for ${level}:`, () => {
-      const noteEl = markdownDocument.querySelector(`.docs-alert-${level.toLowerCase()}`);
-      // TLDR is written without a semi colon in the markdown, but is rendered
-      // with a colon, as such we have to adjust our expectation here.
-      if (level === AlertSeverityLevel.TLDR) {
-        level = 'TL;DR';
-      }
-      expect(noteEl?.textContent?.trim()).toMatch(`^${level}:`);
+  for (const [key, level] of Object.entries(AlertSeverityLevel)) {
+    it(`should create a docs-alert for ${key}:`, () => {
+      const noteEl = markdownDocument.querySelector(`.docs-alert-${key.toLowerCase()}`);
+      expect(noteEl?.textContent?.trim()).toMatch(new RegExp(`^${level}:`));
     });
   }
 
diff --git a/adev/src/app/editor/README.md b/adev/src/app/editor/README.md
@@ -81,7 +81,7 @@
 5. The file is added to the TypeScript virtual file system, allowing the TypeScript web worker to provide diagnostics, autocomplete and type features for the new file. Also, exports from the new file are available in other files.
 6. The new file is added as the last tab in the code editor and the new file can be edited.
 
-Note: If the new file name matches a file that already exists but is hidden in the code editor, the content for that file will show up in the created file. An example for a file that always exists is `index.html`.
+NOTE: If the new file name matches a file that already exists but is hidden in the code editor, the content for that file will show up in the created file. An example for a file that always exists is `index.html`.
 
 ### Deleting a file
 
@@ -90,7 +90,7 @@ Note: If the new file name matches a file that already exists but is hidden in t
 3. The file is removed from the TypeScript virtual file system.
 4. The file is removed from the code editor tabs.
 
-Note: Some files can't be deleted to prevent users to break the app, being `src/main.ts`and `src/index.html`
+NOTE: Some files can't be deleted to prevent users to break the app, being `src/main.ts`and `src/index.html`
 
 ### Switching a project
 
diff --git a/adev/src/content/guide/components/styling.md b/adev/src/content/guide/components/styling.md
@@ -63,7 +63,7 @@ the [`:host`](https://developer.mozilla.org/docs/Web/CSS/:host)
 and [`:host-context()`](https://developer.mozilla.org/docs/Web/CSS/:host-context) pseudo
 classes without
 using [Shadow DOM](https://developer.mozilla.org/docs/Web/Web_Components/Using_shadow_DOM).
-During compilation, the framework transforms these pseudo classes into attributes so it doesn't 
+During compilation, the framework transforms these pseudo classes into attributes so it doesn't
 comply with these native pseudo classes' rules at runtime (e.g. browser compatibility, specificity). Angular's
 emulated encapsulation mode does not support any other pseudo classes related to Shadow DOM, such
 as `::shadow` or `::part`.
@@ -97,7 +97,7 @@ Shadow DOM in your application before enabling this option.
 This mode disables all style encapsulation for the component. Any styles associated with the
 component behave as global styles.
 
-Note: In `Emulated` and `ShadowDom` modes, Angular doesn't 100% guarantee that your component's styles will always override styles coming from outside it.
+NOTE: In `Emulated` and `ShadowDom` modes, Angular doesn't 100% guarantee that your component's styles will always override styles coming from outside it.
 It is assumed that these styles have the same specificity as your component's styles in case of collision.
 
 ## Defining styles in templates
diff --git a/adev/src/content/guide/di/dependency-injection.md b/adev/src/content/guide/di/dependency-injection.md
@@ -100,16 +100,16 @@ NOTE: Declaring a service using `providers` causes the service to be included in
 
 ## Injecting/consuming a dependency
 
-Use Angular's `inject` function to retrieve dependencies. 
+Use Angular's `inject` function to retrieve dependencies.
 
 ```ts
-import {inject, Component} from 'angular/core'; 
+import {inject, Component} from 'angular/core';
 
 @Component({/* ... */})
 export class UserProfile {
   // You can use the `inject` function in property initializers.
   private userClient = inject(UserClient);
-  
+
   constructor() {
     // You can also use the `inject` function in a constructor.
     const logger = inject(Logger);
diff --git a/adev/src/content/guide/http/testing.md b/adev/src/content/guide/http/testing.md
@@ -181,7 +181,7 @@ const req = httpTesting.expectOne('/api/config');
 expect(req.request.headers.get('X-Authentication-Token')).toEqual(service.getAuthToken());
 </docs-code>
 
-A similar interceptor could be implemented with class based interceptors: 
+A similar interceptor could be implemented with class based interceptors:
 
 <docs-code language="ts">
 @Injectable()
@@ -204,9 +204,9 @@ TestBed.configureTestingModule({
   providers: [
     AuthService,
     provideHttpClient(withInterceptorsFromDi()),
-    provideHttpClientTesting(), 
+    provideHttpClientTesting(),
     // We rely on the HTTP_INTERCEPTORS token to register the AuthInterceptor as an HttpInterceptor
     { provide: HTTP_INTERCEPTORS, useClass: AuthInterceptor, multi: true },
   ],
 });
-</docs-code>
+</docs-code>
diff --git a/adev/src/content/guide/hydration.md b/adev/src/content/guide/hydration.md
@@ -93,7 +93,7 @@ Event replay supports _native browser events_, for example `click`, `mouseover`,
 
 ---
 
-This feature ensures a consistent user experience, preventing user actions performed before Hydration from being ignored. Note: if you have [incremental hydration](guide/incremental-hydration) enabled, event replay is automatically enabled under the hood.
+This feature ensures a consistent user experience, preventing user actions performed before Hydration from being ignored. NOTE: if you have [incremental hydration](guide/incremental-hydration) enabled, event replay is automatically enabled under the hood.
 
 ## Constraints
 
diff --git a/adev/src/content/guide/image-optimization.md b/adev/src/content/guide/image-optimization.md
@@ -19,7 +19,7 @@ In addition to optimizing the loading of the LCP image, `NgOptimizedImage` enfor
 
 If you're using a background image in CSS, [start here](#how-to-migrate-your-background-image).
 
-**Note: Although the `NgOptimizedImage` directive was made a stable feature in Angular version 15, it has been backported and is available as a stable feature in versions 13.4.0 and 14.3.0 as well.**
+**NOTE: Although the `NgOptimizedImage` directive was made a stable feature in Angular version 15, it has been backported and is available as a stable feature in versions 13.4.0 and 14.3.0 as well.**
 
 ## Getting Started
 
@@ -162,10 +162,10 @@ You can also specify a placeholder using a base64 [data URL](https://developer.m
 
 <docs-code language="angular-html">
 
-<img 
-  ngSrc="cat.jpg" 
-  width="400" 
-  height="200" 
+<img
+  ngSrc="cat.jpg"
+  width="400"
+  height="200"
   placeholder="data:image/png;base64,iVBORw0K..."
 />
 
@@ -179,11 +179,11 @@ By default, NgOptimizedImage applies a CSS blur effect to image placeholders. To
 
 <docs-code language="angular-html">
 
-<img 
-  ngSrc="cat.jpg" 
-  width="400" 
-  height="200" 
-  placeholder 
+<img
+  ngSrc="cat.jpg"
+  width="400"
+  height="200"
+  placeholder
   [placeholderConfig]="{blur: false}"
 />
 
@@ -235,7 +235,7 @@ Defining a [`srcset` attribute](https://developer.mozilla.org/docs/Web/API/HTMLI
 
 If your image should be "fixed" in size  (i.e. the same size across devices, except for [pixel density](https://web.dev/codelab-density-descriptors/)), there is no need to set a `sizes` attribute. A `srcset` can be generated automatically from the image's width and height attributes with no further input required.
 
-Example srcset generated: 
+Example srcset generated:
 ```angular-html
 <img ... srcset="image-400w.jpg 1x, image-800w.jpg 2x">
 ```
@@ -416,7 +416,7 @@ Note that in the above example, we've invented the 'roundedCorners' property nam
 
 The NgOptimizedImage does not directly support the `background-image` css property, but it is designed to easily accommodate the use case of having an image as the background of another element.
 
-For a step-by-step process for migration from `background-image` to `NgOptimizedImage`, see the [How to migrate your background image](#how-to-migrate-your-background-image) section above. 
+For a step-by-step process for migration from `background-image` to `NgOptimizedImage`, see the [How to migrate your background image](#how-to-migrate-your-background-image) section above.
 
 ### Why can't I use `src` with `NgOptimizedImage`?
 
@@ -446,19 +446,19 @@ For maintenance reasons, we don't currently plan to support additional built-in
 
 ### Can I use this with the `<picture>` tag
 
-No, but this is on our roadmap, so stay tuned. 
+No, but this is on our roadmap, so stay tuned.
 
 If you're waiting on this feature, please upvote the Github issue [here](https://github.com/angular/angular/issues/56594).
 
 ### How do I find my LCP image with Chrome DevTools?
 
 1. Using the performance tab of the Chrome DevTools, click on the "start profiling and reload page" button on the top left. It looks like a page refresh icon.
 
-2. This will trigger a profiling snapshot of your Angular application. 
+2. This will trigger a profiling snapshot of your Angular application.
 
 3. Once the profiling result is available, select "LCP" in the timings section.
 
-4. A summary entry should appear in the panel at the bottom. You can find the LCP element in the row for "related node".  Clicking on it will reveal the element in the Elements panel. 
+4. A summary entry should appear in the panel at the bottom. You can find the LCP element in the row for "related node".  Clicking on it will reveal the element in the Elements panel.
 
 <img alt="LCP in the Chrome DevTools" src="assets/images/guide/image-optimization/devtools-lcp.png">
 
diff --git a/adev/src/content/guide/templates/expression-syntax.md b/adev/src/content/guide/templates/expression-syntax.md
@@ -76,7 +76,7 @@ Angular expressions additionally also support the following non-standard operato
 | Optional chaining\*             | `someObj.someProp?.nestedProp` |
 | Non-null assertion (TypeScript) | `someObj!.someProp`            |
 
-\*Note: Optional chaining behaves differently from the standard JavaScript version in that if the left side of Angular’s optional chaining operator is `null` or `undefined`, it returns `null` instead of `undefined`.
+\*NOTE: Optional chaining behaves differently from the standard JavaScript version in that if the left side of Angular’s optional chaining operator is `null` or `undefined`, it returns `null` instead of `undefined`.
 
 ### Unsupported operators
 
diff --git a/adev/src/content/reference/errors/NG0203.md b/adev/src/content/reference/errors/NG0203.md
@@ -12,7 +12,7 @@ export class Car {
 
   // OK: field initializer
   spareTyre = inject(Tyre);
-  
+
   constructor() {
     // OK: constructor body
     this.radio = inject(Radio);
@@ -51,7 +51,7 @@ Work backwards from the stack trace of the error to identify a place where the d
 
 To fix the error move the [`inject`](api/core/inject) call to an allowed place (usually a class constructor or a field initializer).
 
-**Note:** If you are running in a test context, `TestBed.runInInjectionContext` will enable `inject()` to succeed.
+**NOTE:** If you are running in a test context, `TestBed.runInInjectionContext` will enable `inject()` to succeed.
 
 ```typescript
 TestBed.runInInjectionContext(() => {
diff --git a/adev/src/content/reference/errors/NG0751.md b/adev/src/content/reference/errors/NG0751.md
@@ -5,7 +5,7 @@ Hot Module Replacement (HMR) is a technique used by development servers to avoid
 When the HMR is enabled in Angular, all `@defer` block dependencies are loaded
 eagerly, instead of waiting for configured trigger conditions (both for client-only and incremental hydration triggers). This is needed
 for the HMR to function properly, replacing components in an application at runtime
-without the need to reload the entire page. Note: the actual rendering of defer
+without the need to reload the entire page. NOTE: the actual rendering of defer
 blocks respects trigger conditions in the HMR mode.
 
 If you want to test `@defer` block behavior in development mode and ensure that
diff --git a/adev/src/content/reference/migrations/inject-function.md b/adev/src/content/reference/migrations/inject-function.md
@@ -103,7 +103,7 @@ fixed in `inject()` which can cause new compilation errors to show up. If you en
 the migration will produce a non-null assertion after the `inject()` call to match the old type,
 at the expense of potentially hiding type errors.
 
-**Note:** non-null assertions won't be added to parameters that are already typed to be nullable,
+**NOTE:** non-null assertions won't be added to parameters that are already typed to be nullable,
 because the code that depends on them likely already accounts for their nullability.
 
 #### Before
diff --git a/adev/src/content/tools/devtools.md b/adev/src/content/tools/devtools.md
@@ -173,7 +173,7 @@ Later, import the file in the initial view of the profiler by clicking the **Cho
 
  ## Inspect your injectors
 
- Note: The Injector Tree is available for Angular Applications built with version 17 or higher.
+ NOTE: The Injector Tree is available for Angular Applications built with version 17 or higher.
 
 ### View the injector hierarchy of your application
 
@@ -185,7 +185,7 @@ Later, import the file in the initial view of the profiler by clicking the **Cho
 
  When a specific injector is selected, the path that Angular's dependency injection algorithm traverses from that injector to the root is highlighted. For element injectors, this includes highlighting the environment injectors that the dependency injection algorithm jumps to when a dependency cannot be resolved in the element hierarchy.
 
-See [resolution rules](guide/di/hierarchical-dependency-injection#resolution-rules) for more details about how Angular resolves resolution paths. 
+See [resolution rules](guide/di/hierarchical-dependency-injection#resolution-rules) for more details about how Angular resolves resolution paths.
 
 <img src="assets/images/guide/devtools/di-injector-tree-selected.png" alt="A screenshot of the 'Profiler' tab displaying how the injector tree visualize highlights resolution paths when an injector is selected.">
 
diff --git a/adev/src/content/tutorials/deferrable-views/steps/2-loading-error-placeholder/README.md b/adev/src/content/tutorials/deferrable-views/steps/2-loading-error-placeholder/README.md
@@ -82,7 +82,7 @@ Update `app.component.ts` to include a `@loading` block with a minimum parameter
 }
 </docs-code>
 
-Note: this example uses two parameters, separated by the ; character.
+NOTE: this example uses two parameters, separated by the ; character.
 
 </docs-step>
 
diff --git a/adev/src/content/tutorials/deferrable-views/steps/3-defer-triggers/README.md b/adev/src/content/tutorials/deferrable-views/steps/3-defer-triggers/README.md
@@ -73,7 +73,7 @@ Next, update the template to include a button with the label "Show all comments"
 }
 </docs-code>
 
-Note: for more information on [template variables check the documentation](https://angular.dev/guide/templates/reference-variables#).
+NOTE: for more information on [template variables check the documentation](https://angular.dev/guide/templates/reference-variables#).
 
 </docs-step>
 
diff --git a/adev/src/content/tutorials/first-app/intro/README.md b/adev/src/content/tutorials/first-app/intro/README.md
@@ -25,7 +25,7 @@ The lessons in this tutorial assume that you have experience with the following:
 
 These lessons can be completed using a local installation of the Angular tools or in our embedded editor. Local Angular development can be completed on Windows, MacOS or Linux based systems.
 
-Note: Look for alerts like this one, which call out steps that may only be for your local editor.
+NOTE: Look for alerts like this one, which call out steps that may only be for your local editor.
 
 ## Conceptual preview of your first Angular app
 
@@ -36,7 +36,7 @@ This app uses features that are common to many Angular apps.
 
 ## Local development environment
 
-Note: This step is only for your local environment!
+NOTE: This step is only for your local environment!
 
 Perform these steps in a command-line tool on the computer you want to use for this tutorial.
 
diff --git a/adev/src/content/tutorials/first-app/steps/01-hello-world/README.md b/adev/src/content/tutorials/first-app/steps/01-hello-world/README.md
@@ -8,7 +8,7 @@ This first lesson serves as the starting point from which each lesson in this tu
 
 The updated app you have after this lesson confirms that you and your IDE are ready to begin creating an Angular app.
 
-Note: If you are working with the embedded editor, skip to [step three](#create-%60hello-world%60).
+NOTE: If you are working with the embedded editor, skip to [step three](#create-%60hello-world%60).
 When working in the browser playground, you do not need to `ng serve` to run the app. Other commands like `ng generate` can be done in the console window to your right.
 
 <docs-workflow>
@@ -83,7 +83,7 @@ In this step, you update the Angular project files to change the displayed conte
 In your IDE:
 
 1. Open `first-app/src/index.html`.
-    Note: This step and the next are only for your local environment!
+    NOTE: This step and the next are only for your local environment!
 
 1. In `index.html`, replace the `<title>` element with this code to update the title of the app.
 
diff --git a/adev/src/content/tutorials/first-app/steps/02-HomeComponent/README.md b/adev/src/content/tutorials/first-app/steps/02-HomeComponent/README.md
@@ -43,7 +43,7 @@ In the **Terminal** pane of your IDE:
 
 1. Run this command to build and serve your app.
 
-    Note: This step is only for your local environment!
+    NOTE: This step is only for your local environment!
 
     <docs-code language="shell">
     ng serve
@@ -104,7 +104,7 @@ In the **Edit** pane of your IDE:
 
 1. Next, open `home.component.css` in the editor and update the content with these styles.
 
-    Note: In the browser, these can go in `src/app/home/home.component.ts` in the `styles` array.
+    NOTE: In the browser, these can go in `src/app/home/home.component.ts` in the `styles` array.
 
     <docs-code header="Replace in src/app/home/home.component.css" path="adev/src/content/tutorials/first-app/steps/03-HousingLocation/src/app/home/home.component.css"/>
 
diff --git a/adev/src/content/tutorials/first-app/steps/03-HousingLocation/README.md b/adev/src/content/tutorials/first-app/steps/03-HousingLocation/README.md
diff --git a/adev/src/content/tutorials/first-app/steps/14-http/README.md b/adev/src/content/tutorials/first-app/steps/14-http/README.md
diff --git a/adev/src/content/tutorials/learn-angular/steps/11-optimizing-images/README.md b/adev/src/content/tutorials/learn-angular/steps/11-optimizing-images/README.md
diff --git a/adev/src/content/tutorials/learn-angular/steps/15-forms/README.md b/adev/src/content/tutorials/learn-angular/steps/15-forms/README.md
diff --git a/adev/src/content/tutorials/learn-angular/steps/20-inject-based-di/README.md b/adev/src/content/tutorials/learn-angular/steps/20-inject-based-di/README.md
diff --git a/adev/src/content/tutorials/learn-angular/steps/23-pipes-format-data/README.md b/adev/src/content/tutorials/learn-angular/steps/23-pipes-format-data/README.md
diff --git a/adev/src/content/tutorials/learn-angular/steps/5-control-flow-for/README.md b/adev/src/content/tutorials/learn-angular/steps/5-control-flow-for/README.md

Original file line number	Diff line number	Diff line change
`@@ -1,4 +1,4 @@`
`1`		`-Note: Use Note for ancillary/additional information that's not _essential_ to the main text.`
	`1`	`+NOTE: Use Note for ancillary/additional information that's not _essential_ to the main text.`
`2`	`2`	`This is a multiline note`
`3`	`3`
`4`	`4`	`TIP: Use Tip to call out a specific task/action users can perform, or a fact that plays directly into a task/action.`