Using Markdown in Astro.js Projects

One of the things I absolutely love about Astro.js is how seamlessly it handles Markdown content. Whether you’re building a blog, documentation site, or content-heavy platform, Astro’s Markdown integration makes content management a breeze. Let me walk you through everything you need to know about using Markdown in your Astro projects.

Getting Started with Markdown in Astro

Right out of the box, Astro supports Markdown files with the .md extension. You don’t need any additional configuration to start using them. Just create a new file in your src/pages directory with a .md extension, and Astro automatically transforms it into a static HTML page.

Enhanced Markdown with MDX

Want to take your Markdown to the next level? Astro also supports MDX, which lets you include JavaScript expressions and React components directly in your Markdown files. To use MDX, you’ll need to install the MDX integration:

npm install @astrojs/mdx

After installation, update your astro.config.mjs:

import { defineConfig } from 'astro/config';
import mdx from '@astrojs/mdx';

export default defineConfig({
  integrations: [mdx()],
});

Markdown Features You’ll Love

Astro’s Markdown support includes all the features you’d expect, plus some excellent extras:

Frontmatter Support

Every Markdown file can include frontmatter - metadata about your content wrapped in triple-dashes. This is perfect for adding titles, descriptions, dates, or any custom data your content needs.

Automatic Slug Generation

Astro automatically creates URL-friendly slugs from your Markdown filenames. A file named hello-world.md becomes available at /hello-world in your built site.

Code Syntax Highlighting

Code blocks in your Markdown files get automatic syntax highlighting. Astro uses Shiki by default, which provides beautiful, accurate highlighting for hundreds of programming languages.

Best Practices

Here are some tips I’ve learned while working with Markdown in Astro:

1. Organize your content in a dedicated directory (like src/content) to keep things tidy
2. Use consistent frontmatter schemas across similar content types
3. Take advantage of Astro’s content collections for better type safety and organization
4. Keep your images in an organized structure relative to your content

What’s Next?

Once you’ve mastered the basics, you can explore more advanced features like custom components in MDX, dynamic content generation, and integrating with headless CMS platforms. The possibilities are endless!