docs(docs-infra): throw when rendering absolute links to adev in our guides

JeanMeche · AndrewKushnir · commit b5205c7c42a9 · 2025-12-15T09:45:04.000-08:00
This is to prevent any further regressions in the future
diff --git a/adev/shared-docs/pipeline/shared/marked/renderer.mts b/adev/shared-docs/pipeline/shared/marked/renderer.mts
@@ -42,6 +42,10 @@ export class AdevDocsRenderer extends Renderer {
 
   defaultRenderer = new Renderer();
 
+  isGuideFile(): boolean {
+    return this.context.markdownFilePath?.includes('/content/guide') ?? false;
+  }
+
   override link = linkRender;
   override table = tableRender;
   override list = listRender;
diff --git a/adev/shared-docs/pipeline/shared/marked/test/link/link.md b/adev/shared-docs/pipeline/shared/marked/test/link/link.md
@@ -1,4 +1,4 @@
-[Angular Site](https://angular.dev)
+[Please click](https://www.youtube.com/watch?v=dQw4w9WgXcQ)
 [same page](#test)
 [same site](../other/page)
 [npm packages](https://docs.npmjs.com/getting-started/what-is-npm 'What is npm?')
diff --git a/adev/shared-docs/pipeline/shared/marked/test/link/link.spec.mts b/adev/shared-docs/pipeline/shared/marked/test/link/link.spec.mts
@@ -20,7 +20,7 @@ describe('markdown to html', () => {
 
   it('should render external links with _blank target', () => {
     expect(parsedMarkdown).toContain(
-      '<a href="https://angular.dev" target="_blank">Angular Site</a>',
+      '<a href="https://www.youtube.com/watch?v=dQw4w9WgXcQ" target="_blank">Please click</a>',
     );
   });
 
@@ -37,4 +37,17 @@ describe('markdown to html', () => {
       '<a href="https://docs.npmjs.com/getting-started/what-is-npm" title="What is npm?" target="_blank">npm packages</a>',
     );
   });
+
+  it('should throw if on absolute links to adev', async () => {
+    try {
+      parsedMarkdown = await parseMarkdown(
+        '[Some absolute link](https://angular.dev/yeah-nope-should-be-relative)',
+        {...rendererContext, markdownFilePath: '/content/guide/some-guide.md'},
+      );
+    } catch (e: any) {
+      expect(e.message).toContain('Absolute links to angular.dev are not allowed');
+      return;
+    }
+    fail('Did not throw for absolute link to angular.dev');
+  });
 });
diff --git a/adev/shared-docs/pipeline/shared/marked/test/list/list.md b/adev/shared-docs/pipeline/shared/marked/test/list/list.md
@@ -10,5 +10,5 @@
 - here
 - matter
 - doesn't
-- [some link](https://angular.dev)
+- [some link](https://www.youtube.com/watch?v=dQw4w9WgXcQ)
 - Code block `SomeClass`
diff --git a/adev/shared-docs/pipeline/shared/marked/test/list/list.spec.mts b/adev/shared-docs/pipeline/shared/marked/test/list/list.spec.mts
@@ -35,7 +35,7 @@ describe('markdown to html', () => {
   it('should render list items', () => {
     const unorderedList = markdownDocument.querySelector('ul');
     const linkItem = unorderedList!.children[4];
-    expect(linkItem.outerHTML).toContain('href="https://angular.dev"');
+    expect(linkItem.outerHTML).toContain('href="https://www.youtube.com/watch?v=dQw4w9WgXcQ"');
 
     const codeItem = unorderedList!.children[5];
     expect(codeItem.outerHTML).toContain('<code>SomeClass</code>');
diff --git a/adev/shared-docs/pipeline/shared/marked/transformations/link.mts b/adev/shared-docs/pipeline/shared/marked/transformations/link.mts
@@ -8,6 +8,7 @@
 
 import {anchorTarget} from '../helpers.mjs';
 import {Renderer, Tokens} from 'marked';
+import {AdevDocsRenderer} from '../renderer.mjs';
 
 /**
  * Tracks whether the current renderer is inside a link.
@@ -19,7 +20,20 @@ export function setInsideLink(value: boolean) {
   insideLink = value;
 }
 
-export function linkRender(this: Renderer, {href, title, tokens}: Tokens.Link) {
+export function linkRender(this: AdevDocsRenderer, {href, title, tokens}: Tokens.Link) {
+  // We have render-time check that we don't create absolute links (which are rendered as external links)
+  // in our guides
+  if (
+    (href.startsWith('https://angular.dev/') || href.startsWith('http://angular.dev/')) &&
+    this.isGuideFile()
+  ) {
+    Error.stackTraceLimit = Infinity;
+    throw new Error(
+      `Absolute links to angular.dev are not allowed: "${href}". Please use relative links instead.` +
+        `\n ----------------------------- \n ${(this as any).__raw}`,
+    );
+  }
+
   if (insideLink) {
     return this.parser.parseInline(tokens);
   }
diff --git a/adev/src/content/ai/mcp-server-setup.md b/adev/src/content/ai/mcp-server-setup.md
@@ -22,7 +22,7 @@ Some tools are provided in experimental / preview status since they are new or n
 | Name                       | Description                                                                                                                                                                                                                                                         | `local-only` | `read-only` |
 | :------------------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | :----------: | :---------: |
 | `build`                    | Perform a one-off, non-watched build using `ng build`.                                                                                                                                                                                                              |      ✅      |     ❌      |
-| `modernize`                | Performs code migrations and provides further instructions on how to modernize Angular code to align with the latest best practices and syntax. [Learn more](https://angular.dev/reference/migrations)                                                              |      ✅      |     ❌      |
+| `modernize`                | Performs code migrations and provides further instructions on how to modernize Angular code to align with the latest best practices and syntax. [Learn more](/reference/migrations)                                                                                 |      ✅      |     ❌      |
 | `start_devserver`          | Asynchronously starts a development server that watches the workspace for changes, similar to running `ng serve`. Since this is asynchronous it returns immediately. To manage the resulting server, use the `stop_devserver` and `wait_for_devserver_build` tools. |      ✅      |     ✅      |
 | `stop_devserver`           | Stops a development server started by `start_devserver`.                                                                                                                                                                                                            |      ✅      |     ✅      |
 | `wait_for_devserver_build` | Returns the output logs of the most recent build in a running development server started by `start_devserver`. If a build is currently ongoing, it will first wait for that build to complete and then return the logs.                                             |      ✅      |     ✅      |
diff --git a/adev/src/content/guide/ngmodules/overview.md b/adev/src/content/guide/ngmodules/overview.md
@@ -173,7 +173,7 @@ IMPORTANT: The Angular team recommends using [bootstrapApplication](api/platform
 
 The `@NgModule` decorator accepts an optional `bootstrap` array that may contain one or more components.
 
-You can use the [`bootstrapModule`](https://angular.dev/api/core/PlatformRef#bootstrapModule) method from either [`platformBrowser`](api/platform-browser/platformBrowser) or [`platformServer`](api/platform-server/platformServer) to start an Angular application. When run, this function locates any elements on the page with a CSS selector that matches the listed componet(s) and renders those components on the page.
+You can use the [`bootstrapModule`](/api/core/PlatformRef#bootstrapModule) method from either [`platformBrowser`](api/platform-browser/platformBrowser) or [`platformServer`](api/platform-server/platformServer) to start an Angular application. When run, this function locates any elements on the page with a CSS selector that matches the listed componet(s) and renders those components on the page.
 
 ```typescript
 import {platformBrowser} from '@angular/platform-browser';
diff --git a/adev/src/content/guide/testing/using-component-harnesses.md b/adev/src/content/guide/testing/using-component-harnesses.md
@@ -177,7 +177,7 @@ it('should get value of slider thumb', async () => {
 
 ## Interop with Angular change detection
 
-By default, test harnesses runs Angular's [change detection](https://angular.dev/best-practices/runtime-performance) before reading the state of a DOM element and after interacting with a DOM element.
+By default, test harnesses runs Angular's [change detection](/best-practices/runtime-performance) before reading the state of a DOM element and after interacting with a DOM element.
 
 There may be times that you need finer-grained control over change detection in your tests. such as checking the state of a component while an async operation is pending. In these cases use the `manualChangeDetection` function to disable automatic handling of change detection for a block of code.
 
diff --git a/adev/src/content/reference/cli.md b/adev/src/content/reference/cli.md
@@ -17,5 +17,5 @@
 | [`run`](cli/run)                   |            | Runs an Architect target with an optional custom builder configuration defined in your project.           |
 | [`serve`](cli/serve)               | `s`, `dev` | Builds and serves your application, rebuilding on file changes.                                           |
 | [`test`](cli/test)                 | `t`        | Runs unit tests in a project.                                                                             |
-| [`update`](cli/update)             |            | Updates your workspace and its dependencies. See https://angular.dev/update-guide/.                       |
+| [`update`](cli/update)             |            | Updates your workspace and its dependencies. See the [Update Guide](/update-guide).                       |
 | [`version`](cli/version)           | `v`        | Outputs Angular CLI version.                                                                              |
diff --git a/adev/src/content/reference/errors/NG0913.md b/adev/src/content/reference/errors/NG0913.md
@@ -15,12 +15,12 @@ Use the image URL provided in the console warning to find the `<img>` element in
 
 - Use a smaller source image
 - Add a [`srcset`](https://web.dev/learn/design/responsive-images/#responsive-images-with-srcset) if multiple sizes are needed for different layouts.
-- Switch to use Angular's built-in image directive ([`NgOptimizedImage`](https://angular.dev/api/common/NgOptimizedImage)), which generates [srcsets automatically](https://angular.dev/guide/image-optimization#request-images-at-the-correct-size-with-automatic-srcset).
+- Switch to use Angular's built-in image directive ([`NgOptimizedImage`](/api/common/NgOptimizedImage)), which generates [srcsets automatically](/guide/image-optimization#request-images-at-the-correct-size-with-automatic-srcset).
 
 ### Ways to fix lazy-loaded LCP element
 
 - Change the `loading` attribute to a different value such as `"eager"`.
-- Switch to use Angular's built-in image directive ([`NgOptimizedImage`](https://angular.dev/api/common/NgOptimizedImage)), which allows for easily [prioritizing LCP images](https://angular.dev/guide/image-optimization#mark-images-as-priority).
+- Switch to use Angular's built-in image directive ([`NgOptimizedImage`](/dev/api/common/NgOptimizedImage)), which allows for easily [prioritizing LCP images](/guide/image-optimization#mark-images-as-priority).
 
 ### Disabling Image Performance Warnings
 
diff --git a/adev/src/content/reference/license.md b/adev/src/content/reference/license.md
@@ -1,6 +1,6 @@
 # The MIT License
 
-Copyright (c) 2010-2025 Google LLC. https://angular.dev/license
+Copyright (c) 2010-2025 Google LLC. [https://angular.dev/license](/license)
 
 Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
 
diff --git a/adev/src/content/reference/roadmap.md b/adev/src/content/reference/roadmap.md
@@ -149,7 +149,7 @@ To make it easier for developers to use modern Angular APIs, we enabled integrat
 As part of this initiative, the language service automatically imports components and pipes in standalone and NgModule-based apps. Additionally, we've added a template diagnostic to highlight unused imports in standalone components, which should help make application bundles smaller.
 </docs-card>
 <docs-card title="Local template variables" link="Completed in Q3 2024">
-We've released the support for local template variables in Angular, see [`@let` docs](https://angular.dev/api/core/@let) for additional information.
+We've released the support for local template variables in Angular, see [`@let` docs](/api/core/@let) for additional information.
 </docs-card>
 <docs-card title="Expand the customizability of Angular Material" link="Completed in Q2 2024" href="https://material.angular.dev/guide/theming">
 To provide better customization of our Angular Material components and enable Material 3 capabilities, we'll be collaborating with Google's Material Design team on defining token-based theming APIs.
@@ -172,7 +172,7 @@ Angular.dev is the new site, domain and home for Angular development. The new si
 In v17 we shipped a developer preview version of a new control flow. It brings significant performance improvements and better ergonomics for template authoring. We also provided a migration of existing `*ngIf`, `*ngFor`, and `*ngSwitch` which you can run to move your project to the new implementation. As of v18 the built-in control flow is now stable.
 </docs-card>
 <docs-card title="Modernize getting started tutorial" link="Completed Q4 2023" href="">
-Over the past two quarters, we developed a new [video](https://www.youtube.com/watch?v=xAT0lHYhHMY&list=PL1w1q3fL4pmj9k1FrJ3Pe91EPub2_h4jF) and [textual](https://angular.dev/tutorials/learn-angular) tutorial based on standalone components.
+Over the past two quarters, we developed a new [video](https://www.youtube.com/watch?v=xAT0lHYhHMY&list=PL1w1q3fL4pmj9k1FrJ3Pe91EPub2_h4jF) and [textual](/tutorials/learn-angular) tutorial based on standalone components.
 </docs-card>
 <docs-card title="Investigate modern bundlers" link="Completed Q4 2023" href="guide/hydration">
 In Angular v16, we released a developer preview of an esbuild-based builder with support for `ng build` and `ng serve`. The `ng serve` development server uses Vite and a multi-file compilation by esbuild and the Angular compiler. In v17 we graduated the build tooling from developer preview and enabled it by default for new projects.
diff --git a/adev/src/content/tools/libraries/using-libraries.md b/adev/src/content/tools/libraries/using-libraries.md
@@ -171,7 +171,7 @@ If you do not add the interface for the script-defined extension, your IDE shows
 [GuideWorkspaceConfig]: reference/configs/workspace-config 'Angular workspace configuration | Angular'
 [Resources]: resources 'Explore Angular Resources | Angular'
 [AngularMaterialMain]: https://material.angular.dev 'Angular Material | Angular'
-[AngularUpdateMain]: https://angular.dev/update-guide 'Angular Update Guide | Angular'
+[AngularUpdateMain]: /update-guide 'Angular Update Guide | Angular'
 [GetbootstrapDocs40GettingStartedIntroduction]: https://getbootstrap.com/docs/4.0/getting-started/introduction 'Introduction | Bootstrap'
 [NpmjsMain]: https://www.npmjs.com 'npm'
 [YarnpkgMain]: https://yarnpkg.com ' Yarn'
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
@@ -74,7 +74,7 @@ Next, update the template to include a button with the label "Show all comments"
 }
 ```
 
-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](/guide/templates/reference-variables).
 
 </docs-step>
 
@@ -105,5 +105,5 @@ You can reload the page to try out different triggers to render the comments sec
 </docs-step>
 </docs-workflow>
 
-If you would like to learn more, check out the documentation for [Deferrable View](https://angular.dev/guide/defer).
+If you would like to learn more, check out the documentation for [Deferrable View](/guide/defer).
 Keep learning to unlock more of Angular's great features.
