update

app/src/components/HtmlEmbed.astro

@@ -1,6 +1,6 @@
 ---
-interface Props { src: string; title?: string; desc?: string; frameless?: boolean; align?: 'left' | 'center' | 'right' }
-const { src, title, desc, frameless = false, align = 'left' } = Astro.props as Props;
+interface Props { src: string; title?: string; desc?: string; frameless?: boolean; align?: 'left' | 'center' | 'right'; id?: string }
+const { src, title, desc, frameless = false, align = 'left', id } = Astro.props as Props;
 
 // Load all .html embeds under src/content/embeds/** as strings (dev & build)
 const embeds = (import.meta as any).glob('../content/embeds/**/*.html', { query: '?raw', import: 'default', eager: true }) as Record<string, string>;
@@ -20,7 +20,7 @@ const html = resolveFragment(src);
 const mountId = `frag-${Math.random().toString(36).slice(2)}`;
 ---
 { html ? (
-  <figure class="html-embed">
+  <figure class="html-embed" id={id}>
     {title && <figcaption class="html-embed__title" style={`text-align:${align}`}>{title}</figcaption>}
     <div class={`html-embed__card${frameless ? ' is-frameless' : ''}`}>
       <div id={mountId} set:html={html} />

app/src/content/chapters/components.mdx

@@ -224,6 +224,7 @@ For researchers who want to stay in **Python** while targeting **D3**, the [d3bl
 | `desc`      | No       | Short description displayed below the card. Supports inline HTML (e.g., links).                  
 | `frameless` | No       | Removes the card background and border for seamless embeds.                                      
 | `align`     | No       | Aligns the title/description text. One of `left` (default), `center`, `right`.                  
+| `id`        | No       | Adds an `id` to the outer figure for deep-linking and cross-references.                        
 
 <Accordion title="Code example">
 ```mdx
@@ -231,6 +232,7 @@ import HtmlEmbed from '../components/HtmlEmbed.astro'
 
 <HtmlEmbed src="plotly-line.html" title="Plotly Line" desc="Some chart description" />
 <HtmlEmbed src="d3-line-example.html" title="D3 Line" desc="Some chart description" />
+<HtmlEmbed src="d3-line-example.html" id="real-world-examples" title="D3 Line (with id)" desc="Linkable example via #real-world-examples" />
 ```
 </Accordion>