app/src/content/chapters/available-blocks.mdx

import { Image } from 'astro:assets';
import placeholder from '../../assets/images/placeholder.png';
import audioDemo from '../../assets/audio/audio-example.wav';
import HtmlFragment from '../../components/HtmlFragment.astro';
import Aside from '../../components/Aside.astro';
import Wide from '../../components/Wide.astro';
import FullBleed from '../../components/FullBleed.astro';
import Accordion from '../../components/Accordion.astro';

## Available blocks

All the following blocks are available in the article.mdx file. You can also create your own blocks by creating a new component in the components folder.

<br/>
<div className="button-group">
  <a className="button" href="#math">Math</a>
  <a className="button" href="#images">Images</a>
  <a className="button" href="#code-blocks">Code</a>
  <a className="button" href="#mermaid-diagrams">Mermaid</a>
  <a className="button" href="#citations-and-notes">Citations & notes</a>
  <a className="button" href="#placement">Placement</a>
  <a className="button" href="#accordion">Accordion</a>
  <a className="button" href="#minimal-table">Minimal table</a>
  <a className="button" href="#audio">Audio</a>
  <a className="button" href="#embeds">Embeds</a>
</div>

### Math

KaTeX is used for math rendering.

**Inline**

This is an inline math equation: $x^2 + y^2 = z^2$. 


<small className="muted">Example</small>
```mdx
$x^2 + y^2 = z^2$
```

**Block**

Affichage en bloc, voir l'exemple ci-dessous.

<small className="muted">Example</small>
```mdx
$$
\mathrm{Attention}(Q,K,V)=\mathrm{softmax}\!\left(\frac{QK^\top}{\sqrt{d_k}}\right) V
$$
```

### Images

**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**.

**Optional:** Zoomable (Medium-like lightbox): add `data-zoomable` to opt-in. Only images with this attribute will open full-screen on click.

**Optional:** Lazy loading: add `loading="lazy"` to opt-in.

**Optional:** Figcaption and credits: add a `figcaption` element with a `span` containing the credit.



<figure>
  <Image
    src={placeholder}
    data-zoomable
    alt="Tensor parallelism in a transformer block"
  />
  <figcaption>
    Tensor parallelism in a transformer block
    <span className="image-credit">Original work on <a target="_blank" href="https://huggingface.co/spaces/nanotron/ultrascale-playbook?section=tensor_parallelism_in_a_transformer_block">Ultrascale Playbook</a></span>
  </figcaption>
</figure>

<small className="muted">Example</small>
```mdx
import { Image } from 'astro:assets'
import myImage from '../assets/images/placeholder.jpg'

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

<figure>
  <Image src={myImage} data-zoomable alt="Example with caption and credit" loading="lazy" />
  <figcaption>
    Optimized image with a descriptive caption.
    <span className="image-credit">Credit: Photo by <a href="https://example.com">Author</a></span>
  </figcaption>
</figure>
```


### Code blocks

Use fenced code blocks with a language for syntax highlighting.

```python
def greet(name: str) -> None:
    print(f"Hello, {name}!")

greet("Astro")
```

<small className="muted">Example</small>
````mdx
```python
def greet(name: str) -> None:
    print(f"Hello, {name}!")

greet("Astro")
```
````

### Mermaid diagrams

Native mermaid diagrams are supported. You can use the <a target="_blank" href="https://mermaid.live/edit#pako:eNpVjUFPg0AQhf_KZk6a0AYsCywHE0u1lyZ66EnoYQMDSyy7ZFlSK_DfXWiMOqd58773ZoBcFQgxlGd1yQXXhhx3mSR2ntJE6LozDe9OZLV6HPdoSKMkXkeyvdsr0gnVtrWs7m_8doZIMhxmDIkRtfyYblay5F8ljmSXHnhrVHv66xwvaiTPaf0mbP1_R2i0qZe05HHJVznXJOF6QcCBStcFxEb36ECDuuGzhGF2MzACG8wgtmuBJe_PJoNMTjbWcvmuVPOT1KqvBNj6c2dV3xbc4K7mlea_CMoCdaJ6aSCm3lIB8QCfED94dM2o77ssjFzK3MiBq2WCNWUeiza-H26YvU8OfC0_3XVII9eLQuYFIaVBGEzfyTJ22g"> live editor</a> to create your diagram and copy the code to your article.

```mermaid
graph TD
  A[Start] --> B{Is it working?}
  B -- Yes --> C[Great!]
  B -- No --> D[Fix it]
  D --> B
```

<small className="muted">Example</small>
````mdx
```mermaid
graph TD
  A[Start] --> B{Is it working?}
  B -- Yes --> C[Great!]
  B -- No --> D[Fix it]
  D --> B
```
````

### Citations and notes

Here are a few variations using the same bibliography:

1) **In-text citation** with brackets: [@example2023].

2) **Narrative citation**: As shown by @vaswani2017attention, transformers enable efficient sequence modeling.

3) **Multiple citations** and a **footnote** together: see [@vaswani2017attention; @example2023] for related work. Also note this footnote[^f1].

[^f1]: Footnote attached to the sentence above.

<small className="muted">Example</small>
```mdx
1) In-text citation with brackets: [@example2023].

2) Narrative citation: As shown by @vaswani2017attention, transformers enable efficient sequence modeling.

3) Multiple citations and a footnote together: see [@vaswani2017attention; @example2023] for related work. Also note this footnote[^f1].

[^f1]: Footnote attached to the sentence above.
```


### Placement

#### Asides

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

<small className="muted">Example</small>
```mdx
import Aside from '../components/Aside.astro'

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

Use these helpers to expand content beyond the main column when needed. They will always be centered and displayed above every other content.

#### Wide example

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

<small className="muted">Example</small>
```mdx
import Wide from '../components/Wide.astro'

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

#### Full-bleed example

<FullBleed>
  <div className="demo-full-bleed">demo full-bleed</div>
</FullBleed>

<small className="muted">Example</small>
```mdx
import FullBleed from '../components/FullBleed.astro'

<FullBleed>
  Your content here...
</FullBleed>
```


### Accordion

Accessible accordion based on `details/summary`. 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="Closed by default">
  <p>This one stays collapsed until the user clicks the summary.</p>
</Accordion>

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

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

<small className="muted">Example</small>
````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="Another accordion">
  <ul>
    <li>Item A</li>
    <li>Item B</li>
  </ul>
</Accordion>

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

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

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

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


### Minimal table

| Method | Score |
|---|---|
| A | 0.78 |
| B | 0.86 |

<small className="muted">Example</small>
```mdx
| Method | Score |
| --- | --- |
| A | 0.78 |
| B | 0.86 |
```

### Audio

<audio controls src={audioDemo}/>
<br/>
<small className="muted">Example</small>
```mdx
import audioDemo from '../assets/audio/audio-example.wav'

<audio controls src={audioDemo}/>
```



### Embeds


#### Html Fragments

The main purpose of the ```HtmlFragment``` 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/fragments` folder.

Plotly and D3 are already supported by the template. 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.

Here are some examples of the two **libraries** in the template:

<small class="muted">D3 version</small>
  <div className="plot-card">
    <HtmlFragment src="d3-line.html" />
</div>
<caption className="caption">D3 Line chart — simple time series example.</caption>

  <div className="plot-card">
    <HtmlFragment src="d3-bar.html" />
</div>
<caption className="caption">D3 Bar chart — categorical distribution example.</caption>

--- 

<small class="muted">Plotly version</small>

<div className="plot-card">
  <HtmlFragment src="line.html" />
</div>
<caption className="caption">Plotly Line chart — interactive time series with hover and zoom.</caption>

<small className="muted">Example</small>
```mdx
import HtmlFragment from '../components/HtmlFragment.astro'

<HtmlFragment src="line.html" />
```

#### Iframes

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

<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 className="plot-card" 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>


<small className="muted">Example</small>
```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>
```

#### gradio

You can also embed **gradio** apps.

<gradio-app theme_mode="light" space="hebrew-llm-leaderboard/leaderboard"></gradio-app>



<small className="muted">Example</small>
```mdx
<gradio-app theme_mode="light" space="hebrew-llm-leaderboard/leaderboard"></gradio-app>
```