Frontmatter#

Every article begins with YAML frontmatter. It defines metadata used by article pages, lists, search results, and feeds:

1
---
2
title: My MDX Article
3
published: 2026-08-08
4
description: A short introduction shown in article previews.
5
tags: [Markdown, MDX]
6
category: Guides
7
draft: false
8
---

Keep frontmatter focused on metadata. Imports and JavaScript declarations belong immediately after the closing --- delimiter.

Standard Markdown#

Most of an MDX article should remain ordinary Markdown. This keeps the source easy to read and gives RSS and Atom readers a useful static version.

1
## A section heading
2

3
- A list item
4
- **Bold text** and *emphasis*
5
- [A normal link](https://example.com/)
6

7
> A blockquote remains a blockquote.

Importing and Using Components#

MDX can import Astro components at the top level and use them directly in the document. Component names must begin with a capital letter.

1
import Notice from "../../components/Notice.astro";
2

3
export const message = "Props can come from an MDX expression.";
4

5
<Notice label={message} />

The following panel is a live component rendered by this article:

Use components for reusable interface elements or structured content. Prefer Markdown for regular prose so the article remains portable and readable.

JavaScript Expressions#

Top-level export const declarations can prepare values for the document. Insert a JavaScript expression with braces:

1
export const topics = ["components", "expressions", "extended Markdown"];
2

3
This guide covers {topics.length} topics: {topics.join(", ")}.

This live expression counts 3 topics: components, expressions, extended Markdown.

Expressions should be deterministic during the build. Browser-only APIs such as window and document belong inside a component script rather than the MDX module body.

Callouts#

Callouts highlight information without requiring a custom component:

TIP

Use the simplest syntax that works

Choose Markdown for prose, an MDX expression for a small dynamic value, and a component when markup or behavior needs to be reused.

1
:::tip[Optional title]
2
This content is emphasized as a tip.
3
:::

Wiki Links#

An inline Wiki Link points to another article while keeping the sentence readable. For example, continue with the content guide.

A standalone Wiki Link becomes an article card with its available metadata and cover image:

Writing a Blog Post

A generic example of article structure and frontmatter.

2024-04-01Guides#Example#Writing#Markdown

1
Read [[guide|the content guide]] for more details.
2

3
[[guide]]

Math and Chemistry#

Inline math uses single dollar signs, while display equations use a pair. The mhchem extension is also available for chemical notation.

Einstein’s mass-energy relation is $E = mc^2$.

A chemical reaction can be written as $\ce{H2O + CO2 -> H2CO3}$.

1
Inline: $E = mc^2$
2

3
Display: $$\int_0^1 x^2\,dx = \frac{1}{3}$$
4

5
Chemistry: $\ce{H2O + CO2 -> H2CO3}$

Code Groups#

Use a code group when readers may choose between equivalent examples. Each label corresponds to one fenced code block:

1
export const renderTarget = "page";

1
pnpm build

1
::: code-group labels=[TypeScript, Shell]
2

3
```ts
4
export const renderTarget = "page";
5
```
6

7
```bash
8
pnpm build
9
```
10

11
:::

Images and Captions#

Image alt text describes the image for assistive technology. A Markdown title becomes a visible caption, and an optional w-N% token controls the width.

1
![Descriptive alt text w-60%](./image.webp "Visible image caption")

Valid widths range from w-1% to w-100%. Omit the token when the image should use the normal responsive width.

Internal and External Links#

Relative links and absolute URLs that use the configured site origin are classified as internal. Links to other origins receive the external-link attributes configured by the theme.

• Visit the About page using a relative site URL.
• Compare it with an external reference.

Use relative paths for internal content. External origins such as https://example.com/ are classified separately by the theme.

Writing Portable MDX#

The article page, RSS, and Atom share the same content pipeline. Interactive scripts are removed from feeds, but semantic HTML produced by components, callouts, Wiki Links, math, code groups, and images remains readable.

For reliable output:

1. Keep the main explanation in Markdown.
2. Give images meaningful alt text and components semantic HTML.
3. Avoid browser globals in top-level expressions.
4. Ensure useful information is visible before client-side JavaScript runs.
5. Run pnpm test, pnpm check, and pnpm build before publishing.

MDX works best as an extension of Markdown—not a replacement for it. Start with plain content, then introduce expressions and components only where they make the article clearer or more reusable.