astro/packages/integrations/mdx
bholmesdev da1895fbdb Squashed commit of markdoc-poc
commit bd0dd9d71938da22f596ddd1662d9b91707f80c7
Author: bholmesdev <hey@bholmes.dev>
Date:   Wed Feb 15 09:43:04 2023 -0500

    Revert "feat: support `.md` overrides for content collections"

    This reverts commit c06f83ef85.

commit 5b9a1f33f4d0ffd4a63a81a86652fee032b75d76
Author: bholmesdev <hey@bholmes.dev>
Date:   Tue Feb 14 13:48:56 2023 -0500

    feat: generate `.md` types override

commit e464ae894ed69cf492de1d3e8018d9a17c00d7a3
Author: bholmesdev <hey@bholmes.dev>
Date:   Tue Feb 14 12:56:11 2023 -0500

    chore: mdoc -> md

commit b74fd6a7d6b973b2bfd9b2ab9567801ff4d7fec1
Author: bholmesdev <hey@bholmes.dev>
Date:   Tue Feb 14 12:56:01 2023 -0500

    feat: support `.md` overrides for content collections

commit bdcc18a7c03e3524927ba7c1b18ad2fd80a2e994
Author: bholmesdev <hey@bholmes.dev>
Date:   Tue Feb 14 12:30:48 2023 -0500

    deps: remove html-escaper

commit f44b57f0fa2ac923a3f2a46471fda710e92d5824
Author: bholmesdev <hey@bholmes.dev>
Date:   Tue Feb 14 12:30:42 2023 -0500

    fix: remove unneeded html-escaper

commit fb7919498aca6beded444ed5922f3598d244d30c
Author: bholmesdev <hey@bholmes.dev>
Date:   Tue Feb 14 12:08:04 2023 -0500

    fix: type inferencing in preview

commit 0c05034b321a82f2f054b527538d57f45f096822
Author: bholmesdev <hey@bholmes.dev>
Date:   Tue Feb 14 11:32:19 2023 -0500

    fix: import types from @astrojs/markdoc

commit 57e741a6306b801ac4ce47f20f7664518359611d
Author: bholmesdev <hey@bholmes.dev>
Date:   Tue Feb 14 11:28:33 2023 -0500

    refactor: remove unneeded async

commit b19d85451e60da281bc32a2a180452987a049479
Author: bholmesdev <hey@bholmes.dev>
Date:   Tue Feb 14 10:26:20 2023 -0500

    fix: lock

commit b1083a14f9fefe5e7a9f2a8c7c31626a7430c851
Author: bholmesdev <hey@bholmes.dev>
Date:   Tue Feb 14 10:19:50 2023 -0500

    nit: 0.0.0 to avoid version bump

commit 71891ebe9dd54b495e965bf064ee78aaca9dfede
Author: bholmesdev <hey@bholmes.dev>
Date:   Tue Feb 14 09:33:27 2023 -0500

    chore: changeset

commit 444752a5e27c4f5bda54ac024eca9a7ab1c4563f
Author: bholmesdev <hey@bholmes.dev>
Date:   Tue Feb 14 09:30:10 2023 -0500

    docs: add note on Aside src

commit 619d4b3fdf02cc34ea3f8f9a0b4d93db273bb0a1
Author: bholmesdev <hey@bholmes.dev>
Date:   Tue Feb 14 09:25:56 2023 -0500

    nit: reorder type import

commit e914da05706382b17e1b8f3404fc2852002a5dc7
Author: bholmesdev <hey@bholmes.dev>
Date:   Tue Feb 14 09:25:38 2023 -0500

    refactor: clean up astroNode

commit 2dfc226f56dc6a9e3e3ace72d4c3889a1fde4e6d
Author: bholmesdev <hey@bholmes.dev>
Date:   Tue Feb 14 09:08:56 2023 -0500

    docs: README edits

commit 3c7b85c7d9e3c75d551baf33aba9a646d0d61cba
Author: bholmesdev <hey@bholmes.dev>
Date:   Tue Feb 14 09:07:29 2023 -0500

    docs: change with-markdoc title

commit 29cdea9a0be439b631389cbc906751185489cbe9
Author: bholmesdev <hey@bholmes.dev>
Date:   Mon Feb 13 18:29:10 2023 -0500

    docs: add usage and examples to Markdoc README

commit e397a80179e9bd934ef8875155d7491b1d4e077a
Author: bholmesdev <hey@bholmes.dev>
Date:   Mon Feb 13 18:18:54 2023 -0500

    fix: line endings in test

commit f9ebf59982fa7dc1202368da344897f54de7f259
Author: bholmesdev <hey@bholmes.dev>
Date:   Mon Feb 13 18:09:15 2023 -0500

    docs: @astrojs/markdoc README intro

commit 7800e9c9dac946f89e139b200a0083b53942118d
Author: bholmesdev <hey@bholmes.dev>
Date:   Mon Feb 13 18:08:07 2023 -0500

    docs: update example README

commit f0b900a6fa7f0775dfab7600c4fb04c9b64e7439
Author: bholmesdev <hey@bholmes.dev>
Date:   Mon Feb 13 18:04:34 2023 -0500

    chore: remove markdoc.config loader

commit 3f040e44d0c639dc51976abe75f46c57f0be60fc
Author: bholmesdev <hey@bholmes.dev>
Date:   Mon Feb 13 17:58:52 2023 -0500

    chore: remove unused fixture dep

commit b2ea6c26df6acf1df8f06d2feb9c91da8c8eafae
Author: bholmesdev <hey@bholmes.dev>
Date:   Mon Feb 13 17:58:25 2023 -0500

    fix: glob for single content extension

commit f4e171c05c421f8696ebc406c9d4d28967f80690
Author: bholmesdev <hey@bholmes.dev>
Date:   Mon Feb 13 15:10:39 2023 -0500

    chore: remove unused deps

commit d9095d0284b0fc22d5da367771bc5286eb8f1926
Author: bholmesdev <hey@bholmes.dev>
Date:   Mon Feb 13 15:10:31 2023 -0500

    chore: unused style tag

commit a5435f13575577bf6a954c68eef9e883959568dc
Author: bholmesdev <hey@bholmes.dev>
Date:   Mon Feb 13 15:08:52 2023 -0500

    chore: clean up Markdoc starter to essentials

commit 815e2f2bad5617ab077d278d7c751f34c22dd0d9
Author: bholmesdev <hey@bholmes.dev>
Date:   Mon Feb 13 14:13:02 2023 -0500

    feat: content prop types for markdoc!

commit 8bcd23c4e70b4900b16ebf5a30dad6ec998f4092
Author: bholmesdev <hey@bholmes.dev>
Date:   Mon Feb 13 14:05:40 2023 -0500

    feat: allow Render type injection

commit cdb7e9e4878888c0883d4082d2415f4d85050389
Author: bholmesdev <hey@bholmes.dev>
Date:   Mon Feb 13 14:04:37 2023 -0500

    chore: unused file

commit 0df33ea37d4ca9bd933be54d7f8b455fce174679
Author: bholmesdev <hey@bholmes.dev>
Date:   Mon Feb 13 14:04:31 2023 -0500

    chore: with-markdoc strictNullChecks

commit 377c6d766bd51469f09e1f946a1c2b77affe6620
Author: bholmesdev <hey@bholmes.dev>
Date:   Fri Feb 10 17:39:35 2023 -0500

    play: add docs example with Aside and Since ported

commit f9f811257167da7a5e05a7de3a12b58e7b3568b1
Author: bholmesdev <hey@bholmes.dev>
Date:   Fri Feb 10 09:22:47 2023 -0500

    chore: remove unused options object

commit c9a66bfeb0ce55ef0a1c0c6ed2da746d5250c795
Author: bholmesdev <hey@bholmes.dev>
Date:   Fri Feb 10 09:18:27 2023 -0500

    chore: remove content-types. Too early!

commit 67f49e86a980c5d858ad0e384bdc67fad5e096e6
Author: bholmesdev <hey@bholmes.dev>
Date:   Fri Feb 10 09:18:20 2023 -0500

    fix: ContentEntryType import

commit 9b93d8189213a12346520fa8a71eae824386ad3e
Author: bholmesdev <hey@bholmes.dev>
Date:   Fri Feb 10 09:10:06 2023 -0500

    chore: Markdoc working! log

commit 90f77645ef3985fbba1badeb4413759626290b1a
Author: bholmesdev <hey@bholmes.dev>
Date:   Fri Feb 10 09:09:58 2023 -0500

    test: content component dev and build

commit 14559f6a40af63106cebeba210e73392d5d1c37d
Author: bholmesdev <hey@bholmes.dev>
Date:   Fri Feb 10 09:01:10 2023 -0500

    test: prod builds

commit a0dcbff73cf8b3cf9b55434a8fb2b0b683903c5f
Author: bholmesdev <hey@bholmes.dev>
Date:   Fri Feb 10 09:01:04 2023 -0500

    fix: stop bundling markdoc for isTag

commit cb1904876f074c50c206131e9588878230bbab47
Author: bholmesdev <hey@bholmes.dev>
Date:   Fri Feb 10 09:00:53 2023 -0500

    fix: avoid import if no config present (prod build error)

commit bda8295e7920638c013875ab9fe31ce87743c95f
Author: bholmesdev <hey@bholmes.dev>
Date:   Fri Feb 10 09:00:33 2023 -0500

    chore: ignore `.astro` type error

commit 28a6d7993a227c68aeca747661254ff68883244a
Author: bholmesdev <hey@bholmes.dev>
Date:   Fri Feb 10 09:00:12 2023 -0500

    fix: remove "components" from tsconfig

commit 0297bb749599aa8063e685a7ece738afe3ae77cc
Author: bholmesdev <hey@bholmes.dev>
Date:   Fri Feb 10 09:00:01 2023 -0500

    deps: add shiki for Code comp error

commit e4f141e558b3d76b761bec69e694eaa40cdf250d
Author: bholmesdev <hey@bholmes.dev>
Date:   Fri Feb 10 08:45:37 2023 -0500

    play: make sure md also works

commit dfdb35f0888ee83457ee825172f7d8485b7d2a43
Author: bholmesdev <hey@bholmes.dev>
Date:   Thu Feb 9 13:25:18 2023 -0500

    test: entry and collections parse

commit eaf4994bf309955209f406d7db0863775fdf4fe0
Author: bholmesdev <hey@bholmes.dev>
Date:   Thu Feb 9 13:25:07 2023 -0500

    deps: devalue, test fixture

commit 3f71932c04f8064cfe74b7f4b02409c681925e4a
Author: bholmesdev <hey@bholmes.dev>
Date:   Thu Feb 9 13:24:47 2023 -0500

    chore: remove unused dream file

commit b182686f88878cdf003efba798edb69372872b21
Author: bholmesdev <hey@bholmes.dev>
Date:   Thu Feb 9 12:29:32 2023 -0500

    refactor: remove fallback loader

commit 0540d701ccb33db7a82be861c36dcafec0dbbb81
Author: bholmesdev <hey@bholmes.dev>
Date:   Thu Feb 9 12:26:21 2023 -0500

    fix: markdoc.config loading

commit 575dadf70e7b5aa263e30c8b496a1cceebd31bb4
Author: bholmesdev <hey@bholmes.dev>
Date:   Thu Feb 9 12:16:18 2023 -0500

    oops, forgot to commit untracked

commit 9746a97bc2dfcf63bfd685f541ffbd229ea134ca
Author: bholmesdev <hey@bholmes.dev>
Date:   Thu Feb 9 12:16:02 2023 -0500

    refactor: pass file contents

commit 534a658325cbddbb153bea1c1338d13011eb0e4f
Author: bholmesdev <hey@bholmes.dev>
Date:   Thu Feb 9 12:13:38 2023 -0500

    refactor: move plain md to content entry type

commit 24df79b1475c12ccefaadb2392e9d5911c491872
Author: bholmesdev <hey@bholmes.dev>
Date:   Wed Feb 8 15:51:44 2023 -0500

    wip: move mdx to collection type API

commit cc44e4fa3453353041fdbe9424d96040f93f28a7
Author: bholmesdev <hey@bholmes.dev>
Date:   Wed Feb 8 15:50:52 2023 -0500

    deps: mdx

commit c30c1b3dcf6da3a075c1f07260ae893ef93e07e2
Author: bholmesdev <hey@bholmes.dev>
Date:   Wed Feb 8 10:10:39 2023 -0500

    wip: scaffold content types

commit 2487aedf9deb74a5725ba8393766b68f60b74af8
Author: bholmesdev <hey@bholmes.dev>
Date:   Wed Feb 8 09:53:35 2023 -0500

    feat: move Renderer to markdoc, get Content component!

commit 44faff911b8de6f6da45f195dad0a56a426b076e
Author: bholmesdev <hey@bholmes.dev>
Date:   Wed Feb 8 09:53:06 2023 -0500

    deps: move to @astrojs/markdoc

commit bef26906f3f2f1104b88332778ee219cf062fe88
Author: bholmesdev <hey@bholmes.dev>
Date:   Tue Feb 7 16:01:34 2023 -0500

    feat: addContentEntryType integration hook

commit 508568f5117a56fc4ef14db9d0482cdfcfe5007d
Author: bholmesdev <hey@bholmes.dev>
Date:   Tue Feb 7 16:00:42 2023 -0500

    deps: graymatter

commit cb706020391b4b61f3854b3e9a9d9190a94785c9
Author: bholmesdev <hey@bholmes.dev>
Date:   Tue Feb 7 14:00:27 2023 -0500

    chore: unit tests

commit 545246d15362b8f981f8c315d3b7d0341626eeb8
Author: bholmesdev <hey@bholmes.dev>
Date:   Tue Feb 7 14:00:23 2023 -0500

    wip: get dream API for file loader working

commit 97664e0f862f7f6e0c9ce8478b3bed58432f6426
Author: bholmesdev <hey@bholmes.dev>
Date:   Mon Feb 6 18:09:23 2023 -0500

    wip: play with separate markdoc config

commit c5d8a3336cc9f5dd7b4115b7f86fdb86474ca462
Author: bholmesdev <hey@bholmes.dev>
Date:   Mon Feb 6 17:04:22 2023 -0500

    fix: render attributes to html

commit 82e30a0083b20c85307726027ee7e74df7378632
Author: bholmesdev <hey@bholmes.dev>
Date:   Mon Feb 6 17:04:14 2023 -0500

    deps: stringify-attributes

commit b72ba6167db88d5042eee51d5912d4270417bca5
Author: bholmesdev <hey@bholmes.dev>
Date:   Mon Feb 6 16:33:27 2023 -0500

    fix: component render bug

commit 59f1e5c6f89d2c7457a0b0e0acb838bf945d39bf
Author: bholmesdev <hey@bholmes.dev>
Date:   Mon Feb 6 16:11:15 2023 -0500

    feat: basic Astro renderer in with-markdoc

commit de15a7213d9afbc94dd0e50f713c9a02dc8e90e5
Author: bholmesdev <hey@bholmes.dev>
Date:   Mon Feb 6 16:11:01 2023 -0500

    wip: expose Markdoc from integration

commit 83bfe4441b652a7eb880486785dc2c5eda08e3b3
Author: bholmesdev <hey@bholmes.dev>
Date:   Mon Feb 6 11:21:17 2023 -0500

    feat: get markdoc contents

commit 6f500689a00b8f8c2151254930fda24e0b3e4207
Author: bholmesdev <hey@bholmes.dev>
Date:   Mon Feb 6 11:13:57 2023 -0500

    chore: integration setup
2023-02-16 13:06:33 -05:00
..
src Squashed commit of markdoc-poc 2023-02-16 13:06:33 -05:00
template Squashed commit of markdoc-poc 2023-02-16 13:06:33 -05:00
test Support rehype plugins that inject namespaced attributes 2 (#6253) 2023-02-16 18:53:30 +08:00
CHANGELOG.md [ci] release (#6251) 2023-02-15 22:54:16 +08:00
package.json [ci] release (#6251) 2023-02-15 22:54:16 +08:00
README.md Revert MDX README changes (#6062) 2023-01-31 15:41:22 +01:00
tsconfig.json MDX support (#3706) 2022-06-30 13:09:09 -05:00

@astrojs/mdx 📝

This Astro integration enables the usage of MDX components and allows you to create pages as .mdx files.

Why MDX?

MDX allows you to use variables, JSX expressions and components within Markdown content in Astro. If you have existing content authored in MDX, this integration allows you to bring those files to your Astro project.

Installation

Quick Install

The astro add command-line tool automates the installation for you. Run one of the following commands in a new terminal window. (If you aren't sure which package manager you're using, run the first command.) Then, follow the prompts, and type "y" in the terminal (meaning "yes") for each one.

# Using NPM
npx astro add mdx
# Using Yarn
yarn astro add mdx
# Using PNPM
pnpm astro add mdx

If you run into any issues, feel free to report them to us on GitHub and try the manual installation steps below.

Manual Install

First, install the @astrojs/mdx package using your package manager. If you're using npm or aren't sure, run this in the terminal:

npm install @astrojs/mdx

Then, apply this integration to your astro.config.* file using the integrations property:

astro.config.mjs

import { defineConfig } from 'astro/config';
import mdx from '@astrojs/mdx';

export default defineConfig({
  // ...
  integrations: [mdx()],
});

Editor Integration

VS Code supports Markdown by default. However, for MDX editor support, you may wish to add the following setting in your VSCode config. This ensures authoring MDX files provides a Markdown-like editor experience.

"files.associations": {
    "*.mdx": "markdown"
}

Usage

With the Astro MDX integration, you can add MDX pages to your project by adding .mdx files within your src/pages/ directory. You can also import .mdx files into .astro files.

Astro's MDX integration adds extra features to standard MDX, including Markdown-style frontmatter. This allows you to use most of Astro's built-in Markdown features like a special frontmatter layout property and a property for marking a page as a draft.

See how MDX works in Astro with examples in our Markdown & MDX guide.

Visit the MDX docs to learn about using standard MDX features.

Configuration

Once the MDX integration is installed, no configuration is necessary to use .mdx files in your Astro project.

You can configure how your MDX is rendered with the following options:

Options inherited from Markdown config

All markdown configuration options except drafts can be configured separately in the MDX integration. This includes remark and rehype plugins, syntax highlighting, and more. Options will default to those in your Markdown config (see the extendMarkdownConfig option to modify this).

:::note There is no separate MDX configuration for including pages marked as draft in the build. This Markdown setting will be respected by both Markdown and MDX files and cannot be overridden for MDX files specifically. :::

astro.config.mjs

import { defineConfig } from 'astro/config';
import mdx from '@astrojs/mdx';
import remarkToc from 'remark-toc';
import rehypeMinifyHtml from 'rehype-minify-html';

export default defineConfig({
  integrations: [
    mdx({
      syntaxHighlight: 'shiki',
      shikiConfig: { theme: 'dracula' },
      remarkPlugins: [remarkToc],
      rehypePlugins: [rehypeMinifyHtml],
      remarkRehype: { footnoteLabel: 'Footnotes' },
      gfm: false,
    })
  ]
})

:::caution MDX does not support passing remark and rehype plugins as a string. You should install, import, and apply the plugin function instead. :::

📚 See the Markdown Options reference for a complete list of options.

extendMarkdownConfig

  • Type: boolean
  • Default: true

MDX will extend your project's existing Markdown configuration by default. To override individual options, you can specify their equivalent in your MDX configuration.

For example, say you need to disable GitHub-Flavored Markdown and apply a different set of remark plugins for MDX files. You can apply these options like so, with extendMarkdownConfig enabled by default:

astro.config.mjs

import { defineConfig } from 'astro/config';
import mdx from '@astrojs/mdx';

export default defineConfig({
  markdown: {
    syntaxHighlight: 'prism',
    remarkPlugins: [remarkPlugin1],
    gfm: true,
  },
  integrations: [
    mdx({
      // `syntaxHighlight` inherited from Markdown

      // Markdown `remarkPlugins` ignored,
      // only `remarkPlugin2` applied.
      remarkPlugins: [remarkPlugin2],
      // `gfm` overridden to `false`
      gfm: false,
    })
  ]
});

You may also need to disable markdown config extension in MDX. For this, set extendMarkdownConfig to false:

astro.config.mjs

import { defineConfig } from 'astro/config';
import mdx from '@astrojs/mdx';

export default defineConfig({
  markdown: {
    remarkPlugins: [remarkPlugin1],
  },
  integrations: [
    mdx({
      // Markdown config now ignored
      extendMarkdownConfig: false,
      // No `remarkPlugins` applied
    })
  ]
});

recmaPlugins

These are plugins that modify the output estree directly. This is useful for modifying or injecting JavaScript variables in your MDX files.

We suggest using AST Explorer to play with estree outputs, and trying estree-util-visit for searching across JavaScript nodes.

Examples

Troubleshooting

For help, check out the #support channel on Discord. Our friendly Support Squad members are here to help!

You can also check our Astro Integration Documentation for more on integrations.

Contributing

This package is maintained by Astro's Core team. You're welcome to submit an issue or PR!

Changelog

See CHANGELOG.md for a history of changes to this integration.