Welcome to the Workshop

This blog is built with Astro 5 and MDX. Every post is a .mdx file in src/content/blog/, which means you can mix Markdown prose with interactive widget components. This post walks through the entire workflow and shows each widget in action.

How It Works

The authoring process is three steps:

Write — Create an .mdx file in src/content/blog/ with the required frontmatter fields.
Enhance — Import widget components to add charts, callouts, tables, and more.
Publish — Set status: published in your frontmatter and deploy.

MDX in a nutshell

MDX lets you use JSX components inside Markdown. You get the simplicity of Markdown for prose and the power of components for everything else. Import a component at the top of the file, then use it inline like HTML.

Frontmatter Reference

Every post needs a frontmatter block at the top of the file. Here are the available fields:

Frontmatter Fields

All available frontmatter fields for blog posts.
Field	Type	Required	Description
title	string	Yes	The post title displayed in listings and the page heading
excerpt	string	Yes	A short summary used in post cards and SEO metadata
date	YYYY-MM-DD	Yes	Publication date, used for sorting
status	draft \| published \| archived	Yes	Controls visibility of the post
tags	string[]	Yes	Array of topic tags for categorization
coverAlt	string	No	Alt text for the cover image
readTime	string	No	Estimated reading time, e.g. 4 min
featured	boolean	No	Set to true to highlight the post

Creating a New Post

Drop a new .mdx file into the content directory and add the required frontmatter. Here is the minimum viable post:

src/content/blog/my-new-post.mdx mdx

---
title: "My New Post"
excerpt: "A brief description of what this post covers."
date: 2026-03-25
status: draft
tags: ["topic"]
---

Write your content here using standard Markdown syntax.

## Subheadings work as expected

So do **bold**, *italic*, [links](https://example.com), and all the rest.

Using Widgets

To use a widget, import it at the top of your MDX file (after the frontmatter closing ---) and then place it anywhere in your content.

Importing a widget mdx

import Callout from '@/components/widgets/Callout.astro'

<Callout type="info" title="Heads up">
This is the callout content. Markdown works in here too.
</Callout>

Activity at a Glance

Here is a sample chart showing hypothetical posting activity. Replace the data with your own numbers as the blog grows.

Posts per Month

Total Posts

Publishing Workflow

When you are ready to make a post visible, change the status field from draft to published. Posts with status: draft will not appear on the live site but are still accessible during local development, which makes them useful for previewing work in progress.

Set status: archived to hide older posts from listings without deleting them.

What about images?

Place images in the public/ directory (or an asset pipeline of your choice) and reference them with the Figure component or standard Markdown image syntax. The Figure component adds captions and supports a wide layout option.

Next Steps

Browse the Widget Reference Guide for detailed examples of every component.
Duplicate my-first-post.mdx as a starting template for your own writing.
Experiment locally with npm run dev and check the result in your browser.

Happy writing.