How to Write Tutorial Posts in MDX

January 20, 2026

This site uses MDX: Markdown that can also embed components (JSX-like tags). In practice, that means you can write a normal tutorial with headings, lists, equations, images, and also drop in interactive Python code cells (via PyodideRunner) when needed. This website uses using Astro, Pyodide and Svelte in backhand.

This document is itself a working reference you can copy/paste from.

1. File structure and where things live

A typical post is a single *.mdx file under your content/posts folder (wherever your Astro content collection expects it).

Common asset locations (typical Astro conventions):

Images for posts: public/images/...
Refer to them as images/... (no leading slash) in frontmatter, and either images/... or /images/... in the body, depending on how your router is configured.
Data files: public/data/...
Fetch them from Pyodide using pyfetch("/data/yourfile.ext").

If your site uses a different folder layout, keep the same idea: assets must be served by the web server (i.e., under public/), not only exist locally.

2. Frontmatter

Every post begins with YAML frontmatter between --- lines.

Example (copy/paste):

---
layout: ../layouts/PostLayout.astro
title: "Your Title"
author: "Your Name"
description: "One sentence for previews and SEO."
date: "January 20, 2026" # Home page automatically sorts posts based on dates in a decreasing order.
tags: ["tag-a", "tag-b"] 
image: "images/cover.png"
featured: false # Posts can be pinned on top, irrespective of the dates.
---

2.1 What each field does

layout: which Astro layout renders the post. In this project, it is ../layouts/PostLayout.astro.
title: shown on the post page and in list previews.
author: shown in the post header (if the layout displays it).
description: used for previews and metadata; keep it concrete.
date: used for sorting and display. Use a stable human-readable date string (as in existing posts).
tags: list of strings. Do not leave trailing commas inside the list.
image: preview/cover image for the post (commonly used on the blog index page).
featured: whether to highlight the post in lists (depends on your index implementation).

Note: Comments in mdx are given by: {/* This is a comment. */}

3. Headings, text, lists, and links (Markdown)

3.1 Headings

Use # through ######:

# Top-level title (usually one per file)
## Section
### Subsection
#### Sub-subsection

Top-level title (usually one per file)

Section

Subsection

Sub-subsection

3.2 Emphasis and inline code

This is *italic*, this is **bold**, and this is `inline code`.

This is italic, this is bold, and this is inline code. Use --- for a horizontal line/ruler.

3.3 Lists

- Unordered item
- Another item

1. Ordered item
2. Another item

Unordered item
Another item

Ordered item
Another item

3.4 Links

A normal link: [Normal Link](https://www.praisecu.com/)
A local link: [Blog home](/blog/)

A normal link: Normal Link A local link: Blog home

4. Math (LaTeX): use only `$` and `$$`

This project compiles math from $...$ (inline) and $$...$$ (display).

Inline example: $\nabla f(x)$ , $x \in \mathbb{R}^d$ .

Display example:

\arg\min_\theta \; \sum_{i=1}^n \left(y_i - f_\theta(x_i)\right)^2.

4.1 Practical rules

Use $...$ for short expressions inside a sentence.
Use $$...$$ for multi-line or centered equations.
When writing backslashes inside code blocks, double-check escaping only when you are inside a JavaScript template string (see the PyodideRunner section).

5. Images in the body

Even if your post has a cover image in frontmatter, you can (and often should) include figures inline.

5.1 Simple image (Markdown)

![Alt text describing the image](images/example.png)
- OR -
<img src="/images/mdx-tutorial.png" alt="A placeholder figure" style="width:100%;" />

Example (replace the path with a real image you have in public/images/):

A placeholder figure; replace with your own asset

5.2 Figure with caption (HTML in MDX)

MDX supports inline HTML. A robust pattern is:

<figure>
  <img src="/images/example.png" alt="Describe the figure precisely" />
  <figcaption>Figure 1: A concise caption explaining what the reader should notice.</figcaption>
</figure>

Notes:

Prefer absolute paths like /images/... inside <img> tags; they tend to be less fragile with routing.
Always provide alt text.

6. Code blocks (static)

Use fenced code blocks with a language tag:

import numpy as np

x = np.linspace(0, 1, 5)
print(x)

npm run dev

console.log("Hello from MDX");

7. Interactive Python cells with `PyodideRunner`

This project includes a component:

import PyodideRunner from "../components/PyodideRunner.astro";

You can embed a runnable Python cell like this:

<PyodideRunner
  id="unique_cell_id"
  title="A short title shown above the cell"
  height={360}
  autoRun={false}
  initialCode={`print("Hello from Pyodide")`}
 />

7.1 `PyodideRunner` props (as used in your posts)

From the existing posts in this repo, these props are in use:

id (string, required): unique DOM id for the cell instance.
Use only letters/numbers/underscores; keep it unique within the page.
title (string, optional but recommended): shown as the cell label.
height (number, optional): visual height of the cell container (pixels).
autoRun (boolean): if true, executes immediately on page load.
initialCode (string): Python source code. In MDX, it is typically passed as a JavaScript template string: `...`.

If your local PyodideRunner.astro defines additional props (e.g., theme, packages, prelude), keep this list in sync with that file.

7.2 A complete example: compute + plot

This cell shows the minimal pattern that reliably renders plots in Pyodide:

Example: Matplotlib plot rendered in Pyodide

python

Idle.

Common pitfall: if you do not call plt.show(), many frontends will not display the figure.