Home
☰

Astro - M²DX

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 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.

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,
  },
});

The Features

Astro M²DX provides a plentitude of features, but when adding astro-m2dx to your project, none of the features is active by default, you have to activate them in the Astro configuration (and by providing the respective configuration files, e.g. for per-directory frontmatter).

Default Frontmatter

Reduce the size of your frontmatter, by defining default properties in extra YAML files, that will be injected into all* MDX files.

You could use it to define a default layout property for all files.

Read the docs

Export components

Map HTML elements to JSX components: Define a mapping from standard HTML elements to complex JSX components for all* MDX files.

Read the docs

Auto import

Use JSX components in your MDX without import: Define a set of known JSX components, that can be used in all* MDX files without explicitly being imported.

Read the docs

Relative Images

All relative image references (textual values) with a resolvable reference are replaced with an imported image reference in the compiled MDX.

The resolution will also be applied to obviously relative image references in JSX components.

Read the docs

Style Directives

Use markdown directives to style elements, i.e. apply CSS classes to the generated HTML elements:
> :style{.warning} Warning: This is a warning!

⚠️ In order to use this feature, you must insert the plugin remark-directive before astro-m2dx.

Read the docs

Include directive

Modularize your content and include other MDX files in your MDX file with a ::include[./partial.mdx] directive.

⚠️ In order to use this feature, you must insert the plugin remark-directive before astro-m2dx.

Read the docs

Component directives

If you like pure Markdown style and prefer generic directives over embedded JSX components, this feature is for: map any directive to a JSX component.

⚠️ In order to use this feature, you must insert the plugin remark-directive before astro-m2dx.

Read the docs

Add-ons

Provide simple transformer functions to enhance the MDAST without writing a full plugin.

Read the docs

Inject raw MDX

Get (read-only) access to the (really) raw MDX content of your file.

Read the docs

Inject MDAST

Get (read-only) access to the MarkDown Abstract Syntax Tree, e.g. to transform to text or analyze for added meta-info in your layout.

Read the docs

(*) ‘All’ always means, you can put the definition into a directory and it will be applied to all MDX files in that directory and it’s subdirectories, i.e. you can override these values in lower, more specific directories.

Upcoming Features

Currently no further features are planned.

If you want to request one or start a discussion, open an issue on github…

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

# Astro - M²DX

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{author='Christian' from='Hack Your Shack' avatar='./christian.png'}
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](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** 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.

::callToAction[Dear Astronauts, grab your vacuum cleaner 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,
  },
});
```

## The Features

Astro M²DX provides a plentitude of features, but when adding astro-m2dx to your project, none of the features is active by default, you have to activate them in the Astro configuration (and by providing the respective configuration files, e.g. for per-directory frontmatter).

::include[./_feature-cards.mdx]

## Upcoming Features

Currently no further features are planned.

If you want to request one or start a discussion, [open an issue on github](https://github.com/christian-hackyourshack/npm/issues/new/choose)...

## 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" />