Welcome to Magic MDX with Astro

If you have used MDX before, you might have noticed that MDX files tend to become quite technical.

For us tech nerds, that is mostly fine, and being able to write the content of our technical documents in Markdown is already a big gain. But for non-tech content-editors, writing this style of markdown is quite a burden, and actually I realized, that it is quite a burden for my mind, too.

Christian from Hack Your Shack

I like my content to be clean, so I decided to dust off my MDX with astro-m2dx.

With the arrival of Astro v1.0🚀 and it’s MDX Integration, there was the chance to implement a publication pipeline that provides content-editors with the ability to write almost clean markdown, with some directives, only a few sprinkles of JSX and without overloading the frontmatter: Astro Magic MDX aka astro-m2dx was born.

Astro M²DX is a remark plugin, that you can use in your Astro site generator, to keep your MDX close to Markdown, while still using all of the rich MDX features.

Now with support for image optimization, even for ![Markdown](./image.tags):style{.and-art-direction}!

Dear Astronauts, grab your vacuum cleaner and dust off your MDX, now!

Install

This package is provided on NPM and it is ESM only. In Node.js (version 12.20+, 14.14+, or 16.0+), install with npm:

npm install astro-m2dx

…and in your astro.config.mjs:

import { defineConfig } from 'astro/config';

import mdx from '@astrojs/mdx';
import m2dx from 'astro-m2dx';
//                ^^^^^^^^^^

/** @type {import('astro-m2dx').Options} */
const m2dxOptions = {
  // activate any required feature here
};

// https://astro.build/config
export default defineConfig({
  integrations: [mdx()],
  markdown: {
    remarkPlugins: [[m2dx, m2dxOptions]],
    //               ^^^^
    extendDefaultPlugins: true,
  },
});

From here…

Check out the blog, that introduces some usage scenarios in detail, or check out the docs.

Source code for this page

Besides the plugin, the sources of this web site are published as a showcase of how to apply the plugin to a file/git-based publication workflow, find it on Github.

BTW: This is the complete MDX source for this page (embedded from the injected raw content, see feature rawmdx for details):

Have a look how clean the markdown is
✔️ No frontmatter
✔️ No imports required
✔️ Only very few components
✔️ Mostly pure markdown


# Welcome to :style[Magic MDX]{.shine} with Astro

:::style{.aside-left}

If you have used [MDX](https://mdxjs.com) before, you might have noticed that MDX files tend to become quite technical.

For us tech nerds, that is mostly fine, and being able to write the content of our technical documents in Markdown is already a big gain. But for non-tech content-editors, writing this style of markdown is quite a burden, and actually I realized, that it is quite a burden for my mind, too.

::Quote[I like my content to be clean, so I decided to **dust off my MDX** with **astro-m2dx**.]{author='Christian' from='Hack Your Shack' avatar='./christian.png'}

With the arrival of [Astro v1.0](https://astro.build)🚀 and it's [MDX Integration](https://docs.astro.build/en/guides/integrations-guide/mdx/), there was the chance to implement a publication pipeline that provides content-editors with the ability to write almost clean markdown, with some directives, only a few sprinkles of JSX and without overloading the frontmatter: **Astro Magic MDX** aka [**astro-m2dx**](https://www.npmjs.com/package/astro-m2dx) was born.

Astro M²DX is a [**remark** plugin](https://remark.js.org/), that you can use in your Astro site generator, to keep your MDX close to Markdown, while still using all of the rich MDX features.

Now with support for [image optimization](/blog/working-with-images), even for `![Markdown](./image.tags):style{.and-art-direction}`!

![Astronaut vacuuming stars](./astronaut.jpg):style{.aside}
:::

::CTA[Dear Astronauts, :style[grab your vacuum cleaner]{.underline} and dust off your MDX, now!]{href="https://www.npmjs.com/package/astro-m2dx"}

## Install

This package is provided on [NPM](https://www.npmjs.com/package/astro-m2dx) and it is [ESM only](https://gist.github.com/sindresorhus/a39789f98801d908bbc7ff3ecc99d99c).
In Node.js (version 12.20+, 14.14+, or 16.0+), install with **npm**:

```sh
npm install astro-m2dx
```

...and in your `astro.config.mjs`:

```js
import { defineConfig } from 'astro/config';

import mdx from '@astrojs/mdx';
import m2dx from 'astro-m2dx';
//                ^^^^^^^^^^

/** @type {import('astro-m2dx').Options} */
const m2dxOptions = {
  // activate any required feature here
};

// https://astro.build/config
export default defineConfig({
  integrations: [mdx()],
  markdown: {
    remarkPlugins: [[m2dx, m2dxOptions]],
    //               ^^^^
    extendDefaultPlugins: true,
  },
});
```

## From here...

Check out [the blog](/blog), that introduces some usage scenarios in detail, or check out [the docs](/docs).

## Source code for this page

Besides the plugin, the sources of this web site are published as a showcase of how to apply the plugin to a file/git-based publication workflow, [find it on Github](https://github.com/christian-hackyourshack/npm/tree/main/apps/astro-m2dx).

BTW: This is the complete MDX source for this page (embedded from the injected raw content, see feature `rawmdx` for details):

> Have a look how clean the markdown is  
> ✔️ No frontmatter  
> ✔️ No imports required  
> ✔️ Only very few components  
> ✔️ Mostly pure markdown

<Code code={frontmatter?.rawmdx ?? 'Raw MDX not found'} lang="mdx" />