app/src/content/chapters/writing-your-content.mdx

{/* IMPORTS */}
import { Image } from 'astro:assets';
import placeholder from '../assets/images/placeholder.png';
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 HtmlEmbed from '../../components/HtmlEmbed.astro';
import audioDemo from '../assets/audio/audio-example.wav';

## Writing Your Content

### **Introduction**

Your **article** lives in **one place**

Everything is **self-contained** under `app/src/content/`:
- **MDX**: `article.mdx` and [**optional chapters**](#chapters) in `chapters/`
- **Assets**: `assets/` images, audios, datas, etc. (tracked via **Git LFS**)
- **Embeds**: `embed/` [**HtmlEmbed**](#htmlembed) for Plotly/D3, etc.

The `article.mdx` file is the **main entry point** of your article.

<small className="muted">app/src/content/article.mdx</small>
```mdx
{/* HEADER */}
---
title: "This is the main title"
subtitle: "This will be displayed just below the banner"
description: "A modern, MDX-first research article template with math, citations, and interactive figures."
authors:
  - "Thibaud Frere"
  - "Alice Martin"
  - "Robert Brown"
affiliation: "Hugging Face"
published: "Feb 19, 2025"
tags:
  - research
  - template
{/* Optional override of the default Open Graph image */}
ogImage: "https://override-example.com/your-og-image.png"
{/* By default the table of contents is not collapsing */}
tocAutoCollapse: true
---

{/* IMPORTS */}
import { Image } from 'astro:assets';
import placeholder from './assets/images/placeholder.jpg';

{/* CONTENT */}
# Hello, world

This is a short paragraph written in Markdown. Below is an example image:

<Image src={placeholder} alt="Example image" />
```

### MDX 

**MDX** is a mix of **Markdown** and **HTML/JSX**: write regular Markdown, and embed **interactive components** inline when needed. We’ll describe the available components you can use later in this guide.

For Markdown syntax, see the complete [**Markdown documentation**](https://www.markdownguide.org/basic-syntax/).

<small className="muted">Example</small>
```mdx
{/* IMPORTS */}
import { Image } from 'astro:assets'
import placeholder from './assets/images/placeholder.png'
import Sidenote from '../components/Sidenote.astro'

# Mixing Markdown and components

This paragraph is written in Markdown. 

<Sidenote>A short callout inserted via a component.</Sidenote>

Below is an image imported via Astro and optimized at build time:

<Image src={placeholder} alt="Sample image with Astro optimization" />
```



### Chapters


**If** your article becomes **too long** for one file, you can **organize** it into **separate chapters**.

Simply **create a new file** in the `app/src/content/chapters` **directory**.  
Then, **include** your new chapter in the main `article.mdx` like below.


<small className="muted">Example</small>
```mdx
import MyChapter from './chapters/my-chapter.mdx';

<MyChapter />
```
<small className="muted">You can see a living example here <a target="_blank" href="https://huggingface.co/spaces/tfrere/research-article-template/blob/main/app/src/content/chapters/best-pratices.mdx">app/src/content/chapters/best-pratices.mdx</a>.</small>

### Table of contents
 
The **Table of contents** is generated **automatically** from your **H2–H4** headings. Keep headings **short** and **descriptive**; links work on **desktop** and **mobile**.

### Theme

All **interactive elements** (buttons, inputs, cards, etc.) are themed with the **primary color** you choose.

You can **update this main color** to match your brand by changing the `--primary-color` variable in the `app/src/styles/_variables.css` file.

Use the **color picker** below to see how the primary color affects the theme.

#### Brand color

<Sidenote>
  <HtmlEmbed frameless src="color-picker.html" />
  <Fragment slot="aside">
    You can use the color picker to select the right color.
    
    Here is an example of an <a href="#">interactive element</a>.
  </Fragment>
</Sidenote>


#### Color palettes

Here is a suggestion of **color palettes** for your **data visualizations** that align with your **brand identity**. These palettes are generated from your `--primary-color`.

<HtmlEmbed frameless src="palettes.html" />
<br/>
**Use color with care.**
Color should rarely be the only channel of meaning.
Always pair it with text, icons, shape or position. The simulation helps you spot palettes and states that become indistinguishable for people with color‑vision deficiencies.

#### Using the palettes

##### CSS
Use the generated **CSS variables** to style elements.

```css
/* Usage */
.series-a { color: var(--palette-categorical-1); }
.series-b { color: var(--palette-categorical-2); }
.heatmap-low  { background: var(--palette-sequential-1); }
.heatmap-high { background: var(--palette-sequential-6); }
.neg { color: var(--palette-diverging-1); }  /* left = primary */
.pos { color: var(--palette-diverging-6); }  /* right = complement */

/* Override size */
:root { --palette-count: 8; }                    /* global */
:root { --palette-diverging-count: 7; }          /* per palette */
```

<Note variant="info">⚠️ **CSS overrides** automatically trigger a **palette regeneration** via JS observers; no manual call is needed.</Note>

##### JS
Fetch arrays of colors via **`window.ColorPalettes.getColors(type)`**. To change sizes **at runtime**, set CSS vars and call **`window.ColorPalettes.refresh()`**.

```js
// Usage
const cat = window.ColorPalettes.getColors('categorical');
const seq = window.ColorPalettes.getColors('sequential');
const div = window.ColorPalettes.getColors('diverging');

// Override size (runtime)
document.documentElement.style.setProperty('--palette-count', '8');
document.documentElement.style.setProperty('--palette-diverging-count', '7');
window.ColorPalettes.refresh();
```

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

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

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


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

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

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

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