Markdown and MDX Tutorial Guide

What You Are Learning

This guide explains two related writing formats:

• Markdown, often saved as .md, is a simple way to write formatted text using plain-text symbols.
• MDX, often saved as .mdx, is Markdown plus the ability to use components and JavaScript-style expressions.

For Astro and Starlight projects, Markdown is usually best for normal pages. MDX is best when a page needs reusable visual components, interactive examples, cards, callouts, diagrams, or custom layouts.

The Big Picture

Think of Markdown as a clean notebook format. You write headings, paragraphs, links, images, lists, and code examples without needing to write full HTML.

Markdown file
  ↓
Astro or Starlight processes it
  ↓
Website page is generated

MDX adds one extra power: it lets your writing use components.

MDX file
  ↓
Markdown text + imported components
  ↓
Astro or Starlight processes it
  ↓
Richer website page is generated

Markdown in Simple Terms

Markdown is a lightweight writing syntax. Instead of writing this:

<h2>Character Background</h2>
<p>Aurelian was raised far from the royal court.</p>

You can write this:

## Character Background

Aurelian was raised far from the royal court.

Markdown is easier to read, easier to write, and easier to maintain when you are creating lots of content pages.

Markdown Headings

Headings are created with # symbols.

# Page Title

## Major Section

### Smaller Section

#### Even Smaller Section

Use headings like an outline. A page should usually have one main title, then organized sections below it.

Paragraphs

Paragraphs are just plain text. Leave a blank line between paragraphs.

This is the first paragraph.

This is the second paragraph.

Do not indent normal paragraphs unless you intentionally want a code block.

Bold, Italic, and Inline Code

**bold text**

*italic text*

`inline code`

Rendered result:

• bold text
• italic text
• inline code

Lists

Use hyphens for unordered lists.

- Geography
- Government
- Economy
- Military
- Transnational Issues

Use numbers for ordered lists.

1. Create the project.
2. Add Starlight.
3. Write Markdown pages.
4. Build the site.
5. Deploy the site.

Links

Markdown links use this pattern:

[link text](destination)

Example:

[Astro Documentation](https://docs.astro.build)

For internal Starlight pages, you might write:

[Character Template](/worldbuilding/templates/character/)

Images

Markdown images look like links with an exclamation mark at the beginning.

![Map of the eastern seaboard](/images/eastern-seaboard-map.png)

The text inside the brackets is alt text. It describes the image for accessibility and for cases where the image does not load.

Code Blocks

Use triple backticks for code blocks. You can name the language after the opening backticks.

```js
const siteName = "World Bible";
console.log(siteName);
```

In an HTML tutorial file like this one, the backtick example is shown as text. In a real Markdown file, the code block would render with formatting.

Blockquotes

Use > for quoted or highlighted text.

> A world bible is not only a lore archive. It is a continuity tool.

This is useful for key ideas, definitions, warnings, or memorable principles.

Tables

Markdown tables are useful for compact reference information.

| Field | Example |
|---|---|
| Name | Veritas Miraculo |
| Role | Rival heir apparent |
| Region | Europe |
| Status | Active |

Tables are good for summaries, but long prose should usually stay in normal sections.

Frontmatter

Frontmatter is a YAML block at the top of a Markdown or MDX file. Astro and Starlight use it as page metadata.

---
title: "Character Sheet Template"
description: "A reusable RPG-style character profile format"
tags:
  - characters
  - worldbuilding
  - template
---

The frontmatter describes the page. The Markdown below it becomes the visible page content.

---
title: "Character Sheet Template"
---

# Character Sheet Template

## Identity

## Attributes

## Relationships

Markdown for a Lesson Page

A lesson page can use frontmatter for course information and Markdown for the lesson body.

---
title: "Introduction to Deployment"
description: "A beginner lesson on publishing web projects"
course: "Web Development"
level: "Beginner"
order: 1
---

# Introduction to Deployment

## What You Are Learning

Deployment means putting your project online.

## Why This Matters

A project is not very useful if no one can visit it.

## Practice Exercise

Deploy a basic HTML page.

Markdown for a World Bible Page

A world bible page can use frontmatter to identify the type of entry, then use Markdown sections for the content.

---
title: "New York Harbor, 2175"
type: "location"
region: "Atlantic Compact"
tags:
  - city
  - harbor
  - transportation
---

# New York Harbor, 2175

## Overview

## Historical Context

## Political Importance

## Technology Level

## Story Hooks

Markdown for an RPG-Style Character Sheet

For characters, use frontmatter for structured information and Markdown for detailed explanation.

---
title: "Example Character"
type: "character"
species: "Human"
role: "Investigator"
faction: "Independent"
attributes:
  strength: 10
  dexterity: 13
  constitution: 12
  intelligence: 16
  wisdom: 14
  charisma: 11
skills:
  - Investigation
  - Diplomacy
  - Technology
status: "Active"
---

# Example Character

## Identity

## Background

## Personality

## Goals

## Flaws

## Relationships

## Story Arc

What MDX Adds

MDX is like Markdown with a toolbox attached. In normal Markdown, you mostly write text. In MDX, you can also import and use components.

---
title: "Character Page with a Stat Card"
---

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

# Veritas Miraculo

<CharacterStats
  strength={10}
  dexterity={14}
  constitution={12}
  intelligence={16}
  wisdom={15}
  charisma={18}
/>

## Background

Veritas is publicly cultured and privately ruthless.

This lets you mix prose with reusable interface pieces.

When to Use Markdown vs MDX

Installing MDX in Astro

Astro supports Markdown by default. MDX is added as an integration.

npx astro add mdx

After that, you can create files ending in .mdx and use MDX features. Astro's official MDX integration supports frontmatter and lets MDX files import Astro components and UI framework components.

MDX Component Example

Imagine you have this Astro component:

// src/components/InfoBox.astro
---
const { title } = Astro.props;
---

<aside class="info-box">
  <h2>{title}</h2>
  <slot />
</aside>

You could use it in an MDX file like this:

---
title: "Using Info Boxes"
---

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

# Using Info Boxes

<InfoBox title="Remember">
Markdown is for writing. MDX is for writing plus components.
</InfoBox>

MDX Expressions

MDX can use JavaScript-style expressions inside curly braces.

export const characterName = "Aurelian Rassendyll";

# {characterName}

This page is about {characterName}.

This is useful, but do not overuse it. Too many expressions can make content harder to read.

Using Frontmatter Variables in MDX

In MDX, frontmatter values can be used inside the page.

---
title: "Aurelian Rassendyll"
role: "Protagonist / Double"
---

# {frontmatter.title}

Role: {frontmatter.role}

This is one of the major advantages of MDX over plain Markdown. Plain Markdown does not normally use frontmatter values directly inside the body without extra tooling.

Markdown, MDX, and Starlight

Starlight is designed for documentation-style sites. It uses Markdown and MDX pages well because lesson pages, guide pages, and reference pages are usually text-heavy.

A Starlight docs folder often looks like this:

src/
  content/
    docs/
      index.md
      getting-started.md
      worldbuilding/
        character-template.md
        region-template.md
      lessons/
        markdown-basics.md
        mdx-basics.mdx

Use Markdown for most pages. Use MDX when the page needs components.

Recommended File Naming

Use simple lowercase filenames. Avoid spaces.

good:
character_sheet_template.md
world_bible_overview.md
markdown_basics.md

also good for web routes:
character-sheet-template.md
world-bible-overview.md
markdown-basics.md

avoid:
Character Sheet Template Final FINAL.md

For web projects, consistency matters more than which naming style you choose.

Common Markdown Mistakes

Missing blank lines

Bad:
## Heading
- item one
- item two

Better:
## Heading

- item one
- item two

Using HTML when Markdown is enough

Too much:
<strong>Important</strong>

Simpler:
**Important**

Broken links

Check that this path exists:
[Map](/images/map.png)

Common MDX Mistakes

Forgetting to import a component

Bad:
<CharacterCard name="Veritas" />

Better:
import CharacterCard from "../../components/CharacterCard.astro";

<CharacterCard name="Veritas" />

Using JSX-style comments inside component-heavy areas

{/* This is a comment */}

Using components when normal Markdown would be better

MDX is powerful, but a simple content page should stay simple. Use MDX when the extra power helps.

Best Practice for World Bible Projects

Use Markdown for most reference pages:

characters/veritas_miraculo.md
regions/europe_2175.md
locations/new_york_harbor.md

Use MDX for pages that need special visual elements:

timelines/master_timeline.mdx
characters/character_dashboard.mdx
maps/eastern_seaboard_interactive.mdx

Best Practice for Lesson Sites

Use Markdown for normal lessons:

lessons/html_basics.md
lessons/vercel_deployment.md
lessons/yaml_frontmatter.md

Use MDX for lessons with embedded demos:

lessons/react_state_demo.mdx
lessons/interactive_quiz.mdx
lessons/svg_diagram_demo.mdx

Mini Project: Create a Markdown Lesson Page

Create this file:

src/content/docs/lessons/markdown_basics.md

Add this content:

---
title: "Markdown Basics"
description: "A beginner lesson on writing Markdown pages"
---

# Markdown Basics

## What Markdown Is

Markdown is a plain-text writing format.

## Why It Matters

It lets you write website content without writing full HTML.

## Practice

Create a heading, a list, a link, and a code block.

Mini Project: Create an MDX Character Page

Create this file:

src/content/docs/characters/example_character.mdx

Add this content:

---
title: "Example Character"
description: "A character page using MDX"
---

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

# {frontmatter.title}

<InfoBox title="Character Note">
This character page uses MDX because it includes a reusable component.
</InfoBox>

## Identity

## Attributes

## Story Role

Cheat Sheet

Simple Rule of Thumb

Use this decision rule:

If the page is mostly writing:
  use Markdown.

If the page needs components:
  use MDX.

If the page needs full custom layout and logic:
  use an Astro component.

Related Topics to Learn Next

• YAML frontmatter
• Astro content collections
• Starlight sidebar navigation
• MDX components
• Remark and rehype plugins
• Code block syntax highlighting
• Deploying Astro projects to Vercel or Netlify