> ## Documentation Index
> Fetch the complete documentation index at: https://mintlify.com/withastro/astro/llms.txt
> Use this file to discover all available pages before exploring further.
# Markdown Support
> Learn how Astro supports Markdown and MDX for creating content-rich pages with components
Astro has built-in support for Markdown and MDX files, making it easy to write content-focused pages. You can use standard Markdown syntax, add frontmatter for metadata, and even use components within your content.
## Markdown Pages
Create Markdown pages by adding `.md` files to your `src/pages/` directory. Each file becomes a route based on its file path.
````markdown src/pages/blog/post.md theme={null}
---
title: My Blog Post
author: Jane Doe
date: 2026-03-03
---
# Welcome to My Post
This is a **Markdown** page in Astro. It supports all standard Markdown syntax.
## Features
- Easy to write
- Familiar syntax
- Fast rendering
```js
console.log('Code blocks work too!');
````
````
Markdown files in `src/pages/` are automatically converted to HTML pages with Astro's default layout.
## Frontmatter
Frontmatter is YAML metadata at the top of your Markdown file, enclosed by `---` delimiters. It's available as the `frontmatter` property in your layouts.
```markdown src/pages/post.md
---
title: Understanding Frontmatter
description: A guide to using frontmatter in Astro
author: John Smith
publishedDate: 2026-03-03
tags: [astro, markdown, frontmatter]
layout: ../../layouts/BlogPost.astro
---
# Content goes here
````
### Accessing Frontmatter
In your layout, access frontmatter data through the `frontmatter` prop:
```astro src/layouts/BlogPost.astro theme={null}
---
const { frontmatter } = Astro.props;
---
{frontmatter.title}
{frontmatter.title}
By {frontmatter.author} on {frontmatter.publishedDate}
```
## MDX Support
MDX extends Markdown by allowing you to import and use components directly in your content. First, add the MDX integration:
```bash theme={null}
npx astro add mdx
```
### Using Components in MDX
Once installed, you can use components in `.mdx` files:
```mdx src/pages/interactive.mdx theme={null}
---
title: Interactive Content
---
import Button from '../components/Button.astro';
import Counter from '../components/Counter.jsx';
# Interactive MDX Page
Here's a regular paragraph of text.
And here's a React counter component:
## More Content
You can mix Markdown and components seamlessly.
```
MDX is perfect for documentation, blogs, and any content that benefits from interactive components.
## Markdown Features
### Syntax Highlighting
Code blocks support syntax highlighting out of the box:
````markdown theme={null}
```js
function greet(name) {
return `Hello, ${name}!`;
}
```
````
You can customize the theme in your `astro.config.mjs`:
```js astro.config.mjs theme={null}
import { defineConfig } from 'astro/config';
export default defineConfig({
markdown: {
shikiConfig: {
theme: 'dracula',
wrap: true
}
}
});
```
### GitHub-Flavored Markdown
Astro supports GitHub-Flavored Markdown (GFM) including:
* **Tables**
* **Task lists**
* **Strikethrough**
* **Autolinks**
```markdown theme={null}
| Feature | Supported |
|---------|----------|
| Tables | ✓ |
| GFM | ✓ |
- [x] Task lists work
- [ ] Unchecked items too
~~Strikethrough text~~
https://example.com (autolinked)
```
### Custom Components
Replace HTML elements with custom components using the `components` prop in MDX:
```mdx src/pages/styled.mdx theme={null}
---
title: Custom Styled Content
---
import CustomHeading from '../components/CustomHeading.astro';
import Note from '../components/Note.astro';
export const components = {
h1: CustomHeading,
blockquote: Note
};
# This renders as CustomHeading
> This renders as the Note component
```
## Layouts for Markdown
Specify a layout in frontmatter to wrap your Markdown content:
```markdown src/pages/article.md theme={null}
---
layout: ../layouts/Article.astro
title: My Article
---
Content here...
```
The layout receives all frontmatter properties plus the rendered content:
```astro src/layouts/Article.astro theme={null}
---
const { frontmatter } = Astro.props;
---
{frontmatter.title}
```
## Programmatic Access
Import Markdown files in Astro components to access their content and frontmatter:
```astro src/pages/index.astro theme={null}
---
import * as post from './blog/my-post.md';
const { Content, frontmatter } = post;
---
```
## Configuration Options
Customize Markdown processing in `astro.config.mjs`:
```js astro.config.mjs theme={null}
import { defineConfig } from 'astro/config';
export default defineConfig({
markdown: {
// Syntax highlighting theme
shikiConfig: {
theme: 'github-dark',
wrap: true
},
// Add remark/rehype plugins
remarkPlugins: [],
rehypePlugins: [],
// Draft pages (frontmatter.draft = true)
drafts: false,
// Smartypants - smart quotes and dashes
smartypants: true,
// GitHub-Flavored Markdown
gfm: true
}
});
```
Remark plugins process Markdown AST before HTML conversion:
```js theme={null}
import remarkToc from 'remark-toc';
export default defineConfig({
markdown: {
remarkPlugins: [remarkToc]
}
});
```
Rehype plugins process HTML after Markdown conversion:
```js theme={null}
import rehypeMinify from 'rehype-minify';
export default defineConfig({
markdown: {
rehypePlugins: [rehypeMinify]
}
});
```
## Best Practices
Use Content Collections for type-safe content management
Create reusable layouts for consistent styling
For complex content sites, use Content Collections instead of accessing Markdown files directly. They provide type safety, validation, and better performance.
## MDX-Specific Features
### Export Variables
Export variables from MDX to use in your content:
```mdx theme={null}
export const title = 'My Post';
export const publishedDate = new Date('2026-03-03');
# {title}
Published: {publishedDate.toLocaleDateString()}
```
### JavaScript Expressions
Use JavaScript expressions inline:
```mdx theme={null}
The answer is {2 + 2}.
Current year: {new Date().getFullYear()}
```
### Component Props
Pass props to components:
```mdx theme={null}
import Alert from '../components/Alert.astro';
This is a warning message!
```
## Common Use Cases
```markdown src/pages/blog/first-post.md theme={null}
---
layout: ../../layouts/BlogPost.astro
title: My First Blog Post
author: Jane Doe
date: 2026-03-03
tags: [astro, blogging]
---
# Welcome to my blog!
This is my first post using Astro and Markdown.
```
```mdx src/pages/docs/getting-started.mdx theme={null}
---
title: Getting Started
description: Learn how to get started
---
import CodeExample from '../../components/CodeExample.astro';
# Getting Started
npm create astro@latest
```
```mdx src/pages/features.mdx theme={null}
---
layout: ../layouts/Marketing.astro
title: Features
---
import FeatureCard from '../components/FeatureCard.astro';
# Amazing Features
```
## Related Resources
Type-safe content management
Wrap content with layouts
Build reusable components
Optimize images in Markdown