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 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, audio; tracked via Git LFS)
- Embeds: `embed/` (HTMLEmbed for Plotly/D3, etc.) — see [HtmlEmbed](#htmlembed)

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

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


### Embeds

Use HTML fragments to embed interactive charts and widgets. Place your fragments under `app/src/content/embeds/` and reference them via the `HtmlEmbed` component.

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

<HtmlEmbed src="d3-line.html" title="D3 Line" desc="Simple time series" />
```


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

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