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 help 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 Techniques.
We’re going to concentrate on MDX immediately.
MDX
MDX is a superset of Markdown. It enables you to use elements in Markdown and easy JSX along with all different Markdown options.
For Astro, you may also use elements from any frontend framework that you’ve put in. So you are able to do one thing like:
---
# Frontmatter...
---
import AstroComp from '@/elements/AstroComp.astro'
import SvelteComp from '@/elements/AstroComp.astro'
...
... It may be an important 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
- Record
- Of
- Objects
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 immediately would have been considerably of a ache.
Putting in MDX
Astro of us have constructed an integration for MDX so it’s easy-peasy so as to add it to your mission. Simply observe these directions.
Three Principal Methods to Use MDX
These strategies additionally work with customary Markdown recordsdata.
- Import it immediately into an Astro file
- By means of content material collections
- By means of a structure
Import it Straight
The primary approach is just to import your MDX file and use it immediately as a element.
---
import MDXComp from '../elements/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. Notice that it’s a must to add the mdx sample to your glob right here.
Import it immediately
The primary approach is just to import your MDX file and use it immediately 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 };You then 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 may move elements into the MDX recordsdata so that you don’t must 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 elements = { Picture }
---
In my MDX recordsdata, I can now use Picture with out importing it.
Use a Structure
Lastly, you may add a structure frontmatter within the MDX file.
---
title: Weblog Submit Title
structure: @/layouts/MDX.astro
---This structure frontmatter ought to level to an Astro file.
In that file:
- You possibly can 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 properly, so that you’ll find yourself manually indenting most of your markup.
That is fantastic for small quantities of markup. However you probably have a number 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 help MDX recordsdata out of the field.
Fortunately, this may be dealt with simply with Astro containers. I’ll present you ways to do that in Sensible Astro.
Taking it Additional
I’ve been constructing with Astro for 3+ years, and I stored operating into the identical friction factors on content-heavy websites: weblog pages, tag pages, pagination, and folder buildings that get messy over time.
So I constructed Sensible Astro: Content material Techniques, 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 would like 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!
