docs: add check for non-existing anchor (angular#64309)

This is only for the anchors on the same document for now.
Commit also includes some reformating.

fixes angular#64303

PR Close angular#64309

Author: JeanMeche

adev/shared-docs/pipeline/guides/BUILD.bazel

@@ -60,6 +60,7 @@ ts_project(
         "//adev/shared-docs:__subpackages__",
     ],
     deps = [
+        "//adev:node_modules/jsdom",
         "//adev/shared-docs/pipeline/shared:shiki",
         "//adev/shared-docs/pipeline/shared/marked",
     ],

adev/shared-docs/pipeline/guides/helpers.mts

@@ -6,6 +6,8 @@
  * found in the LICENSE file at https://angular.dev/license
  */
 
+import {JSDOM} from 'jsdom';
+
 /** Whether the link provided is external to the application. */
 export function isExternalLink(href: string | undefined | null) {
   return href?.startsWith('http') ?? false;
@@ -15,3 +17,24 @@ export function isExternalLink(href: string | undefined | null) {
 export function anchorTarget(href: string | undefined | null) {
   return isExternalLink(href) ? ` target="_blank"` : '';
 }
+
+/**
+ *
+ * @param htmlString
+ * @returns the first unknown anchor found or undefined if all anchors are valid
+ */
+export function hasUnknownAnchors(htmlString: string) {
+  const fragment = JSDOM.fragment(htmlString);
+  const anchors = fragment.querySelectorAll('a');
+  return Array.from(anchors).find((anchor) => {
+    const href = anchor.getAttribute('href');
+    if (href?.startsWith('#')) {
+      const id = href.slice(1);
+      const target = fragment.getElementById(id);
+      if (!target) {
+        return href;
+      }
+    }
+    return undefined;
+  });
+}

adev/shared-docs/pipeline/guides/index.mts

@@ -10,6 +10,7 @@ import {readFileSync, writeFileSync} from 'fs';
 import path from 'path';
 import {initHighlighter} from '../shared/shiki.mjs';
 import {parseMarkdownAsync} from '../shared/marked/parse.mjs';
+import {hasUnknownAnchors} from './helpers.mjs';
 
 type ApiManifest = ApiManifestPackage[];
 interface ApiManifestPackage {
@@ -52,6 +53,13 @@ async function main() {
     const htmlFileName = filePath + '.html';
     const htmlOutputPath = path.join(outputFilenameExecRootRelativePath, htmlFileName);
 
+    const unknownAnchor = hasUnknownAnchors(htmlOutputContent);
+    if (unknownAnchor) {
+      throw new Error(
+        `The file "${filePath}" contains an anchor link to "${unknownAnchor}" which does not exist in the document.`,
+      );
+    }
+
     writeFileSync(htmlOutputPath, htmlOutputContent, {encoding: 'utf8'});
   }
 }

adev/src/content/ecosystem/service-workers/config.md

@@ -56,7 +56,7 @@ The in-application URLs can be indistinguishable from server URLs.
 Modern HTML5 browsers were the first to support `pushState` which is why many people refer to these URLs as "HTML5 style" URLs.
 
 HELPFUL: HTML5 style navigation is the router default.
-In the [LocationStrategy and browser URL styles](#locationstrategy-and-browser-url-styles) section, learn why HTML5 style is preferable, how to adjust its behavior, and how to switch to the older hash \(`#`\) style, if necessary.
+In the [LocationStrategy and browser URL styles](common-router-tasks#locationstrategy-and-browser-url-styles) section, learn why HTML5 style is preferable, how to adjust its behavior, and how to switch to the older hash \(`#`\) style, if necessary.
 
 You must add a [`<base href>` element](https://developer.mozilla.org/docs/Web/HTML/Element/base 'base href') to the application's `index.html` for `pushState` routing to work.
 The browser uses the `<base href>` value to prefix relative URLs when referencing CSS files, scripts, and images.
@@ -94,7 +94,6 @@ Those developers can still use HTML5 URLs by taking the following two steps:
 
 1. Provide the router with an appropriate `APP_BASE_HREF` value.
 1. Use root URLs \(URLs with an `authority`\) for all web resources: CSS, images, scripts, and template HTML files.
-
    - The `<base href>` `path` should end with a "/", as browsers ignore characters in the `path` that follow the right-most "`/`"
    - If the `<base href>` includes a `query` part, the `query` is only used if the `path` of a link in the page is empty and has no `query`.
      This means that a `query` in the `<base href>` is only included when using `HashLocationStrategy`.

adev/src/content/guide/routing/router-reference.md

@@ -4,11 +4,11 @@ This is a visual list of all custom components and styles for Angular.dev.
 
 As a design system, this page contains visual and Markdown authoring guidance for:
 
-* Custom Angular docs elements: [`docs-card`](#cards), [`docs-callout`](#callouts), [`docs-pill`](#pills), and [`docs-steps`](#workflow)
-* Custom text elements: [alerts](#alerts)
-* Code examples: [`docs-code`](#code)
-* Built-in Markdown styled elements: links, lists, [headers](#headers), [horizontal lines](#horizontal-line-divider), [tables](#tables)
-* and more!
+- Custom Angular docs elements: [`docs-card`](#cards), [`docs-callout`](#callouts), [`docs-pill`](#pills), and [`docs-steps`](#workflow)
+- Custom text elements: [alerts](#alerts)
+- Code examples: [`docs-code`](#code)
+- Built-in Markdown styled elements: links, lists, [headers](#headers-h2), [horizontal lines](#horizontal-line-divider)
+- and more!
 
 Get ready to:
 
@@ -42,13 +42,13 @@ Get ready to:
 
 ### `<docs-card>` Attributes
 
-| Attributes               | Details                                           |
-|:---                      |:---                                               |
-| `<docs-card-container>`  | All cards must be nested inside a container       |
-| `title`                  | Card title                                        |
-| card body contents       | Anything between `<docs-card>` and `</docs-card>` |
-| `link`                   | (Optional) Call to Action link text               |
-| `href`                   | (Optional) Call to Action link href               |
+| Attributes              | Details                                           |
+| :---------------------- | :------------------------------------------------ |
+| `<docs-card-container>` | All cards must be nested inside a container       |
+| `title`                 | Card title                                        |
+| card body contents      | Anything between `<docs-card>` and `</docs-card>` |
+| `link`                  | (Optional) Call to Action link text               |
+| `href`                  | (Optional) Call to Action link href               |
 
 ## Callouts
 
@@ -67,7 +67,7 @@ Get ready to:
 ### `<docs-callout>` Attributes
 
 | Attributes                                       | Details                                                   |
-|:---                                              |:---                                                       |
+| :----------------------------------------------- | :-------------------------------------------------------- |
 | `title`                                          | Callout title                                             |
 | card body contents                               | Anything between `<docs-callout>` and `</docs-callout>`   |
 | `helpful` (default) \| `critical` \| `important` | (Optional) Adds styling and icons based on severity level |
@@ -76,7 +76,7 @@ Get ready to:
 
 Pill rows are helpful as a sort of navigation with links to helpful resources.
 
-<docs-pill-row>
+<docs-pill-row id=pill-row>
   <docs-pill href="#pill-row" title="Link"/>
   <docs-pill href="#pill-row" title="Link"/>
   <docs-pill href="#pill-row" title="Link"/>
@@ -87,11 +87,11 @@ Pill rows are helpful as a sort of navigation with links to helpful resources.
 
 ### `<docs-pill>` Attributes
 
-| Attributes               | Details                                      |
-|:---                      |:---                                          |
-| `<docs-pill-row`         | All pills must be nested inside a pill row   |
-| `title`                  | Pill text                                    |
-| `href`                   | Pill href                                    |
+| Attributes       | Details                                    |
+| :--------------- | :----------------------------------------- |
+| `<docs-pill-row` | All pills must be nested inside a pill row |
+| `title`          | Pill text                                  |
+| `href`           | Pill href                                  |
 
 Pills may also be used inline by themselves, but we haven't built that out yet.
 
@@ -135,8 +135,8 @@ Or using the `<docs-code>` element.
 import { Component } from '@angular/core';
 
 @Component({
-  selector: 'example-code',
-  template: '<h1>Hello World!</h1>',
+selector: 'example-code',
+template: '<h1>Hello World!</h1>',
 })
 export class ComponentOverviewComponent {}
 </docs-code>
@@ -163,19 +163,19 @@ We also have styling for the terminal, just set the language as `shell`:
 
 #### `<docs-code>` Attributes
 
-| Attributes               | Type        | Details                                              |
-|:---                      |:---         |:---                                                  |
-| code                     | `string`    | Anything between tags is treated as code             |
-| `path`                   | `string`    | Path to code example (root: `content/examples/`)     |
-| `header`                 | `string`    | Title of the example (default: `file-name`)          |
-| `language`               | `string`    | code language                                        |
-| `linenums`               | `boolean`   | (False) displays line numbers                        |
-| `highlight`              | `string of number[]` | lines highlighted                           |
-| `diff`                   | `string`    | path to changed code                                 |
-| `visibleLines`           | `string of number[]` | range of lines for collapse mode            |
-| `visibleRegion`          | `string`    | **DEPRECATED** FOR `visibleLines`                    |
-| `preview`                | `boolean`   | (False) display preview                              |
-| `hideCode`               | `boolean`   | (False) Whether to collapse code example by default. |
+| Attributes      | Type                 | Details                                              |
+| :-------------- | :------------------- | :--------------------------------------------------- |
+| code            | `string`             | Anything between tags is treated as code             |
+| `path`          | `string`             | Path to code example (root: `content/examples/`)     |
+| `header`        | `string`             | Title of the example (default: `file-name`)          |
+| `language`      | `string`             | code language                                        |
+| `linenums`      | `boolean`            | (False) displays line numbers                        |
+| `highlight`     | `string of number[]` | lines highlighted                                    |
+| `diff`          | `string`             | path to changed code                                 |
+| `visibleLines`  | `string of number[]` | range of lines for collapse mode                     |
+| `visibleRegion` | `string`             | **DEPRECATED** FOR `visibleLines`                    |
+| `preview`       | `boolean`            | (False) display preview                              |
+| `hideCode`      | `boolean`            | (False) Whether to collapse code example by default. |
 
 ### Multifile examples
 
@@ -184,43 +184,43 @@ You can create multifile examples by wrapping the examples inside a `<docs-code-
 <docs-code-multifile
   path="adev/src/content/examples/hello-world/src/app/app.component.ts"
   preview>
-  <docs-code
+<docs-code
     path="adev/src/content/examples/hello-world/src/app/app.component.ts"
     diff="adev/src/content/examples/hello-world/src/app/app.component-old.ts"
     linenums
     visibleLines="[3, 11]"/>
-  <docs-code
+<docs-code
     path="adev/src/content/examples/hello-world/src/app/app.component.html"
     highlight="[1]"
     linenums/>
-  <docs-code
+<docs-code
     path="adev/src/content/examples/hello-world/src/app/app.component.css" />
 </docs-code-multifile>
 
 #### `<docs-code-multifile>` Attributes
 
-| Attributes               | Type        | Details                                              |
-|:---                      |:---         |:---                                                  |
-| body contents            | `string`    | nested tabs of `docs-code` examples                  |
-| `path`                   | `string`    | Path to code example for preview and external link   |
-| `preview`                | `boolean`   | (False) display preview                              |
-| `hideCode`               | `boolean`   | (False) Whether to collapse code example by default. |
+| Attributes    | Type      | Details                                              |
+| :------------ | :-------- | :--------------------------------------------------- |
+| body contents | `string`  | nested tabs of `docs-code` examples                  |
+| `path`        | `string`  | Path to code example for preview and external link   |
+| `preview`     | `boolean` | (False) display preview                              |
+| `hideCode`    | `boolean` | (False) Whether to collapse code example by default. |
 
 ### Adding `preview` to your code example
 
 Adding the `preview` flag builds a running example of the code below the code snippet. This also automatically adds a button to open the running example in Stackblitz.
 
 NOTE: `preview` only works with standalone.
 
-### Styling example previews with Tailwind CSS 
+### Styling example previews with Tailwind CSS
 
 Tailwind utility classes can be used within code examples.
 
 <docs-code-multifile
   path="adev/src/content/examples/hello-world/src/app/tailwind-app.component.ts"
   preview>
-  <docs-code path="adev/src/content/examples/hello-world/src/app/tailwind-app.component.html" />
-  <docs-code path="adev/src/content/examples/hello-world/src/app/tailwind-app.component.ts" />
+<docs-code path="adev/src/content/examples/hello-world/src/app/tailwind-app.component.html" />
+<docs-code path="adev/src/content/examples/hello-world/src/app/tailwind-app.component.ts" />
 </docs-code-multifile>
 
 ## Workflow
@@ -229,11 +229,11 @@ Style numbered steps using `<docs-step>`. Numbering is created using CSS (handy!
 
 ### `<docs-workflow>` and `<docs-step>` Attributes
 
-| Attributes               | Details                                           |
-|:---                      |:---                                               |
-| `<docs-workflow>`        | All steps must be nested inside a workflow        |
-| `title`                  | Step title                                        |
-| step body contents       | Anything between `<docs-step>` and `</docs-step>` |
+| Attributes         | Details                                           |
+| :----------------- | :------------------------------------------------ |
+| `<docs-workflow>`  | All steps must be nested inside a workflow        |
+| `title`            | Step title                                        |
+| step body contents | Anything between `<docs-step>` and `</docs-step>` |
 
 Steps must start on a new line, and can contain `docs-code`s and other nested elements and styles.
 
@@ -242,7 +242,7 @@ Steps must start on a new line, and can contain `docs-code`s and other nested el
 <docs-step title="Install the Angular CLI">
   You use the Angular CLI to create projects, generate application and library code, and perform a variety of ongoing development tasks such as testing, bundling, and deployment.
 
-  To install the Angular CLI, open a terminal window and run the following command:
+To install the Angular CLI, open a terminal window and run the following command:
 
   <docs-code language="shell">
     npm install -g @angular/cli
@@ -252,34 +252,34 @@ Steps must start on a new line, and can contain `docs-code`s and other nested el
 <docs-step title="Create a workspace and initial application">
   You develop apps in the context of an Angular workspace.
 
-  To create a new workspace and initial starter app:
+To create a new workspace and initial starter app:
 
-* Run the CLI command `ng new` and provide the name `my-app`, as shown here:
-    <docs-code language="shell">
-      ng new my-app
-    </docs-code>
+- Run the CLI command `ng new` and provide the name `my-app`, as shown here:
+  <docs-code language="shell">
+  ng new my-app
+  </docs-code>
 
-* The ng new command prompts you for information about features to include in the initial app. Accept the defaults by pressing the Enter or Return key.
+- The ng new command prompts you for information about features to include in the initial app. Accept the defaults by pressing the Enter or Return key.
 
   The Angular CLI installs the necessary Angular npm packages and other dependencies. This can take a few minutes.
 
   The CLI creates a new workspace and a simple Welcome app, ready to run.
-</docs-step>
+  </docs-step>
 
 <docs-step title="Run the application">
   The Angular CLI includes a server, for you to build and serve your app locally.
 
-  1. Navigate to the workspace folder, such as `my-app`.
-  2. Run the following command:
-    <docs-code language="shell">
-      cd my-app
-      ng serve --open
-    </docs-code>
+1. Navigate to the workspace folder, such as `my-app`.
+2. Run the following command:
+   <docs-code language="shell">
+   cd my-app
+   ng serve --open
+   </docs-code>
 
-  The `ng serve` command launches the server, watches your files, and rebuilds the app as you make changes to those files.
+The `ng serve` command launches the server, watches your files, and rebuilds the app as you make changes to those files.
 
-  The `--open` (or just `-o`) option automatically opens your browser to <http://localhost:4200/>.
-  If your installation and setup was successful, you should see a page similar to the following.
+The `--open` (or just `-o`) option automatically opens your browser to <http://localhost:4200/>.
+If your installation and setup was successful, you should see a page similar to the following.
 </docs-step>
 
 <docs-step title="Final step">
@@ -299,7 +299,7 @@ Steps must start on a new line, and can contain `docs-code`s and other nested el
 
 You can add images using the semantic Markdown image:
 
-![Rhubarb the cat](assets/images/kitchen-sink/rhubarb.jpg "Optional title")
+![Rhubarb the cat](assets/images/kitchen-sink/rhubarb.jpg 'Optional title')
 
 ### Add `#small` and `#medium` to change the image size
 
@@ -339,7 +339,7 @@ Write diagrams and charts using [Mermaid](http://mermaid.js.org/) by setting the
 
 ## Horizontal Line Divider
 
-This can be used to separate page sections, like we're about to do below.  These styles will be added by default, nothing custom needed.
+This can be used to separate page sections, like we're about to do below. These styles will be added by default, nothing custom needed.
 
 <hr/>