docs: add copy buttons to markdown code blocks (#33861)

* docs: add copy buttons to markdown code blocks

Add copy functionality to all code blocks in documentation markdown content.
Previously, only example viewer code and module import snippets had copy
buttons, but regular markdown code blocks (like configuration examples)
were missing this feature.

* docs: render code block copy buttons through markup

Emit the copy button as part of the code block markup in the markdown renderer
and handle clicks with a single delegated listener in the `DocViewer`, instead
of attaching a component to every code block through a portal. This removes
the `CodeBlockCopyButton` component.

Author: MeAkib

docs/src/app/shared/doc-viewer/doc-viewer.spec.ts

@@ -209,6 +209,23 @@ describe('DocViewer', () => {
     expect(clipboardSpy.copy).toHaveBeenCalled();
   });
 
+  it('should copy the code block content when its copy button is clicked', () => {
+    const fixture = TestBed.createComponent(DocViewerTestComponent);
+    fixture.componentInstance.documentUrl = `http://material.angular.io/doc-with-code-block.html`;
+    fixture.detectChanges();
+
+    const url = fixture.componentInstance.documentUrl;
+    http.expectOne(url).flush(FAKE_DOCS[url]);
+
+    const docViewer = fixture.debugElement.query(By.directive(DocViewer));
+    const copyIcon = docViewer.nativeElement.querySelector('.docs-markdown-copy-button span');
+    expect(copyIcon).toBeTruthy();
+
+    // Click the icon inside the button to verify that the click is delegated to the button.
+    copyIcon.click();
+    expect(clipboardSpy.copy).toHaveBeenCalledWith('const example = "test code";');
+  });
+
   // TODO(mmalerba): Add test that example-viewer is instantiated.
 });
 
@@ -261,6 +278,12 @@ const FAKE_DOCS: {[key: string]: string} = {
         data-docs-api-module-import-button="import {MatIconModule} from '@angular/material/icon';">
       </div>
     </div>`,
+  'http://material.angular.io/doc-with-code-block.html': `
+    <div class="docs-markdown">
+      <pre><code>const example = "test code";</code><button class="docs-markdown-copy-button">
+        <span>content_copy</span>
+      </button></pre>
+    </div>`,
 };
 
 @Component({

docs/src/app/shared/doc-viewer/doc-viewer.ts

@@ -13,7 +13,9 @@ import {
   Portal,
   CdkPortalOutlet,
 } from '@angular/cdk/portal';
+import {Clipboard} from '@angular/cdk/clipboard';
 import {HttpClient, HttpErrorResponse} from '@angular/common/http';
+import {MatSnackBar} from '@angular/material/snack-bar';
 import {DomSanitizer} from '@angular/platform-browser';
 import {
   ApplicationRef,
@@ -68,6 +70,9 @@ class DocFetcher {
   `,
   imports: [CdkPortalOutlet],
   changeDetection: ChangeDetectionStrategy.Eager,
+  host: {
+    '(click)': '_handleClick($event)',
+  },
 })
 export class DocViewer implements OnDestroy {
   private _appRef = inject(ApplicationRef);
@@ -77,6 +82,8 @@ export class DocViewer implements OnDestroy {
   private _ngZone = inject(NgZone);
   private _domSanitizer = inject(DomSanitizer);
   private _docFetcher = inject(DocFetcher);
+  private _clipboard = inject(Clipboard);
+  private _snackbar = inject(MatSnackBar);
 
   private _portalHosts: DomPortalOutlet[] = [];
   private _documentFetchSubscription: Subscription | undefined;
@@ -215,6 +222,19 @@ export class DocViewer implements OnDestroy {
     this._portalHosts = [];
   }
 
+  /** Copies the content of a code block when its copy button is clicked. */
+  protected _handleClick(event: MouseEvent) {
+    const button = (event.target as HTMLElement).closest('.docs-markdown-copy-button');
+    const code = button?.parentElement?.querySelector('code');
+
+    if (code) {
+      const message = this._clipboard.copy(code.textContent || '')
+        ? 'Copied code snippet'
+        : 'Failed to copy code snippet';
+      this._snackbar.open(message, undefined, {duration: 2500});
+    }
+  }
+
   ngOnDestroy() {
     this._clearLiveExamples();
     this._documentFetchSubscription?.unsubscribe();

docs/src/styles/_markdown.scss

@@ -77,12 +77,38 @@
 
       border: solid 1px var(--mat-sys-outline-variant);
       border-radius: 12px;
+      position: relative;
 
       code {
         background: transparent;
         padding: 0;
         font-size: 100%;
       }
+
+      .docs-markdown-copy-button {
+        position: absolute;
+        top: 5px;
+        right: 5px;
+        display: flex;
+        align-items: center;
+        justify-content: center;
+        width: 40px;
+        height: 40px;
+        padding: 0;
+        border: none;
+        border-radius: 50%;
+        background: transparent;
+        color: var(--mat-sys-on-surface-variant);
+        cursor: pointer;
+
+        &:hover {
+          background: color-mix(in srgb, var(--mat-sys-on-surface-variant) 8%, transparent);
+        }
+
+        &:focus-visible {
+          outline: solid 2px var(--mat-sys-primary);
+        }
+      }
     }
 
     code {

tools/markdown-to-html/docs-marked-renderer.mts

@@ -113,9 +113,21 @@ export class DocsMarkdownRenderer extends Renderer {
     });
   }
 
+  /**
+   * Transforms a markdown code block into the corresponding HTML output. Each code block gets a
+   * button that copies its content. The click is handled by the docs site's `DocViewer`.
+   */
   code(block: Tokens.Code): string {
     const langClass = block.lang ? ` class="language-${block.lang}"` : '';
-    return `<pre><code${langClass}>${highlightCodeBlock(block.text, block.lang)}</code></pre>`;
+    const copyButton =
+      '<button class="docs-markdown-copy-button" type="button" aria-label="Copy code"' +
+      ' title="Copy code to the clipboard">' +
+      '<span class="material-symbols-outlined" aria-hidden="true">content_copy</span>' +
+      '</button>';
+    return (
+      `<pre><code${langClass}>${highlightCodeBlock(block.text, block.lang)}</code>` +
+      `${copyButton}</pre>`
+    );
   }
 
   /**

tools/markdown-to-html/docs-marked-renderer.spec.mts

@@ -108,6 +108,14 @@ describe('DocsMarkdownRenderer', () => {
     );
   });
 
+  it('adds a copy button to code blocks', () => {
+    const output = transform('```ts\nconst a = 1;\n```');
+    expect(output).toContain('<pre><code class="language-ts">');
+    expect(output).toMatch(
+      /<\/code><button class="docs-markdown-copy-button" type="button" aria-label="Copy code"/,
+    );
+  });
+
   it('does not allow id links with no matching id element', () => {
     spyOn(console, 'error');
     spyOn(process, 'exit');