| title | description | i18nReady |
|---|---|---|
Markdown & MDX |
Learn how to create content using Markdown or MDX with Astro |
true |
import Since from '/components/Since.astro';
import { FileTree } from '@astrojs/starlight/components';
import RecipeLinks from "/components/RecipeLinks.astro";
import ReadMore from '~/components/ReadMore.astro';
import { Steps } from '@astrojs/starlight/components';
Markdown is commonly used to author text-heavy content like blog posts and documentation. Astro includes built-in support for standard Markdown files that can also include frontmatter YAML to define custom metadata such as a title, description, and tags.
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!
You 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.
See more about using content collections in Astro.
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.
---
# Example: src/pages/page-1.md
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.
Astro provides some extra, built-in Markdown features available when using Markdown and MDX files.
Astro provides Markdown and MDX pages (located within src/pages/) with a special frontmatter layout property that can specify a relative path (or alias) to an Astro layout component.
---
# src/pages/posts/post-1.md
layout: ../../layouts/BlogPostLayout.astro
title: Astro in brief
author: Himanshu
description: Find out what makes Astro awesome!
---
This is a post written in Markdown.Specific properties are then available to the layout component through Astro.props. For example, you can access frontmatter properties through Astro.props.frontmatter:
---
// src/layouts/BlogPostLayout.astro
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.
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://example.com/page-1/#introduction` to navigate directly to my Introduction on the page.Astro generates heading ids based on github-slugger. You can find more examples in the github-slugger documentation.
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 {.
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.
.mdx files must be written in MDX syntax rather than Astro’s HTML-like syntax.
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 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}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 file somewhere else.
---
layout: '../../layouts/BlogPostLayout.astro'
title: 'My first MDX post'
---
# {frontmatter.title}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 />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.
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 import.meta.glob().
---
// Import a single file
import * as myPost from '../pages/post/my-post.md';
// Import multiple files with import.meta.glob
const matches = await import.meta.glob('../pages/post/*.md', { eager: true });
const posts = Object.values(posts);
---When you import Markdown and MDX files in an Astro component, you get an object containing their exported properties.
---
title: 'The greatest post of all time'
author: 'Ben'
---
Here is my _great_ post!---
import * as greatPost from '../pages/post/great-post.md';
const posts = Object.values(await import.meta.glob('../pages/post/*.md', { eager: true }));
---
<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 greatest post of all time'
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>:::note[Using an Astro layout?] See the properties exported to an Astro layout component when using Astro's special frontmatter layout. :::
The following properties are available to a .astro component when using an import statement or import.meta.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 -> h6elements) in the file. Each heading’sslugcorresponds 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
exportstatement.
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 />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 matches = await import.meta.glob('../posts/**/*.md', { eager: true })
const posts = Object.values(matches);
return posts.map(post => ({
params: {
slug: post.frontmatter.slug
},
props: {
post
},
}))
}
const { Content } = Astro.props.post
---
<article>
<Content/>
</article>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 import.meta.glob() statements:
---
// src/pages/index.astro
const matches = await import.meta.glob('./*.mdx', { eager: true });
const posts = Object.values(posts);
---
{posts.map(post => <p>{post.title}</p>)}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 }} />:::note
Custom components defined and exported in an MDX file must be imported and then passed back to the <Content /> component via the components property.
:::
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 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.
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 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 defineConfig({
markdown: {
// Applied to .md and .mdx files
remarkPlugins: [ [remarkToc, { heading: 'toc', maxDepth: 3 } ] ],
rehypePlugins: [rehypeAccessibleEmojis],
},
});Astro 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 { defineConfig } from 'astro/config';
import { rehypeHeadingIds } from '@astrojs/markdown-remark';
import { otherPluginThatReliesOnHeadingIDs } from 'some/plugin/source';
export default defineConfig({
markdown: {
rehypePlugins: [
rehypeHeadingIds,
otherPluginThatReliesOnHeadingIDs,
],
},
});:::note
getHeadings() only returns the headings written directly in a Markdown or MDX file itself. If an MDX file imports components that contain their own headings, these will not be returned by getHeadings().
:::
In order to customize a plugin, provide an options object after it in a nested array.
The example below adds the heading option to the remarkToc plugin to change where the table of contents is placed, and the behavior option to the rehype-autolink-headings plugin in order to add the anchor tag after the headline text.
import remarkToc from 'remark-toc';
import rehypeSlug from 'rehype-slug';
import rehypeAutolinkHeadings from 'rehype-autolink-headings';
export default {
markdown: {
remarkPlugins: [ [remarkToc, { heading: "contents"} ] ],
rehypePlugins: [rehypeSlug, [rehypeAutolinkHeadings, { behavior: 'append' }]],
},
}:::note If you are using content collections, please see "Modifying Frontmatter with Remark". :::
You can add frontmatter properties to all of your Markdown and MDX files by using a remark or rehype plugin.
1. Append a `customProperty` to the `data.astro.frontmatter` property from your plugin's `file` argument:```js title="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';
}
}
```
:::tip
<Since v="2.0.0" />
`data.astro.frontmatter` contains all properties from a given Markdown or MDX document. This allows you to modify existing frontmatter properties, or compute new properties from this existing frontmatter.
:::
-
Apply this plugin to your
markdownormdxintegration config:import { defineConfig } from 'astro/config'; import { exampleRemarkPlugin } from './example-remark-plugin.mjs'; export default defineConfig({ markdown: { remarkPlugins: [exampleRemarkPlugin] }, });
or
import { defineConfig } from 'astro/config'; import { exampleRemarkPlugin } from './example-remark-plugin.mjs'; export default defineConfig({ 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.
<RecipeLinks slugs={["en/recipes/reading-time"]} />
Astro'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
})
]
});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 is our default syntax highlighter. You can configure all options via the shikiConfig object like so:
import { defineConfig } from 'astro/config';
export default defineConfig({
markdown: {
shikiConfig: {
// Choose from Shiki's built-in themes (or add your own)
// https://shiki.style/themes
theme: 'dracula',
// Alternatively, provide multiple themes
// See note below for using dual light/dark themes
themes: {
light: 'github-light',
dark: 'github-dark',
},
// Disable the default colors
// https://shiki.style/guide/dual-themes#without-default-color
// (Added in v4.12.0)
defaultColor: false,
// Add custom languages
// Note: Shiki has countless langs built-in, including .astro!
// https://shiki.style/languages
langs: [],
// Enable word wrap to prevent horizontal scrolling
wrap: true,
// Add custom transformers: https://shiki.style/guide/transformers
// Find common transformers: https://shiki.style/packages/transformers
transformers: [],
},
},
});:::note[Customizing Shiki themes]
Astro code blocks are styled using the .astro-code class. When following Shiki's documentation (e.g. to customize light/dark dual or multiple themes), be sure to replace the .shiki class in the examples with .astro-code.
:::
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.
If you'd like to switch to 'prism' by default, or disable syntax highlighting entirely, you can use the markdown.syntaxHighlighting config object:
import { defineConfig } from 'astro/config';
export default defineConfig({
markdown: {
// Can be 'shiki' (default), 'prism' or false to disable highlighting
syntaxHighlight: 'prism',
},
});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!
1. Choose a premade stylesheet from the available [Prism Themes](https://github.com/PrismJS/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.
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} />