app/src/pages/article.mdx

---
title: "The science template:\nCraft Beautiful Blogs"
description: "A modern, MDX-first research article template with math, citations, and interactive figures."
authors:
  - "John Doe"
  - "Alice Martin"
  - "Robert Brown"
affiliation: "Hugging Face"
published: "Feb 19, 2025"
tags:
  - research
  - template
ogImage: "https://example.com/your-og-image.png"
---

import HtmlFragment from "../components/HtmlFragment.astro";
import Wide from "../components/Wide.astro";
import FullBleed from "../components/FullBleed.astro";
import { Image } from 'astro:assets';
import placeholder from "../assets/images/placeholder.jpg";
import audioDemo from "../assets/audio/audio-example.wav";
import Aside from "../components/Aside.astro";
import visualPoster from "../assets/images/visual-vocabulary-poster.png";

<Aside>
  Welcome to this single-page research article template built with **Astro** and **MDX**.
  It’s designed to help you write clear, modern, and **interactive** technical articles with **minimal setup**.
  Whether you cover machine learning, data science, physics, or software topics, this template keeps the authoring flow simple while offering robust features out of the box.
  <Fragment slot="aside">
    Reading time: 10–15 minutes.
  </Fragment>
  In this guide, you’ll learn how to install the template,
  write content (math, citations, images, code, asides, interactive fragments),
  customize styles and behavior, and follow a few **best practices** for publishing.
  <Fragment slot="aside">
    If you have questions or remarks open a discussion on the <a href="https://huggingface.co/spaces/tfrere/science-blog-template/discussions?status=open&type=discussion">Community tab</a>!
  </Fragment>
</Aside>

Ce template est heavely inspired by distill.

## Features

<div className="tag-list">
  <span className="tag">Markdown based</span>
  <span className="tag">KaTeX math</span>
  <span className="tag">Citations & footnotes</span>
  <span className="tag">Automatic build</span>
  <span className="tag">Table of content</span>
  <span className="tag">Dark theme</span>
  <span className="tag">HTML fragments</span>
  <span className="tag">Plotly ready</span>
  <span className="tag">SEO Friendly</span>
  <span className="tag">Lightweight bundle(\<500ko)</span>
  <span className="tag">Aside notes</span>
  <span className="tag">Medium like zoomable images</span>
</div>

## Getting Started

### Installation

```bash
git lfs install
git lfs pull
cd app
npm install
```


### Development

```bash
npm run dev
```

### Build

```bash
npm run build
```

Serving the `dist/` directory on any static host is enough to deliver the site.

### Deploy

The easiest way to get online is to clone [this Hugging Face Space](https://huggingface.co/spaces/tfrere/science-blog-template) and push your changes; every push triggers an automatic build and deploy.

### Large files (Git LFS)

Track binaries (e.g., `.png`, `.wav`) with Git LFS to keep the repository lean. This project is preconfigured to store such files via LFS.


## Writing Your Content

### MDX

Author your content in MDX for a pleasant, productive writing flow that combines familiar Markdown with reusable components when needed.
Below are minimal examples of the core elements.


Don't forget to enable syntax highlighting for MDX to make your editing experience even smoother!

```bash
# For VS Code but alternatively, use the Extensions marketplace UI and search for "MDX" by unifiedjs.
code --install-extension unifiedjs.vscode-mdx
```



The initial skeleton of this article looks like this:

```mdx
{/* HEADER */}
---
title: "The science template:\nCraft Beautiful Blogs"
description: "A modern, MDX-first research article template with math, citations, and interactive figures."
authors:
  - "John Doe"
  - "Alice Martin"
  - "Robert Brown"
affiliation: "Hugging Face"
published: "Feb 19, 2025"
tags:
  - research
  - template
ogImage: "https://example.com/your-og-image.png"
---

{/* IMPORTS */}
import { Image } from 'astro:assets';
import Aside from "../components/Aside.astro";
import HtmlFragment from "../components/HtmlFragment.astro";
import placeholder from "../assets/images/placeholder.png";
import audioDemo from "../assets/audio/audio-example.wav";

{/* CONTENT */}
<Aside>
  Welcome to this single-page research article template built with Astro and MDX.
  It’s designed to help you write clear, modern, and interactive technical articles with minimal setup.
  Whether you cover machine learning, data science, physics, or software topics, this template keeps the authoring flow simple while offering robust features out of the box.
  <Fragment slot="aside">
    Reading time: 10–15 minutes.
  </Fragment>
  In this guide, you’ll learn how to install the template,
  write content (math, citations, images, code, asides, interactive fragments),
  customize styles and behavior, and follow a few best practices for publishing.
  <Fragment slot="aside">
    If you have questions or remarks open a discussion on the <a href="https://huggingface.co/spaces/lvwerra/distill-blog-template/discussions?status=open&type=discussion">Community tab</a>!
  </Fragment>
</Aside>


```

It is composed of three parts:

- **Header**: which contains the title and the article's metadata.
- **Imports**: the imports of the different modules / images used in the article
- **Content**: the content of the article

**Available blocs**:

<div className="tag-list">
  <a className="tag" href="#math">Math</a>
  <a className="tag" href="#images">Images</a>
  <a className="tag" href="#code-blocks">Code</a>
  <a className="tag" href="#citations-and-notes">Citations & notes</a>
  <a className="tag" href="#asides">Asides</a>
  <a className="tag" href="#minimal-table">Array</a>
  <a className="tag" href="#audio">Audio</a>
  <a className="tag" href="#interactive-fragments">Interactive fragments</a>
  <a className="tag" href="#tracking-training-metrics-with-trackio">TrackIO</a>
</div>

### Math

Inline example: $x^2 + y^2 = z^2$.

Block example:

$$
x^2 + y^2 = z^2
$$

```mdx
Inline example: $x^2 + y^2 = z^2$

Block example:
$$
\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:** Figcaption and credits

<figure>
  <Image
    src={placeholder}
    data-zoomable
    alt="Example with caption and credit"
  />
  <figcaption>
    Optimized image with a descriptive caption.
    <span className="image-credit">Crédit: Photo by <a href="https://example.com">Author</a></span>
  </figcaption>
</figure>

```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">Crédit: 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 block example:

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

greet("Astro")
```

How to write it in MDX:

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

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

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

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


### Asides

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

```mdx
import Aside from '../components/Aside.astro'

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

### Width helpers

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>

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

```mdx
import FullBleed from '../components/FullBleed.astro'

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


### Minimal table

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

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

### Audio

<audio controls src={audioDemo}>
  Your browser does not support the audio element.
</audio>

```mdx
import audioDemo from '../assets/audio/audio-example.wav'

<audio controls src={audioDemo}>
  Your browser does not support the audio element.
</audio>
```



### Embeds


#### HtmlFragments

The main purpose of the ```HtmlFragment``` component is to embed a plotly or d3 chart in your article. Libraries are already imported in the template.

<div className="plot-card">
  <HtmlFragment src="line.html" />
</div>

```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—a lightweight dashboard to monitor machine learning experiments—can be used this way. The example below opens a demo project and displays a couple of metrics. You can customize the query parameters (`project`, `metrics`, `sidebar`, etc.) to fit your needs.

<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="600" frameborder="0"></iframe>

To embed TrackIO in your own page, copy the following HTML and adjust the `src` parameters:

#### GitHub code embeds

Finally, if you want to include code from GitHub you can use emgithub.com and, for example, create a collapsible widget like this:


  <div class="code-embed-container"></div>
  <script 
    src="https://emgithub.com/embed-v2.js?target=https%3A%2F%2Fgithub.com%2Fhuggingface%2Fpicotron%2Fblob%2F0035cce0e04afd6192763b11efe50010d8ad0f71%2Fpicotron%2Fdata_parallel%2Fdata_parallel.py%23L10-L60&style=github&type=code&showBorder=off&showLineNumbers=on&showFileMeta=on&showCopy=on&showFullPath=on">
  </script>

```html
  <div class="code-embed-container"></div>
  <script 
    src="https://emgithub.com/embed-v2.js?target=https%3A%2F%2Fgithub.com%2Fhuggingface%2Fpicotron%2Fblob%2F0035cce0e04afd6192763b11efe50010d8ad0f71%2Fpicotron%2Fdata_parallel%2Fdata_parallel.py%23L10-L60&style=github&type=code&showBorder=off&showLineNumbers=on&showFileMeta=on&showCopy=on&showFullPath=on">
  </script>
```


## Best Practices

- Keep sections short and focused.
- Prefer vector or optimized images; use `astro:assets` for responsive delivery.
- Annotate figures and code minimally but clearly.
- Use math sparingly; explain notation on first use.

### Choosing the right chart

Picking the right visualization depends on your goal (compare values, show distribution, part-to-whole, trends, relationships, etc.). The Visual Vocabulary poster below provides a concise mapping from analytical task to chart types.

<figure>
  <Image src={visualPoster} alt="Visual Vocabulary: choosing the right chart by task" data-zoomable />
  <figcaption>
    Visual Vocabulary: a handy reference to select chart types by purpose (comparison, distribution, part-to-whole, correlation, and more).
  </figcaption>
  </figure>


## Conclusions

This template provides a practical baseline for writing and sharing technical articles with math, citations, and interactive figures. Start simple, iterate on structure and style, and keep content maintainable for future readers and collaborators.