docs(docs-infra): prevent heading from linking symbols

Author: JeanMeche

adev/shared-docs/pipeline/shared/marked/extensions/docs-card/docs-card.mts

@@ -6,9 +6,9 @@
  * found in the LICENSE file at https://angular.dev/license
  */
 
-import {Tokens, Token, RendererThis, TokenizerThis} from 'marked';
-import {loadWorkspaceRelativeFile, anchorTarget} from '../../helpers.mjs';
-import {setInsideLink} from '../../transformations/link.mjs';
+import {RendererThis, Token, TokenizerThis, Tokens} from 'marked';
+import {anchorTarget, loadWorkspaceRelativeFile} from '../../helpers.mjs';
+import {AdevDocsRenderer} from '../../renderer.mjs';
 
 interface DocsCardToken extends Tokens.Generic {
   type: 'docs-card';
@@ -67,11 +67,13 @@ export const docsCardExtension = {
     return undefined;
   },
   renderer(this: RendererThis, token: DocsCardToken) {
-    return token.imgSrc ? getCardWithSvgIllustration(this, token) : getStandardCard(this, token);
+    return token.imgSrc
+      ? getCardWithSvgIllustration(this, token)
+      : getStandardCard(this.parser.renderer as AdevDocsRenderer, token);
   },
 };
 
-function getStandardCard(renderer: RendererThis, token: DocsCardToken) {
+function getStandardCard(renderer: AdevDocsRenderer, token: DocsCardToken) {
   if (token.iconImgSrc && token.href) {
     // We can assume that all icons are svg files since they are custom.
     // We need to read svg content, instead of renering svg with `img`,
@@ -110,13 +112,11 @@ function getStandardCard(renderer: RendererThis, token: DocsCardToken) {
   `;
 }
 
-function parseWithoutCreatingLinks(renderer: RendererThis, token: DocsCardToken) {
-  setInsideLink(true);
-  try {
-    return renderer.parser.parse(token.tokens);
-  } finally {
-    setInsideLink(false);
-  }
+function parseWithoutCreatingLinks(renderer: AdevDocsRenderer, token: DocsCardToken) {
+  renderer.context.disableAutoLinking = true;
+  const parsed = renderer.parser.parse(token.tokens);
+  renderer.context.disableAutoLinking = false;
+  return parsed;
 }
 
 function getCardWithSvgIllustration(renderer: RendererThis, token: DocsCardToken) {

adev/shared-docs/pipeline/shared/marked/renderer.mts

@@ -31,6 +31,8 @@ export interface RendererContext {
   apiEntries?: Record<string, {moduleName: string; aliases?: string[]}>;
   highlighter: HighlighterGeneric<any, any>;
   headerIds: Map<string, number>;
+  /** In the case we want to disable auto-linking because anchor blocks might be incompatible where some code blocks are being rendered */
+  disableAutoLinking: boolean;
 }
 
 /**

adev/shared-docs/pipeline/shared/marked/test/heading/heading.spec.mts

@@ -6,10 +6,10 @@
  * found in the LICENSE file at https://angular.dev/license
  */
 
-import {parseMarkdown} from '../../parse.mjs';
-import {resolve} from 'node:path';
 import {readFile} from 'fs/promises';
 import {JSDOM} from 'jsdom';
+import {resolve} from 'node:path';
+import {parseMarkdown} from '../../parse.mjs';
 import {rendererContext} from '../renderer-context.mjs';
 
 describe('markdown to html', () => {
@@ -118,4 +118,17 @@ describe('markdown to html', () => {
 
     expect(h2.firstElementChild!.innerHTML).toBe('Query for the <code>&lt;h1&gt;</code>');
   });
+
+  it('shoud now link symbols in headings', () => {
+    const markdownDocument = JSDOM.fragment(
+      parseMarkdown('## Hello **NEW** `Router` ', rendererContext),
+    );
+    const h2 = markdownDocument.querySelector('h2')!;
+
+    // The anchor element should be to only child, no nested anchor
+    expect(h2.children.length).toBe(1);
+
+    // We ensure that we still style the heading content
+    expect(markdownDocument.querySelector('strong')).toBeDefined();
+  });
 });

adev/shared-docs/pipeline/shared/marked/test/renderer-context.mts

@@ -25,6 +25,7 @@ export const rendererContext: RendererContext = {
     Router: {moduleName: 'angular/router'},
   },
   headerIds: new Map<string, number>(),
+  disableAutoLinking: false,
 };
 
 export async function setHighlighter() {

adev/shared-docs/pipeline/shared/marked/transformations/heading.mts

@@ -13,7 +13,9 @@ export function headingRender(
   this: AdevDocsRenderer,
   {depth, tokens, text: headingText, raw}: Tokens.Heading,
 ): string {
-  const parsedText = this?.parser.parseInline(tokens);
+  this.context.disableAutoLinking = true;
+  const parsedText = this?.parser.parseInline(tokens, this);
+  this.context.disableAutoLinking = false;
   if (depth === 1) {
     return `
     <header class="docs-header">

adev/shared-docs/pipeline/shared/marked/transformations/link.mts

@@ -6,20 +6,10 @@
  * found in the LICENSE file at https://angular.dev/license
  */
 
+import {Tokens} from 'marked';
 import {anchorTarget} from '../helpers.mjs';
-import {Renderer, Tokens} from 'marked';
 import {AdevDocsRenderer} from '../renderer.mjs';
 
-/**
- * Tracks whether the current renderer is inside a link.
- *
- * This is necessary because nested links are invalid HTML and can cause rendering issues.
- */
-let insideLink = false;
-export function setInsideLink(value: boolean) {
-  insideLink = value;
-}
-
 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
@@ -40,7 +30,7 @@ export function linkRender(this: AdevDocsRenderer, {href, title, tokens}: Tokens
     );
   }
 
-  if (insideLink) {
+  if (this.context.disableAutoLinking) {
     return this.parser.parseInline(tokens);
   }