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
Section titled Markdown and MDX PagesContent collections
Section titled Content collectionsYou can manage your Markdown and MDX files in Astro in a special src/content/
folder. Content collections help you organize your content, validate your frontmatter, and provide automatic TypeScript type-safety while working with your content.
src/content/
newsletter/
- week-1.md
- week-2.md
authors/
- grace-hopper.md
- alan-turing.md
See more about using content collections in Astro.
File-based Routing
Section titled File-based RoutingAstro 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
Section titled Draft Pagesdraft: 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
Section titled Enable building draft pagesTo 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
Section titled Markdown FeaturesAstro provides some extra, built-in Markdown features available when using Markdown and MDX files.
Frontmatter layout
Section titled Frontmatter layoutAstro 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>
You can also style your Markdown in your layout component.
📚 Learn more about Markdown Layouts.
Heading IDs
Section titled Heading IDsUsing 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
Section titled Escaping special charactersCertain 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
Section titled MDX-only FeaturesAdding 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
Section titled Using Exported Variables in MDXMDX 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 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
Section titled Using Frontmatter Variables in MDXThe 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 file somewhere else.
---
layout: '../../layouts/BlogPostLayout.astro'
title: 'My first MDX post'
---
# {frontmatter.title}
Using Components in MDX
Section titled Using Components in MDXAfter 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
Section titled Assigning Custom Components to HTML elementsWith 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
Section titled Importing MarkdownYou 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
Section titled Exported PropertiesThe 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’sslug
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
Section titled The Content ComponentImport 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
Section titled Example: Dynamic page routingInstead 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
Section titled MDX-only ExportsMDX 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
Section titled Custom components with imported MDXWhen 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
Section titled Configuring Markdown and MDXMarkdown 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 for quotations and em-dashes.
You can customize how remark parses your Markdown in astro.config.mjs
. See the full list of Markdown configuration options.
Markdown Plugins
Section titled Markdown PluginsAstro 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 styling your Markdown.
We encourage you to browse awesome-remark and awesome-rehype for popular plugins! See each plugin’s own README for specific installation instructions.
This example applies remark-toc
and rehype-accessible-emojis
to both Markdown and MDX files:
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, rehypeAccessibleEmojis],
},
}
Heading IDs and plugins
Section titled Heading IDs and pluginsAstro injects an id
attribute into all heading elements (<h1>
to <h6>
) in Markdown and MDX files and provides a getHeadings()
utility for retrieving these IDs in Markdown exported properties.
You can customize these heading IDs by adding a rehype plugin that injects id
attributes (e.g. rehype-slug
). Your custom IDs, instead of Astro’s defaults, will be reflected in the HTML output and the items returned by getHeadings()
.
By default, Astro injects id
attributes after your rehype plugins have run. If one of your custom rehype plugins needs to access the IDs injected by Astro, you can import and use Astro’s rehypeHeadingIds
plugin directly. Be sure to add rehypeHeadingIds
before any plugins that rely on it:
import { rehypeHeadingIds } from '@astrojs/markdown-remark';
export default {
markdown: {
rehypePlugins: [
rehypeHeadingIds,
otherPluginThatReliesOnHeadingIDs,
],
},
}
Modifying frontmatter programmatically
Section titled Modifying frontmatter programmaticallyYou can add frontmatter properties to all of your Markdown and MDX files by using a remark or rehype plugin.
-
Append a
customProperty
to thedata.astro.frontmatter
property from your plugin’sfile
argument:example-remark-plugin.mjs 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
ormdx
integration config:astro.config.mjs import { exampleRemarkPlugin } from './example-remark-plugin.mjs'; export default { markdown: { remarkPlugins: [exampleRemarkPlugin], extendDefaultPlugins: true, }, };
or
astro.config.mjs 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
Section titled Example: calculate reading timeYou can use a remark plugin to add a reading time to your frontmatter. We recommend two helper packages:
reading-time
to calculate minutes readmdast-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>
Extending Markdown config from MDX
Section titled Extending Markdown config from MDXAstro’s MDX integration will extend your project’s existing Markdown configuration by default. To override individual options, you can specify their equivalent in your MDX configuration.
The following example disables GitHub-Flavored Markdown and applies a different set of remark plugins for MDX files:
import { defineConfig } from 'astro/config';
import mdx from '@astrojs/mdx';
export default defineConfig({
markdown: {
syntaxHighlight: 'prism',
remarkPlugins: [remarkPlugin1],
gfm: true,
},
integrations: [
mdx({
// `syntaxHighlight` inherited from Markdown
// Markdown `remarkPlugins` ignored,
// only `remarkPlugin2` applied.
remarkPlugins: [remarkPlugin2],
// `gfm` overridden to `false`
gfm: false,
})
]
});
To avoid extending your Markdown config from MDX, set the extendMarkdownConfig
option (enabled by default) to false
:
import { defineConfig } from 'astro/config';
import mdx from '@astrojs/mdx';
export default defineConfig({
markdown: {
remarkPlugins: [remarkPlugin],
},
integrations: [
mdx({
// Markdown config now ignored
extendMarkdownConfig: false,
// No `remarkPlugins` applied
})
]
});
Syntax Highlighting
Section titled Syntax HighlightingAstro 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 style
s without any extraneous CSS classes, stylesheets, or client-side JS.
Shiki configuration
Section titled Shiki configurationShiki 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
Section titled Adding your own themeInstead 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
Section titled Change Default Syntax Highlighting ModeIf 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
Section titled Prism configurationIf 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
Section titled Fetching Remote MarkdownAstro 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} />