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 HtmlEmbed from '../../components/HtmlEmbed.astro';
import Sidenote from '../../components/Sidenote.astro';
import Wide from '../../components/Wide.astro';
import FullWidth from '../../components/FullWidth.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**

$$
\mathrm{Attention}(Q,K,V)=\mathrm{softmax}\!\left(\frac{QK^\top}{\sqrt{d_k}}\right) V
$$

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

### Image

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

Props (optional)
- `data-zoomable`: adds a zoomable lightbox.
- `data-downloadable`: adds a small download button to fetch the image file.
- `loading="lazy"`: lazy loads the image.
- `figcaption`: adds a caption and credit.

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

**Optional:** Download button: add `data-downloadable` to render a small button in the bottom-right corner that downloads the image. By default it tries to use the original filename; you can override via `data-download-name="myfile.png"` and `data-download-src="/path/to/original.png"`.

**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
    data-downloadable
    layout="fixed"
    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} layout="fixed" data-zoomable data-downloadable 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

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 diagram

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
erDiagram
  DATASET ||--o{ SAMPLE : contains
  RUN }o--o{ SAMPLE : uses
  RUN ||--|| MODEL : trains
  RUN ||--o{ METRIC : logs

  DATASET {
    string id
    string name
  }

  SAMPLE {
    string id
    string uri
  }

  MODEL {
    string id
    string framework
  }

  RUN {
    string id
    date startedAt
  }

  METRIC {
    string name
    float value
  }
```

<small className="muted">Example</small>
````mdx
```mermaid
erDiagram
  DATASET ||--o{ SAMPLE : contains
  RUN }o--o{ SAMPLE : uses
  RUN ||--|| MODEL : trains
  RUN ||--o{ METRIC : logs

  DATASET {
    string id
    string name
  }

  SAMPLE {
    string id
    string uri
  }

  MODEL {
    string id
    string framework
  }

  RUN {
    string id
    date startedAt
  }

  METRIC {
    string name
    float value
  }
```
````

### Citation and footnote

**Citations** use the `@` syntax (e.g., `[@vaswani2017attention]` or `@vaswani2017attention` in narrative form) and are **automatically** collected to render the **bibliography** at the end of the article. The citation keys come from `app/src/content/bibliography.bib`.

**Footnotes** use an identifier like `[^f1]` and a definition anywhere in the document, e.g., `[^f1]: Your explanation`. They are **numbered** and **listed automatically** at the end of the article.

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

### Separator

Use `---` on its own line to insert a horizontal separator between sections. This is a standard Markdown “thematic break”. Don’t confuse it with the `---` used at the very top of the file to delimit the frontmatter.

---

<small className="muted">Example</small>
```mdx
Intro paragraph.

---

Next section begins here.
```


### 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="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="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}/>
```




### 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/fragments` 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.

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

Props (optional)
- `title`: short title displayed above the card.
- `desc`: short description displayed below the card. Supports inline HTML (e.g., links).
- `frameless`: removes the card background and border for seamless embeds.
- `align`: aligns the title/description text. One of `left` (default), `center`, `right`.

{/* <HtmlEmbed src="d3-scatter.html" frameless title="" desc="" /> */}
<HtmlEmbed src="d3-line.html" title="D3 Line" desc="Simple time series" />
---
<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" title="D3 Interactive neural network (MNIST-like)" desc="Draw a digit and visualize activations and class probabilities (0–9)." align="center" />
</Wide>
---
<FullWidth>
  <HtmlEmbed src="d3-pie.html" desc="D3 Pie charts by category" align="center" />
</FullWidth>
---
<HtmlEmbed src="line.html" title="Plotly Line" desc="Interactive time series" />

<br/><br/>
Here are some examples of the two **libraries** in the template

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

<HtmlEmbed src="d3-line.html" title="D3 Line" desc="Simple time series" />
<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" title="D3 Interactive neural network (MNIST-like)" desc="Draw a digit and visualize activations and class probabilities (0–9)." align="center" />
</Wide>

<FullWidth>
  <HtmlEmbed src="d3-pie.html" desc="D3 Pie charts by category" align="center" />
</FullWidth>

<HtmlEmbed src="line.html" title="Plotly Line" desc="Interactive time series" />
```

### 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>

<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>
<iframe src="https://gradio-hello-world.hf.space" width="100%" height="380" frameborder="0"></iframe>
```