app/src/content/chapters/components.mdx

import { Image } from 'astro:assets';
import placeholder from '../assets/image/placeholder.png';
import audioDemo from '../assets/audio/audio-example.wav';
import HtmlEmbed from '../../components/HtmlEmbed.astro';
import Sidenote from '../../components/Sidenote.astro';
import Wide from '../../components/Wide.astro';
import Note from '../../components/Note.astro';
import FullWidth from '../../components/FullWidth.astro';
import Accordion from '../../components/Accordion.astro';
import ResponsiveImage from '../../components/ResponsiveImage.astro';

## Components

**All** the following **components** are available in the **article.mdx** file. You can also create your own **components** by creating a new file in the `/components` folder.
You have to import them in the **.mdx** file you want to use them in.

<br/>
<div className="button-group">
  <a className="button" href="#responsiveimage">ResponsiveImage</a>
  <a className="button" href="#placement">Placement</a>
  <a className="button" href="#accordion">Accordion</a>
  <a className="button" href="#note">Note</a>
  <a className="button" href="#htmlembed">HtmlEmbed</a>
  <a className="button" href="#iframe">Iframe</a>
</div>

### ResponsiveImage

**Responsive images** automatically generate an optimized `srcset` and `sizes` so the browser downloads the most appropriate file for the current viewport and DPR. You can also request multiple output formats (e.g., **AVIF**, **WebP**, fallback **PNG/JPEG**) and control **lazy loading/decoding** for better **performance**.

| Prop                   | Required | Description                                                                                                         
|------------------------|----------|-------------------------------------------------------
| `zoomable`        | No       | Adds a zoomable lightbox (Medium-like).                                                                             
| `downloadable`    | No       | Adds a download button to fetch the image file.                                                               
| `loading="lazy"`       | No       | Lazy loads the image.                                                                                               
| `caption`              | No       | Adds a caption and credit.                                                                                          
| `id`              | No       | Adds an `id` to the outer figure for deep-linking and cross-references.                                                                                          


<ResponsiveImage
  src={placeholder}
  zoomable
  downloadable
  id="placeholder-image"
  layout="fixed"
  alt="A placeholder image alt text"
  caption={'A placeholder image description <span class="image-credit">From the <a target="_blank" href="https://commons.wikimedia.org/wiki/File:RCA_Indian_Head_Test_Pattern.svg">RCA Indian Head Test Pattern</a></span>'}
/>

<Accordion title="Code example">
```mdx
import ResponsiveImage from '../components/ResponsiveImage.astro'
import myImage from './assets/image/placeholder.jpg'

<ResponsiveImage src={myImage} alt="Responsive, optimized example image" />

<ResponsiveImage
  src={myImage}
  layout="fixed"
  zoomable
  downloadable
  loading="lazy"
  alt="Example with caption and credit"
  caption={'Optimized image with a descriptive caption. <span class="image-credit">Credit: Photo by <a href="https://example.com">Author</a></span>'}
/>
```
</Accordion>


### Placement

Use these helpers when you need to step outside the main content flow: **Sidenotes** for contextual side notes, **Wide** to extend beyond the main column, and **Full-width** for full-width, immersive sections.

#### Sidenotes

<Sidenote>
  This paragraph presents a **key idea** concisely.
  <Fragment slot="aside">
    **Side note** for brief context or a definition.
  </Fragment>
  </Sidenote>

<Accordion title="Code example">
```mdx
import Sidenote from '../components/Sidenote.astro'

<Sidenote>
  Main paragraph with the core idea.
  <Fragment slot="aside">Short side note.</Fragment>
</Sidenote>
```
</Accordion>


#### Wide example

<Wide>
  <div className="demo-wide">demo wide</div>
</Wide>

<Accordion title="Code example">
```mdx
import Wide from '../components/Wide.astro'

<Wide>
  Your content here...
</Wide>
```
</Accordion>

#### Full-width example

<FullWidth>
  <div className="demo-full-width">demo full-width</div>
</FullWidth>

<Accordion title="Code example">
```mdx
import FullWidth from '../components/FullWidth.astro'

<FullWidth>
  Your content here...
</FullWidth>
```
</Accordion>


### Accordion

Can be used like this `<Accordion>some content</Accordion>`. You can pass any children content.

<Accordion title="What can this accordion hold?" open>
  <p>Text, lists, images, code blocks, etc.</p>
  <ul>
    <li>Item one</li>
    <li>Item two</li>
  </ul>
</Accordion>

<Accordion title="A table inside an accordion">
  | Prop        | Required | Description                                                                                      
|-------------|----------|----------------------------------------------------------------------------------
| `src`       | Yes      | Path to the embed file in the `embeds` folder.                                                   
| `title`     | No       | Short title displayed above the card.                                                            
| `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>

<Accordion title="Code example">
````mdx
import Accordion from '../components/Accordion.astro'

<Accordion title="Accordion title" open>
  <p>Free content with <strong>markdown</strong> and MDX components.</p>
</Accordion>

<Accordion title="A table inside an accordion">
  | Prop        | Required | Description                                                                                      
|-------------|----------|----------------------------------------------------------------------------------
| `src`       | Yes      | Path to the embed file in the `embeds` folder.                                                   
| `title`     | No       | Short title displayed above the card.                                                            
| `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>

<Accordion title="Code example">
```ts
function greet(name: string) {
  console.log(`Hello, ${name}`);
}

greet("Astro");
```
</Accordion>
````
</Accordion>

### Note

Small contextual callout for tips, caveats, or emphasis.

<Note title="Heads‑up" emoji="💡" variant="info">
  Use notes to surface context without breaking reading flow.
</Note>

<Note variant="success">
  Operation completed successfully.
</Note>

<Note variant="danger">
  Be careful: this action cannot be undone.
</Note>

<Note>
  Plain note without header. Useful for short clarifications.
</Note>

| Prop     | Required | Type                         | Description                         |
|----------|----------|------------------------------|-------------------------------------|
| `title`  | No       | string                       | Short title displayed in header     |
| `emoji`  | No       | string                       | Emoji displayed before the title    |
| `class`  | No       | string                       | Extra classes for custom styling    |
| `variant`| No       | 'info' | 'success' | 'danger' | Visual intent of the note          |

<Accordion title="Code example">
```mdx
import Note from '../../components/Note.astro'

<Note title="Heads‑up" emoji="💡" variant="info">
  Use notes to surface context without breaking reading flow.
</Note>

<Note variant="success">
  Operation completed successfully.
</Note>

<Note variant="danger">
  Be careful: this action cannot be undone.
</Note>

<Note>
  Plain note without header. Useful for short clarifications.
</Note>
```
</Accordion>


### HtmlEmbed

The main purpose of the ```HtmlEmbed``` component is to **embed** a **Plotly** or **D3.js** chart in your article. **Libraries** are already imported in the template.

They exist in the `app/src/content/embeds` folder.

For researchers who want to stay in **Python** while targeting **D3**, the [d3blocks](https://github.com/d3blocks/d3blocks) library lets you create interactive D3 charts with only a few lines of code. In **2025**, **D3** often provides more flexibility and a more web‑native rendering than **Plotly** for custom visualizations.


<HtmlEmbed src="d3-line-example.html" title="This is a chart title" desc="Some chart description" />

| Prop        | Required | Description                                                                                      
|-------------|----------|----------------------------------------------------------------------------------
| `src`       | Yes      | Path to the embed file in the `embeds` folder.                                                   
| `title`     | No       | Short title displayed above the card.                                                            
| `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.                        

<Note emoji="💡" variant="info">
You can refer to a chart by giving it a name and pointing to it with a link.
-> `<a href="#neural-network-mnist-like">like his</a>`
-> `<HtmlEmbed id="neural-network-mnist-like"/>`
Live example: <a href="#neural-network-mnist-like">Fig 1</a>
</Note>

<Accordion title="Code example">
```mdx
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>

#### Data

If you need to link your **HTML embeds** to **data files**, there is an **`assets/data`** folder for this.
As long as your files are there, they will be served from the **`public/data`** folder.
You can fetch them with this address: **`[domain]/data/your-data.ext`**

<Note emoji="⚠️" variant="danger"><b>Be careful</b>, unlike images, <b>data files are not optimized</b> by Astro. You need to optimize them manually.</Note>

#### Vibe coding charts

If you are from the research field, it can be difficult to use **D3.js** charts instead of **Plotly**.
Happily, **LLM's** are here to help you! In the `app/src/content/embeds` folder, there is a `vibe-code-d3-embeds-directives.md` file that you can use to vibe code **D3.js** charts.

Inside this file, you will find every directives you need to code your own **HtmlEmbed** proof **D3.js** chart.

#### Real world examples

Here are some examples that were vibe coded to inspire you. 


---
<HtmlEmbed src="d3-line.html" title="Training curves by metric" desc="Interactive time series across runs. Choose a metric; hover for values." />
---
<HtmlEmbed src="d3-bar.html" title="D3 Memory usage with recomputation" desc={`Memory usage with recomputation — <a href="https://huggingface.co/spaces/nanotron/ultrascale-playbook?section=activation_recomputation" target="_blank">from the ultrascale playbook</a>`}/>
---
<Wide>
  <HtmlEmbed src="d3-neural.html" id="neural-network-mnist-like" title="D3 Interactive neural network (MNIST-like)" desc="Visualize activations and class probabilities (0–9)." align="center" />
</Wide>
---
<Wide>
  <HtmlEmbed src="d3-pie.html" desc="D3 Pie charts by category" align="center" />
</Wide>
---
<Wide>
  <HtmlEmbed src="filters-quad.html" desc="D3 Stacked Line charts" align="center" />
</Wide>
---
<HtmlEmbed src="d3-comparison.html" title="Image similarity: query vs top-k" desc="Compare a query image to top-k matches. Shows rank and similarity." />
---

### Iframes

You can embed external content in your article using **iframes**. For example, **TrackIO**, **Gradio** or even **Github code embeds** can be used this way.

<small className="muted">Github code embed</small>
<iframe frameborder="0" scrolling="no" style="width:100%; height:292px;" allow="clipboard-write" src="https://emgithub.com/iframe.html?target=https%3A%2F%2Fgithub.com%2Fhuggingface%2Fpicotron%2Fblob%2F1004ae37b87887cde597c9060fb067faa060bafe%2Fsetup.py&style=default&type=code&showBorder=on&showLineNumbers=on"></iframe>

<small className="muted">TrackIO embed</small>
<div className="">
<iframe src="https://trackio-documentation.hf.space/?project=fake-training-750735&metrics=train_loss,train_accuracy&sidebar=hidden&lang=en" width="100%" height="660" frameborder="0"></iframe>
</div>

<small className="muted">Gradio embed</small>
<div className="">
<iframe src="https://gradio-hello-world.hf.space" width="100%" height="380" frameborder="0"></iframe>
</div>

<Accordion title="Code example">
```mdx
<iframe frameborder="0" scrolling="no" style="width:100%; height:292px;" allow="clipboard-write" src="https://emgithub.com/iframe.html?target=https%3A%2F%2Fgithub.com%2Fhuggingface%2Fpicotron%2Fblob%2F1004ae37b87887cde597c9060fb067faa060bafe%2Fsetup.py&style=default&type=code&showBorder=on&showLineNumbers=on"></iframe>
<iframe src="https://trackio-documentation.hf.space/?project=fake-training-750735&metrics=train_loss,train_accuracy&sidebar=hidden&lang=en" width="100%" height="600" frameborder="0"></iframe>
<iframe src="https://gradio-hello-world.hf.space" width="100%" height="380" frameborder="0"></iframe>
```
</Accordion>