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
{/* Optional override of the default Open Graph image */}
ogImage: "https://override-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" />
<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.

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