feat(docs-infra): add docs-image extension for enhanced image handling in markdown

Extends the Markdown parser to support `loading`, `decoding`, and `fetchpriority` attributes for images via curly brace syntax.

Author: SkyZeroZx

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

@@ -0,0 +1,53 @@
+/*!
+ * @license
+ * Copyright Google LLC All Rights Reserved.
+ *
+ * Use of this source code is governed by an MIT-style license that can be
+ * found in the LICENSE file at https://angular.dev/license
+ */
+
+import {TokenizerThis, Tokens} from 'marked';
+
+export interface DocsImage extends Tokens.Image {
+  loading?: string;
+  decoding?: string;
+  fetchpriority?: string;
+}
+
+// Regex to match image syntax: ![alt](url {attrs} 'title') or ![alt](url 'title')
+const imageRule = /^!\[([^\]]*)\]\(([^)\s]+)(?:\s+\{([^}]+)\})?(?:\s+['"]([^'"]+)['"])?\)/;
+
+export const docsImageExtension = {
+  name: 'docs-image',
+  level: 'inline' as const,
+  start(src: string) {
+    return src.match(/!\[/)?.index;
+  },
+  tokenizer(this: TokenizerThis, src: string): DocsImage | undefined {
+    const match = imageRule.exec(src);
+    if (match) {
+      const text = match[1];
+      const href = match[2];
+      const metadataStr = match[3] || '';
+      const title = match[4] || null;
+
+      const loadingRule = /loading\s*:\s*(['"`])([^'"`]+)\1/;
+      const decodingRule = /decoding\s*:\s*(['"`])([^'"`]+)\1/;
+      const fetchpriorityRule = /fetchpriority\s*:\s*(['"`])([^'"`]+)\1/;
+
+      const token: DocsImage = {
+        type: 'image',
+        raw: match[0],
+        href,
+        title,
+        text,
+        tokens: [],
+        loading: loadingRule.exec(metadataStr)?.[2],
+        decoding: decodingRule.exec(metadataStr)?.[2],
+        fetchpriority: fetchpriorityRule.exec(metadataStr)?.[2],
+      };
+      return token;
+    }
+    return undefined;
+  },
+};

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

@@ -23,10 +23,13 @@ import {docsCodeBlockExtension} from './extensions/docs-code/docs-code-block.mjs
 import {docsCodeExtension, DocsCodeToken} from './extensions/docs-code/docs-code.mjs';
 import {docsCodeMultifileExtension} from './extensions/docs-code/docs-code-multifile.mjs';
 import {docsTabGroupExtension, docsTabExtension} from './extensions/docs-tabs.mjs';
+import {docsImageExtension} from './extensions/docs-image.mjs';
+
 import {hooks} from './hooks.mjs';
 
 let markedInstance: typeof marked;
 const extensions = [
+  docsImageExtension,
   docsAlertExtension,
   docsCalloutExtension,
   docsPillExtension,

adev/shared-docs/pipeline/shared/marked/test/image/image.md

@@ -1,2 +1,6 @@
 ![New Logo!](https://angular.dev/favicon.ico 'Our new icon')
 ![New Logo!](./some-image.png 'Local Image')
+![Lazy Image](https://angular.dev/assets/logo.svg {loading: 'lazy'})
+![Async Decoded Image](https://angular.dev/assets/logo.svg {decoding: 'async'} 'Async Image')
+![High Priority Image](https://angular.dev/assets/logo.svg {fetchpriority: 'high'})
+![Combined Attributes](https://angular.dev/assets/logo.svg {loading: 'eager', decoding: 'sync', fetchpriority: 'high'} 'Hero Image')

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

@@ -29,4 +29,28 @@ describe('markdown to html', () => {
     const image = markdownDocument.querySelector('img[title="Local Image"]');
     expect(image?.getAttribute('src')).toBe('unknown/some-image.png');
   });
+
+  it('should add loading attribute when specified', () => {
+    const image = markdownDocument.querySelectorAll('img')[2];
+    expect(image?.getAttribute('loading')).toBe('lazy');
+  });
+
+  it('should add decoding attribute when specified', () => {
+    const image = markdownDocument.querySelectorAll('img')[3];
+    expect(image?.getAttribute('decoding')).toBe('async');
+    expect(image?.getAttribute('title')).toBe('Async Image');
+  });
+
+  it('should add fetchpriority attribute when specified', () => {
+    const image = markdownDocument.querySelectorAll('img')[4];
+    expect(image?.getAttribute('fetchpriority')).toBe('high');
+  });
+
+  it('should handle multiple attributes with title', () => {
+    const image = markdownDocument.querySelectorAll('img')[5];
+    expect(image?.getAttribute('loading')).toBe('eager');
+    expect(image?.getAttribute('decoding')).toBe('sync');
+    expect(image?.getAttribute('fetchpriority')).toBe('high');
+    expect(image?.getAttribute('title')).toBe('Hero Image');
+  });
 });

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

@@ -8,15 +8,31 @@
 
 import {normalize} from 'path';
 
-import {Renderer, Tokens} from 'marked';
+import {Renderer} from 'marked';
+import type {DocsImage} from '../extensions/docs-image.mjs';
 
 // TODO(josephperrott): Determine how we can define/know the image content base path.
 const imageContentBasePath = 'unknown';
 
-export function imageRender(this: Renderer, {href, title, text}: Tokens.Image) {
+export function imageRender(this: Renderer, token: DocsImage) {
+  const {href, title, text, loading, decoding, fetchpriority} = token;
+
   const isRelativeSrc = href?.startsWith('./');
   const src = isRelativeSrc ? `${imageContentBasePath}/${normalize(href)}` : href;
+
+  const attrs = [
+    `src="${src}"`,
+    `alt="${text}"`,
+    `class="docs-image"`,
+    title ? `title="${title}"` : null,
+    loading ? `loading="${loading}"` : null,
+    decoding ? `decoding="${decoding}"` : null,
+    fetchpriority ? `fetchpriority="${fetchpriority}"` : null,
+  ]
+    .filter(Boolean)
+    .join(' ');
+
   return `
-  <img src="${src}" alt="${text}" title="${title}" class="docs-image">
+  <img ${attrs}>
   `;
 }

adev/src/content/events/v21.md

@@ -1,4 +1,4 @@
-![A retro 8-bit, pixel art style graphic announcing the upcoming release of Angular v21. The large, gradient 'v21' text dominates the frame. Next to it, in smaller text, are the words 'The Adventure Begins' and the release date '11-20-2025' inside a pink pixelated box. The Angular logo is in the bottom right corner.](assets/images/v21-event/angular-v21-hero.jpg 'Angular v21 Hero Image')
+![A retro 8-bit, pixel art style graphic announcing the upcoming release of Angular v21. The large, gradient 'v21' text dominates the frame. Next to it, in smaller text, are the words 'The Adventure Begins' and the release date '11-20-2025' inside a pink pixelated box. The Angular logo is in the bottom right corner.](assets/images/angular-v21-hero.jpg {loading: 'eager', fetchpriority: 'high'} 'Angular v21 Hero Image')
 
 # Angular v21: The Adventure Begins
 

adev/src/content/kitchen-sink.md

@@ -321,6 +321,11 @@ You can add images using the semantic Markdown image:
 ![Rhubarb the small cat](assets/images/kitchen-sink/rhubarb.jpg#small)
 ![Rhubarb the medium cat](assets/images/kitchen-sink/rhubarb.jpg#medium)
 
+## Add attributes using curly braces syntax
+
+![Lazy loaded image](assets/images/kitchen-sink/rhubarb.jpg {loading: 'lazy'})
+![Combined attributes](assets/images/kitchen-sink/rhubarb.jpg#small {loading: 'lazy', decoding: 'async', fetchpriority: 'low'})
+
 Embedded videos are created with `docs-video` and just need a `src` and `alt`:
 
 <docs-video src="https://www.youtube.com/embed/O47uUnJjbJc" alt=""/>