Markdown is a superb invention that lets us write much less markup. It additionally handles typographical issues like changing straight apostrophes (') to opening or closing quotes (' or ') for us.
Though Astro has built-in assist for Markdown through .md recordsdata, I’d argue that your Markdown expertise could be enhanced in two methods:
- MDX
- Markdown Element
I’ve cowl these in depth in Sensible Astro: Content material Programs.
We’re going to deal with MDX immediately.
MDX
MDX is a superset of Markdown. It enables you to use parts in Markdown and easy JSX along with all different Markdown options.
For Astro, you can too use parts from any frontend framework that you’ve put in. So you are able to do one thing like:
---
# Frontmatter...
---
import AstroComp from '@/parts/AstroComp.astro'
import SvelteComp from '@/parts/AstroComp.astro'
...
... It may be an ideal substitute for content-heavy stuff as a result of it enables you to write markup like the next.
### Card Title
Content material goes right here
- Checklist
- Of
- Gadgets
Second paragraph
Astro will convert the MDX into the next HTML:
Card Title
Content material goes right here
Second paragraph
Discover what I did above:
- I used
##as a substitute of a fullh2tag. - I used
-as a substitute ofand - I didn’t want any paragraph tags.
Writing the entire thing in HTML straight would have been considerably of a ache.
Putting in MDX
Astro people have constructed an integration for MDX so it’s easy-peasy so as to add it to your undertaking. Simply comply with these directions.
Three Most important Methods to Use MDX
These strategies additionally work with customary Markdown recordsdata.
- Import it straight into an Astro file
- By means of content material collections
- By means of a format
Import it Instantly
The primary method is just to import your MDX file and use it straight as a element.
---
import MDXComp from '../parts/MDXComp.mdx'
---
Due to this, MDX can kinda operate like a partial.
By means of Content material Collections
First, you feed your MDX right into a content material assortment. Observe that it’s a must to add the mdx sample to your glob right here.
Import it straight
The primary method is just to import your MDX file and use it straight as a element.
// src/content material.config.js
import { defineCollection } from 'astro:content material';
import { glob } from 'astro/loaders';
const weblog = defineCollection({
loader: glob({ sample: "**/*.{md,mdx}", base: "./src/weblog" }),
});
export const collections = { weblog };Then you definitely retrieve the MDX file from the content material assortment.
---
import { getEntry, render } from 'astro:content material'
const { slug } = Astro.props
const put up = await getEntry('weblog', slug)
const { Content material } = await render(put up)
---
As you’re doing this, you possibly can move parts into the MDX recordsdata so that you don’t need to import them individually in each file.
For instance, right here’s how I might move the Picture element from Splendid Labz into every of my MDX recordsdata.
---
import { Picture } from '@splendidlabz/astro'
// ...
const { Content material } = await render(put up)
const parts = { Picture }
---
In my MDX recordsdata, I can now use Picture with out importing it.
Use a Structure
Lastly, you possibly can add a format frontmatter within the MDX file.
---
title: Weblog Put up Title
format: @/layouts/MDX.astro
---This format frontmatter ought to level to an Astro file.
In that file:
- You’ll be able to extract frontmatter properties from
Astro.props.content material. - The MDX content material could be rendered with
---
import Base from './Base.astro'
const props = Astro.props.content material
const { title } = props
---
Caveats
Formatting and Linting Fails
ESLint and Prettier don’t format MDX recordsdata effectively, so that you’ll find yourself manually indenting most of your markup.
That is nice for small quantities of markup. However if in case you have a lot of them… then the Markdown Element will probably be a a lot better alternative.
Extra on that in one other upcoming put up.
The Astro RSS integration doesn’t assist MDX recordsdata out of the field.
Fortunately, this may be dealt with simply with Astro containers. I’ll present you the way to do that in Sensible Astro.
Taking it Additional
I’ve been constructing with Astro for 3+ years, and I saved working into the identical friction factors on content-heavy websites: weblog pages, tag pages, pagination, and folder constructions that get messy over time.
So I constructed Sensible Astro: Content material Programs, 7 ready-to-use options for Astro content material workflows (MDX is only one of them). You get each the code and the pondering behind it.
If you need a cleaner, calmer content material workflow, test it out.
I additionally write about Astro Patterns and Utilizing Tailwind + CSS collectively on my weblog. Come by and say hello!
