There are two ways to enhance Markdown in an Astro project:
This article focuses on the Markdown Component.
I use a Markdown Component for two main reasons:
' to opening or closing quotes (' or ').So, I can skip several HTML tags — like <p>, <strong>, <em>, <ul>, <ol>, <li>, and <a>. I can also skip heading tags if I don’t need to add classes to them.
<div class="card">
<!-- prettier-ignore -->
<Markdown>
## Card Title
This is a paragraph with **strong** and *italic* text.
This is the second paragraph with a [link](https://link-somewhere.com)
- List
- Of
- Items
</Markdown>
</div>Notice the prettier-ignore comment? It tells prettier not to format the contents within the <Markdown> block so Prettier won’t mess up my Markdown content.
The HTML output will be as follows:
<div class="card">
<h2> Card Title </h2>
<p>This is a paragraph with <strong>strong</strong> and <em>italic</em> text.</p>
<p>This is the second paragraph with a <a href="https://link-somewhere.com">link</a></p>
<ul>
<li> List </li>
<li> Of </li>
<li> Items </li>
</ul>
</div>Fun Fact: Astro came with a <Markdown> component in its early release, but this <Markdown> component was migrated to a separate plugin in Version 1, and completely removed in version 3.
I was upset about it. But I decided to build a Markdown component for myself since I liked using one. You can the documentation here.
Using the Markdown component is simple: Just import and use it in the way I showed you above.
---
import { Markdown } from '@splendidlabz/astro'
---
<Markdown>
...
</Markdown>You can write your Markdown naturally, as if you’re writing content normally. This Markdown component detects the indentation and outputs the correct values (without wrapping them in <pre> and <code> tags).
<div>
<div>
<!-- prettier-ignore -->
<Markdown>
This is a paragraph
This is a second paragraph
</Markdown>
</div>
</div>Here’s the output:
<div>
<div>
<p>This is a paragraph</p>
<p>This is a second paragraph</p>
</div>
</div>There’s an inline option that tells the <Markdown> component not to generate paragraph tags.
<h2 class="max-w-[12em]">
<Markdown inline> Ain't this cool? </Markdown>
</h2>Here’s the output:
<h2 class="max-w-[12em]">
Ain't this cool?
</h2>Prettier messes up the <!-- prettier-ignore --> block if you have unicode characters like emojis and em dashes anywhere before the block.
Here’s the original code:
<!-- prettier-ignore -->
<Markdown>
Markdown block that contains Unicode characters 🤗
</Markdown>
<!-- prettier-ignore -->
<Markdown>
Second Markdown block.
</Markdown>Here’s what it looks like after saving:
<!-- prettier-ignore -->
<Markdown>
Markdown block that contains unicode characters 🤗
</Markdown>
<!-- prettier-ignore -->
<Markdown>
Second Markdown block.
</Markdown>Unfortunately, we can’t do much about emojis because the issue stems from Prettier’s formatter.
But, we can use en and em dashes by writing -- and ---, respectively.
You can prevent Prettier from breaking all those <!-- prettier-ignore --> comments by not using them!
To do this, you just put your content inside a content property. No need to worry about whitespace as well — that’s taken care of for you.
<Markdown content=`
This is a paragraph
This is another paragraph
`/>Personally, I think it doesn’t look at nice as slot version above…
But it lets you use markdown directly with any JS or json content you load!
---
const content = `
This is a paragraph
This is another paragraph
`
---
<Markdown {content} />I’ve been building with Astro for 3+ years, and I kept running into the same friction points on content-heavy sites: blog pages, tag pages, pagination, and folder structures that get messy over time.
So I built Practical Astro: Content Systems — 7 ready-to-use solutions for Astro content workflows (MDX is just one of them). You get both the code and the thinking behind it.
If you want a cleaner, calmer content workflow, check it out.
I also write about Astro Patterns and Using Tailwind + CSS together on my blog. Come by and say hi!
Enhancing Astro With a Markdown Component originally handwritten and published with love on CSS-Tricks. You should really get the newsletter as well.
Markdown is a great invention that lets us write less markup. It also handles typographical matters like converting straight apostrophes (') to opening or closing quotes (' or ') for us.
Although Astro has built-in support for Markdown via .md files, I’d argue that your Markdown experience can be enhanced in two ways:
I’ve cover these in depth in Practical Astro: Content Systems.
We’re going to focus on MDX today.
MDX is a superset of Markdown. It lets you use components in Markdown and simple JSX in addition to all other Markdown features.
For Astro, you can also use components from any frontend framework that you have installed. So you can do something like:
---
# Frontmatter...
---
import AstroComp from '@/components/AstroComp.astro'
import SvelteComp from '@/components/AstroComp.astro'
<AstroComp> ... </AstroComp>
<SvelteComp> ... </SvelteComp>It can be a great substitute for content-heavy stuff because it lets you write markup like the following.
<div class="card">
### Card Title
Content goes here
- List
- Of
- Items
Second paragraph
</div>Astro will convert the MDX into the following HTML:
<div class="card">
<h2>Card Title</h2>
<p>Content goes here </p>
<ul>
<li> List </li>
<li> Of </li>
<li> Items </li>
</ul>
<p>Second paragraph</p>
</div>Notice what I did above:
## instead of a full h2 tag.- instead of <ul> and <li> to denote lists.Writing the whole thing in HTML directly would have been somewhat of a pain.
Astro folks have built an integration for MDX so it’s easy-peasy to add it to your project. Just follow these instructions.
These methods also work with standard Markdown files.
The first way is simply to import your MDX file and use it directly as a component.
---
import MDXComp from '../components/MDXComp.mdx'
---
<MDXComp />Because of this, MDX can kinda function like a partial.
First, you feed your MDX into a content collection. Note that you have to add the mdx pattern to your glob here.
The first way is simply to import your MDX file and use it directly as a component.
// src/content.config.js
import { defineCollection } from 'astro:content';
import { glob } from 'astro/loaders';
const blog = defineCollection({
loader: glob({ pattern: "**/*.{md,mdx}", base: "./src/blog" }),
});
export const collections = { blog };Then you retrieve the MDX file from the content collection.
---
import { getEntry, render } from 'astro:content'
const { slug } = Astro.props
const post = await getEntry('blog', slug)
const { Content } = await render(post)
---
<Content />As you’re doing this, you can pass components into the MDX files so you don’t have to import them individually in every file.
For example, here’s how I would pass the Image component from Splendid Labz into each of my MDX files.
---
import { Image } from '@splendidlabz/astro'
// ...
const { Content } = await render(post)
const components = { Image }
---
<Content {components} />In my MDX files, I can now use Image without importing it.
<Image src="..." alt="..." />Finally, you can add a layout frontmatter in the MDX file.
---
title: Blog Post Title
layout: @/layouts/MDX.astro
---This layout frontmatter should point to an Astro file.
In that file:
Astro.props.content.<slot>.---
import Base from './Base.astro'
const props = Astro.props.content
const { title } = props
---
<Base>
<h1>{title}</h1>
<slot />
</Base>ESLint and Prettier don’t format MDX files well, so you’ll end up manually indenting most of your markup.
This is fine for small amounts of markup. But if you have lots of them… then the Markdown Component will be a much better choice.
More on that in another upcoming post.
The Astro RSS integration doesn’t support MDX files out of the box.
Thankfully, this can be handled easily with Astro containers. I’ll show you how to do this in Practical Astro.
I’ve been building with Astro for 3+ years, and I kept running into the same friction points on content-heavy sites: blog pages, tag pages, pagination, and folder structures that get messy over time.
So I built Practical Astro: Content Systems, 7 ready-to-use solutions for Astro content workflows (MDX is just one of them). You get both the code and the thinking behind it.
If you want a cleaner, calmer content workflow, check it out.
I also write about Astro Patterns and Using Tailwind + CSS together on my blog. Come by and say hi!
Markdown + Astro = ❤️ originally handwritten and published with love on CSS-Tricks. You should really get the newsletter as well.
With a high of F and a low of 41F. Currently, it's 66F and Fair outside. Current wind speeds: 14 from the Southwest Pollen: 0 Su...
