Markdown & MDX

Markdown is commonly used to author text-heavy content like blog posts and documentation. Astro includes built-in support for standard Markdown files.

With the @astrojs/mdx integration installed, Astro also supports MDX (.mdx) files which bring added features like support for JavaScript expressions and components in your Markdown content.

Use either or both types of files to write your Markdown content!

Markdown and MDX Pages

File-based Routing

Astro treats any .md (or alternative supported extension) or .mdx file inside of the /src/pages/ directory as a page.

Placing a file in this directory, or any sub-directory, will automatically build a page route using the pathname of the file.

---
title: Hello, World
---

# Hi there!

This Markdown file creates a page at `your-domain.com/page-1/`

It probably isn't styled much, but Markdown does support:
- **bold** and _italics._
- lists
- [links](https://astro.build)
- and more!

📚 Read more about Astro’s file-based routing or options for creating dynamic routes.

Draft Pages

draft: true is an optional frontmatter value that will mark an individual Markdown or MDX page or post as “unpublished.” By default, this page will be:

excluded from the site build (no page will be built)
returned by Astro.glob() (visible in lists of posts)

---
layout: ../../layouts/BaseLayout.astro
title: My Blog Post
draft: true
---

This is my in-progress blog post.

No page will be built for this post.

To build and publish this post:

- update the frontmatter to `draft: false` or
- remove the `draft` property entirely.

But, this page _will_ be returned by any matching `Astro.glob()` request.

To exclude draft posts from being included in a post archive, or list of most recent posts, you can filter the results returned by Astro.glob():

const posts = await Astro.glob('../pages/post/*.md');
const nonDraftPosts = posts.filter((post) => !post.frontmatter.draft);

Enable building draft pages

To enable building draft pages by default, update astro.config.mjs by adding drafts: true to markdown or to the mdx integration:

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

Markdown Features

Astro provides some extra, built-in Markdown features available when using Markdown and MDX files.

Frontmatter `layout`

Astro provides Markdown and MDX pages with a special frontmatter layout property that can specify a relative path (or alias) to an Astro layout component.

---
layout: ../../layouts/BlogPostLayout.astro
title: Astro in brief
author: Himanshu
description: Find out what makes Astro awesome!
--- 
This is a post written in Markdown.

Frontmatter properties are then available to the layout through Astro.props:

---
const {frontmatter} = Astro.props;
---
<html>
  <!-- ... -->
  <h1>{frontmatter.title}</h1>
  <h2>Post author: {frontmatter.author}</h2>
  <p>{frontmatter.description}<p>
  <slot /> <!-- Markdown content is injected here -->
   <!-- ... -->
</html>

📚 Learn more about Markdown Layouts.

Heading IDs

Using headings in Markdown and MDX will automatically give you anchor links so you can link directly to certain sections of your page.

---
title: My page of content
---
## Introduction

I can link internally to [my conclusion](#conclusion) on the same page when writing Markdown.

## Conclusion

I can use the URL `https://my-domain.com/page-1/#introduction` to navigate directly to my Introduction on the page.

Escaping special characters

Certain characters have a special meaning in Markdown and MDX. You may need to use a different syntax if you want to display them. To do this, you can use HTML entities for these characters instead.

For example, to prevent < being interpreted as the beginning of an HTML element, write <. Or, to prevent { being interpreted as the beginning of a JavaScript expression in MDX, write {.

MDX-only Features

Adding the Astro MDX integration enhances your Markdown authoring with JSX variables, expressions and components.

It also adds extra features to standard MDX, including support for Markdown-style frontmatter in MDX. This allows you to use most of Astro’s built-in Markdown features like a frontmatter layout property and a setting for draft pages.

.mdx files must be written in MDX syntax rather than Astro’s HTML-like syntax.

Using Exported Variables in MDX

MDX supports using export statements to add variables to your MDX content. These variables are accessible both in the template itself and as named properties when importing the the file somewhere else.

For example, you can export a title field from an MDX page or component to use as a heading with {JSX expressions}:

export const title = 'My first MDX post'

# {title}

Using Frontmatter Variables in MDX

The Astro MDX integration includes support for using frontmatter in MDX by default. Add frontmatter properties just as you would in Markdown files, and these variables are accessible to use in the template, in its layout component, and as named properties when importing the the file somewhere else.

---
layout: '../../layouts/BlogPostLayout.astro'
title: 'My first MDX post'
---

# {frontmatter.title}

Using Components in MDX

After installing the MDX integration, you can import and use both Astro components and UI framework components in MDX (.mdx) files just as you would use them in any other Astro component.

Don’t forget to include a client:directive on your UI framework components, if necessary!

See more examples of using import and export statements in the MDX docs.

---
layout: ../layouts/BaseLayout.astro
title: About me
---
import Button from '../components/Button.astro';
import ReactCounter from '../components/ReactCounter.jsx';

I live on **Mars** but feel free to <Button title="Contact me" />.

Here is my counter component, working in MDX:

<ReactCounter client:load />

Assigning Custom Components to HTML elements

With MDX, you can map Markdown syntax to custom components instead of their standard HTML elements. This allows you to write in standard Markdown syntax, but apply special component styling to selected elements.

Import your custom component into your .mdx file, then export a components object that maps the standard HTML element to your custom component:

import Blockquote from '../components/Blockquote.astro';
export const components = {blockquote: Blockquote}

> This quote will be a custom Blockquote

---
const props = Astro.props;
---
<blockquote {...props} class="bg-blue-50 p-4">
  <span class="text-4xl text-blue-600 mb-2">“</span>
  <slot /> <!-- Be sure to add a `<slot/>` for child content! -->
</blockquote>

Visit the MDX website for a full list of HTML elements that can be overwritten as custom components.

Importing Markdown

You can import Markdown and MDX files directly into your Astro files. This gives you access to their Markdown content, as well as other properties such as frontmatter values that can be used within Astro’s JSX-like expressions.

You can import one specific page with an import statement, or multiple pages with Astro.glob().

---
// Import a single file
import * as myPost from '../pages/post/my-post.md';

// Import multiple files with Astro.glob
const posts = await Astro.glob('../pages/post/*.md');
---

When you import Markdown and MDX files in an Astro component, you get an object containing their exported properties.

---
title: 'The best post I've ever written'
author: 'Ben'
---

Here is my _great_ post!

---
import * as greatPost from '../pages/post/great-post.md';

const posts = await Astro.glob('../pages/post/*.md');
---

<p>{greatPost.frontmatter.title}</p>
<p>Written by: {greatPost.frontmatter.author}</p>

<p>Post Archive:</p>
<ul>
  {posts.map(post => <li><a href={post.url}>{post.frontmatter.title}</a></li>)}
</ul>

In MDX files, you can access properties from both frontmatter and export statements:

---
title: 'The best post I've ever written'
author: 'Ben'
---
export const description = 'Get comfortable! This is going to be a great read.'

Here is my _great_ post!

---
import * as greatPost from '../pages/post/mdx-post.mdx';
---

<p>{greatPost.frontmatter.title}</p>
<p>Written by: {greatPost.frontmatter.author}</p>
<p>{greatPost.description}</p>

You can optionally provide a type for the frontmatter variable using a TypeScript generic:

---
interface Frontmatter {
  title: string;
  description?: string;
}
const posts = await Astro.glob<Frontmatter>('../pages/post/*.md');
---

<ul>
  {posts.map(post => <li>{post.frontmatter.title}</li>)}
  <!-- post.frontmatter.title will be `string`! -->
</ul>

Exported Properties

The following properties are available to a .astro component when using an import statement or Astro.glob():

file - The absolute file path (e.g. /home/user/projects/.../file.md).
url - If it’s a page, the URL of the page (e.g. /en/guides/markdown-content).
frontmatter - Contains any data specified in the file’s YAML frontmatter.
getHeadings - An async function that returns an array of all headings (i.e. h1 -> h6 elements) in the file. Each heading’s slug corresponds to the generated ID for a given heading and can be used for anchor links. This list follows the type: { depth: number; slug: string; text: string }[].
Content - A component that returns the full, rendered contents of the file.
(Markdown only) rawContent() - A function that returns the raw Markdown document as a string.
(Markdown only) compiledContent() - A function that returns the Markdown document compiled to an HTML string. Note this does not include layouts configured in your frontmatter! Only the markdown document itself will be returned as HTML.
(MDX only) - MDX files can also export data with an export statement.

The `Content` Component

Import Content to render a component that returns the full rendered contents of a Markdown or MDX file:

---
import {Content as PromoBanner} from '../components/promoBanner.md';
---

<h2>Today's promo</h2>
<PromoBanner />

Example: Dynamic page routing

Instead of putting your Markdown/MDX files in the src/pages/ directory to create page routes, you can generate pages dynamically.

To access your Markdown content, pass the <Content/> component through the Astro page’s props. You can then retrieve the component from Astro.props and render it in your page template.

---
export async function getStaticPaths() {
  const posts = await Astro.glob('../posts/**/*.md')

  return posts.map(post => ({
    params: { 
      slug: post.frontmatter.slug 
    },
    props: {
      post
    },
  }))
}

const { Content } = Astro.props.post
---
<article>
  <Content/>
</article>

MDX-only Exports

MDX files can also export data with an export statement.

For example, you can export a title field from an MDX page or component.

export const title = 'My first MDX post'

This title will be accessible from import and Astro.glob() statements:

---
const posts = await Astro.glob('./*.mdx');
---

{posts.map(post => <p>{post.title}</p>)}

Custom components with imported MDX

When rendering imported MDX content, custom components can be passed via the components prop.

---
import { Content, components } from '../content.mdx';
import Heading from '../Heading.astro';
---
<!-- Creates a custom <h1> for the # syntax, _and_ applies any custom components defined in `content.mdx` -->
<Content components={{...components, h1: Heading }} />

Configuring Markdown and MDX

Markdown support in Astro is powered by remark, a powerful parsing and processing tool with an active ecosystem. Other Markdown parsers like Pandoc and markdown-it are not currently supported.

Astro applies the GitHub-flavored Markdown and Smartypants plugins by default. This brings some niceties like generating clickable links from text and formatting quotes for readability.

You can customize how remark parses your Markdown in astro.config.mjs. See the full list of Markdown configuration options.

Markdown Plugins

Astro supports adding third-party remark and rehype plugins for Markdown and MDX. These plugins allow you to extend your Markdown with new capabilities, like auto-generating a table of contents, applying accessible emoji labels, and more.

We encourage you to browse awesome-remark and awesome-rehype for popular plugins! See each plugin’s own README for specific installation instructions.

By default, Astro’s MDX integration inherits all remark and rehype plugins from your Astro config markdown options. To change this behavior, configure extendPlugins in your mdx integration.

Any additional plugins you apply in your MDX config will be applied after your configured Markdown plugins, and will apply only to .mdx files.

This example applies remark-toc to Markdown and MDX, and rehype-accessible-emojis to MDX only, while preserving Astro’s default plugins:

import { defineConfig } from 'astro/config';
import remarkToc from 'remark-toc';
import { rehypeAccessibleEmojis } from 'rehype-accessible-emojis';

export default {
  markdown: {
    // Applied to .md and .mdx files
    remarkPlugins: [remarkToc],
    // Preserves remark-gfm and remark-smartypants
    extendDefaultPlugins: true,
  },
  integrations: [mdx({
    // Applied to .mdx files only
    rehypePlugins: [rehypeAccessibleEmojis],
  })],
}

Example: Injecting frontmatter

You can add frontmatter properties to all of your Markdown and MDX files by using a remark or rehype plugin.

Append a customProperty to the data.astro.frontmatter property from your plugin’s file argument:

export function exampleRemarkPlugin() {
  // All remark and rehype plugins return a separate function
  return function (tree, file) {
    file.data.astro.frontmatter.customProperty = 'Generated property';
  }
}

Apply this plugin to your markdown or mdx integration config:

import { exampleRemarkPlugin } from './example-remark-plugin.mjs';

export default {
  markdown: {
    remarkPlugins: [exampleRemarkPlugin],
    extendDefaultPlugins: true,
  },
};

import { exampleRemarkPlugin } from './example-remark-plugin.mjs';

export default {
  integrations: [
    mdx({
      remarkPlugins: [exampleRemarkPlugin],
    }),
  ],
}

Now, every Markdown or MDX file will have customProperty in its frontmatter, making it available when importing your markdown and from the Astro.props.frontmatter property in your layouts.

Example: calculate reading time

You can use a remark plugin to add a reading time to your frontmatter. We recommend two helper packages:

reading-time to calculate minutes read
mdast-util-to-string to extract all text from your markdown

npm install reading-time mdast-util-to-string

We can apply these packages to a remark plugin like so:

import getReadingTime from 'reading-time';
import { toString } from 'mdast-util-to-string';

export function remarkReadingTime() {
  return function (tree, { data }) {
    const textOnPage = toString(tree);
    const readingTime = getReadingTime(textOnPage);
    // readingTime.text will give us minutes read as a friendly string,
    // i.e. "3 min read"
    data.astro.frontmatter.minutesRead = readingTime.text;
  };
}

Once you apply this plugin to your config:

import { remarkReadingTime } from './remark-reading-time.mjs';

export default {
  markdown: {
    remarkPlugins: [remarkReadingTime],
    extendDefaultPlugins: true,
  },
};

…all Markdown documents will have a calculated minutesRead. You can use this to include an “X min read” banner in a markdown layout, for instance:

---
const { minutesRead } = Astro.props.frontmatter;
---

<html>
  <head>...</head>
  <body>
    <p>{minutesRead}</p>
    <slot />
  </body>
</html>

Syntax Highlighting

Astro comes with built-in support for Shiki and Prism. This provides syntax highlighting for:

all code fences (```) used in a Markdown or MDX file.
content within the built-in <Code /> component (powered by Shiki).
content within the <Prism /> component (powered by Prism).

Shiki is enabled by default, preconfigured with the github-dark theme. The compiled output will be limited to inline styles without any extraneous CSS classes, stylesheets, or client-side JS.

Shiki configuration

Shiki is our default syntax highlighter. You can configure all options via the shikiConfig object like so:

export default {
  markdown: {
    shikiConfig: {
      // Choose from Shiki's built-in themes (or add your own)
      // https://github.com/shikijs/shiki/blob/main/docs/themes.md
      theme: 'dracula',
      // Add custom languages
      // Note: Shiki has countless langs built-in, including .astro!
      // https://github.com/shikijs/shiki/blob/main/docs/languages.md
      langs: [],
      // Enable word wrap to prevent horizontal scrolling
      wrap: true,
    },
  },
};

Adding your own theme

Instead of using one of Shiki’s predefined themes, you can import a custom theme from a local file.

import { defineConfig } from 'astro/config';
import customTheme from './my-shiki-theme.json';

export default defineConfig({
  markdown: {
    shikiConfig: { theme: customTheme },
  },
});

We also suggest reading Shiki’s own theme documentation to explore more about themes, light vs dark mode toggles, or styling via CSS variables.

Change Default Syntax Highlighting Mode

If you’d like to switch to 'prism' by default, or disable syntax highlighting entirely, you can use the markdown.syntaxHighlighting config object:

export default {
  markdown: {
    // Can be 'shiki' (default), 'prism' or false to disable highlighting
    syntaxHighlight: 'prism',
  },
};

Prism configuration

If you opt to use Prism, Astro will apply Prism’s CSS classes instead. Note that you need to bring your own CSS stylesheet for syntax highlighting to appear!

Choose a premade stylesheet from the available Prism Themes.
Add this stylesheet to your project’s public/ directory.
Load this into your page’s <head> in a layout component via a <link> tag. (See Prism basic usage.)

You can also visit the list of languages supported by Prism for options and usage.

Fetching Remote Markdown

Astro was primarily designed for local Markdown files that could be saved inside of your project directory. However, there may be certain cases where you need to fetch Markdown from a remote source. For example, you may need to fetch and render Markdown from a remote API when you build your website (or when a user makes a request to your website, when using SSR).

Astro does not include built-in support for remote Markdown! To fetch remote Markdown and render it to HTML, you will need to install and configure your own Markdown parser from npm. This will not inherit from any of Astro’s built-in Markdown and MDX settings that you have configured. Be sure that you understand these limitations before implementing this in your project.

---
// Example: Fetch Markdown from a remote API 
// and render it to HTML, at runtime.
// Using "marked" (https://github.com/markedjs/marked)
import { marked } from 'marked';
const response = await fetch('https://raw.githubusercontent.com/wiki/adam-p/markdown-here/Markdown-Cheatsheet.md');
const markdown = await response.text();
const content = marked.parse(markdown);
---
<article set:html={content} />