You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Refine Markdown and MDX configuration options for ease-of-use.
8
+
9
+
#### Markdown
10
+
11
+
-**Remove `remark-smartypants`** from Astro's default Markdown plugins.
12
+
-**Replace the `extendDefaultPlugins` option** with a simplified `gfm` boolean. This is enabled by default, and can be disabled to remove GitHub-Flavored Markdown.
13
+
- Ensure GitHub-Flavored Markdown is applied whether or not custom `remarkPlugins` or `rehypePlugins` are configured. If you want to apply custom plugins _and_ remove GFM, manually set `gfm: false` in your config.
14
+
15
+
#### MDX
16
+
17
+
- Support _all_ Markdown configuration options (except `drafts`) from your MDX integration config. This includes `syntaxHighlighting` and `shikiConfig` options to further customize the MDX renderer.
18
+
- Simplify `extendDefaults` to an `extendMarkdownConfig` option. MDX options will default to their equivalent in your Markdown config. By setting `extendMarkdownConfig` to false, you can "eject" to set your own syntax highlighting, plugins, and more.
19
+
20
+
#### Migration
21
+
22
+
To preserve your existing Markdown and MDX setup, you may need some configuration changes:
23
+
24
+
##### Smartypants manual installation
25
+
26
+
[Smartypants](https://github.com/silvenon/remark-smartypants) has been removed from Astro's default setup. If you rely on this plugin, [install `remark-smartypants`](https://github.com/silvenon/remark-smartypants#installing) and apply to your `astro.config.*`:
27
+
28
+
```diff
29
+
// astro.config.mjs
30
+
import { defineConfig } from 'astro/config';
31
+
+ import smartypants from 'remark-smartypants';
32
+
33
+
export default defineConfig({
34
+
markdown: {
35
+
+ remarkPlugins: [smartypants],
36
+
}
37
+
});
38
+
```
39
+
40
+
##### Migrate `extendDefaultPlugins` to `gfm`
41
+
42
+
You may have disabled Astro's built-in plugins (GitHub-Flavored Markdown and Smartypants) with the `extendDefaultPlugins` option. Since Smartypants has been removed, this has been renamed to `gfm`.
43
+
44
+
```diff
45
+
// astro.config.mjs
46
+
import { defineConfig } from 'astro/config';
47
+
48
+
export default defineConfig({
49
+
markdown: {
50
+
- extendDefaultPlugins: false,
51
+
+ gfm: false,
52
+
}
53
+
});
54
+
```
55
+
56
+
57
+
Additionally, applying remark and rehype plugins **no longer disables**`gfm`. You will need to opt-out manually by setting `gfm` to `false`.
58
+
59
+
##### Migrate MDX's `extendPlugins` to `extendMarkdownConfig`
60
+
61
+
You may have used the `extendPlugins` option to manage plugin defaults in MDX. This has been replaced by 2 flags:
62
+
-`extendMarkdownConfig` (`true` by default) to toggle Markdown config inheritance. This replaces the `extendPlugins: 'markdown'` option.
63
+
-`gfm` (`true` by default) to toggle GitHub-Flavored Markdown in MDX. This replaces the `extendPlugins: 'defaults'` option.
* Pass [remark plugins](https://github.com/remarkjs/remark) to customize how your Markdown is built. You can import and apply the plugin function (recommended), or pass the plugin name as a string.
736
736
*
737
-
* :::caution
738
-
* Providing a list of plugins will **remove** our default plugins. To preserve these defaults, see the [`extendDefaultPlugins`](#markdownextenddefaultplugins) flag.
* Pass [rehype plugins](https://github.com/remarkjs/remark-rehype) to customize how your Markdown's output HTML is processed. You can import and apply the plugin function (recommended), or pass the plugin name as a string.
757
753
*
758
-
* :::caution
759
-
* Providing a list of plugins will **remove** our default plugins. To preserve these defaults, see the [`extendDefaultPlugins`](#markdownextenddefaultplugins) flag.
* Astro applies the [GitHub-flavored Markdown](https://github.com/remarkjs/remark-gfm) and [Smartypants](https://github.com/silvenon/remark-smartypants) plugins by default. When adding your own remark or rehype plugins, you can preserve these defaults by setting the `extendDefaultPlugins` flag to `true`:
770
+
* Astro uses [GitHub-flavored Markdown](https://github.com/remarkjs/remark-gfm) by default. To disable this, set the `gfm` flag to `false`:
Copy file name to clipboardExpand all lines: packages/integrations/mdx/README.md
+70-86Lines changed: 70 additions & 86 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -78,116 +78,100 @@ Visit the [MDX docs](https://mdxjs.com/docs/what-is-mdx/) to learn about using s
78
78
79
79
Once the MDX integration is installed, no configuration is necessary to use `.mdx` files in your Astro project.
80
80
81
-
You can extend how your MDX is rendered by adding remark, rehype and recma plugins.
81
+
You can configure how your MDX is rendered with the following options:
82
82
83
-
-[`extendPlugins`](#extendplugins)
84
-
-[`remarkRehype`](#remarkrehype)
85
-
-[`remarkPlugins`](#remarkplugins)
86
-
-[`rehypePlugins`](#rehypeplugins)
83
+
-[Options inherited from Markdown config](#options-inherited-from-markdown-config)
84
+
-[`extendMarkdownConfig`](#extendmarkdownconfig)
87
85
-[`recmaPlugins`](#recmaplugins)
88
86
89
-
### `extendPlugins`
87
+
### Options inherited from Markdown config
90
88
91
-
You can customize how MDX files inherit your project’s existing Markdown configuration using the `extendPlugins` option.
89
+
All [`markdown` configuration options](https://docs.astro.build/en/reference/configuration-reference/#markdown-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](#extendmarkdownconfig) to modify this).
92
90
93
-
#### `markdown` (default)
91
+
:::note
92
+
There is no separate MDX configuration for [including pages marked as draft in the build](https://docs.astro.build/en/reference/configuration-reference/#markdowndrafts). This Markdown setting will be respected by both Markdown and MDX files and cannot be overriden for MDX files specifically.
93
+
:::
94
94
95
-
Astro's MDX files will inherit all [`markdown` options](https://docs.astro.build/en/reference/configuration-reference/#markdown-options) in your Astro configuration file, which includes the [GitHub-Flavored Markdown](https://github.com/remarkjs/remark-gfm) and [Smartypants](https://github.com/silvenon/remark-smartypants) plugins by default.
96
-
97
-
Any additional plugins you apply in your MDX config will be applied *after* your configured Markdown plugins.
98
-
99
-
#### `astroDefaults`
100
-
101
-
Astro's MDX files will apply only [Astro's default plugins](/en/reference/configuration-reference/#markdownextenddefaultplugins), without inheriting the rest of your Markdown config.
102
-
103
-
This example will apply the default [GitHub-Flavored Markdown](https://github.com/remarkjs/remark-gfm) and [Smartypants](https://github.com/silvenon/remark-smartypants) plugins alongside [`remark-toc`](https://github.com/remarkjs/remark-toc) to your MDX files, while ignoring any `markdown.remarkPlugins` configuration:
104
-
105
-
```js "extendPlugins: 'astroDefaults'"
95
+
```ts
106
96
// astro.config.mjs
97
+
import { defineConfig } from'astro/config';
98
+
importmdxfrom'@astrojs/mdx';
107
99
importremarkTocfrom'remark-toc';
100
+
importrehypeMinifyHtmlfrom'rehype-minify-html';
108
101
109
-
exportdefault {
110
-
markdown: {
111
-
remarkPlugins: [/** ignored */]
112
-
},
113
-
integrations: [mdx({
114
-
remarkPlugins: [remarkToc],
115
-
// Astro defaults applied
116
-
extendPlugins:'astroDefaults',
117
-
})],
118
-
}
102
+
exportdefaultdefineConfig({
103
+
integrations: [
104
+
mdx({
105
+
syntaxHighlight: 'shiki',
106
+
shikiConfig: { theme: 'dracula' },
107
+
remarkPlugins: [remarkToc],
108
+
rehypePlugins: [rehypeMinifyHtml],
109
+
remarkRehype: { footnoteLabel: 'Footnotes' },
110
+
gfm: false,
111
+
})
112
+
]
113
+
})
119
114
```
120
115
121
-
#### `false`
116
+
:::caution
117
+
MDX does not support passing remark and rehype plugins as a string. You should install, import, and apply the plugin function instead.
118
+
:::
122
119
123
-
Astro's MDX files will not inherit any [`markdown` options](https://docs.astro.build/en/reference/configuration-reference/#markdown-options), nor will any Astro Markdown defaults be applied:
120
+
📚 See the [Markdown Options reference](https://docs.astro.build/en/reference/configuration-reference/#markdown-options) for a complete list of options.
124
121
125
-
```js "extendPlugins: false"
126
-
// astro.config.mjs
127
-
importremarkTocfrom'remark-toc';
128
-
129
-
exportdefault {
130
-
integrations: [mdx({
131
-
remarkPlugins: [remarkToc],
132
-
// Astro defaults not applied
133
-
extendPlugins:false,
134
-
})],
135
-
}
136
-
```
122
+
### `extendMarkdownConfig`
137
123
138
-
### `remarkRehype`
124
+
-**Type:**`boolean`
125
+
-**Default:**`true`
139
126
140
-
Markdown content is transformed into HTML through remark-rehype which has [a number of options](https://github.com/remarkjs/remark-rehype#options).
127
+
MDX will extend [your project's existing Markdown configuration](https://docs.astro.build/en/reference/configuration-reference/#markdown-options) by default. To override individual options, you can specify their equivalent in your MDX configuration.
141
128
142
-
You can set remark-rehype options in your config file:
129
+
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:
143
130
144
-
```js
131
+
```ts
145
132
// astro.config.mjs
146
-
exportdefault {
147
-
integrations: [mdx({
148
-
remarkRehype: {
149
-
footnoteLabel:'Catatan kaki',
150
-
footnoteBackLabel:'Kembali ke konten',
151
-
},
152
-
})],
153
-
};
154
-
```
155
-
This inherits the configuration of [`markdown.remarkRehype`](https://docs.astro.build/en/reference/configuration-reference/#markdownremarkrehype). This behavior can be changed by configuring `extendPlugins`.
156
-
157
-
### `remarkPlugins`
158
-
159
-
Browse [awesome-remark](https://github.com/remarkjs/awesome-remark) for a full curated list of [remark plugins](https://github.com/remarkjs/remark/blob/main/doc/plugins.md) to extend your Markdown's capabilities.
160
-
161
-
This example applies the [`remark-toc`](https://github.com/remarkjs/remark-toc) plugin to `.mdx` files. To customize plugin inheritance from your Markdown config or Astro's defaults, [see the `extendPlugins` option](#extendplugins).
162
-
163
-
```js
164
-
// astro.config.mjs
165
-
importremarkTocfrom'remark-toc';
133
+
import { defineConfig } from'astro/config';
134
+
importmdxfrom'@astrojs/mdx';
166
135
167
-
exportdefault {
168
-
integrations: [mdx({
169
-
remarkPlugins: [remarkToc],
170
-
})],
171
-
}
136
+
exportdefaultdefineConfig({
137
+
markdown: {
138
+
syntaxHighlight: 'prism',
139
+
remarkPlugins: [remarkPlugin1],
140
+
gfm: true,
141
+
},
142
+
integrations: [
143
+
mdx({
144
+
// `syntaxHighlight` inherited from Markdown
145
+
146
+
// Markdown `remarkPlugins` ignored,
147
+
// only `remarkPlugin2` applied.
148
+
remarkPlugins: [remarkPlugin2],
149
+
// `gfm` overridden to `false`
150
+
gfm: false,
151
+
})
152
+
]
153
+
});
172
154
```
173
155
174
-
### `rehypePlugins`
175
-
176
-
Browse [awesome-rehype](https://github.com/rehypejs/awesome-rehype) for a full curated list of [Rehype plugins](https://github.com/rehypejs/rehype/blob/main/doc/plugins.md) to transform the HTML that your Markdown generates.
156
+
You may also need to disable `markdown` config extension in MDX. For this, set `extendMarkdownConfig` to `false`:
177
157
178
-
We apply our own (non-removable) [`collect-headings`](https://github.com/withastro/astro/blob/main/packages/integrations/mdx/src/rehype-collect-headings.ts) plugin. This applies IDs to all headings (i.e. `h1 -> h6`) in your MDX files to [link to headings via anchor tags](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/a#linking_to_an_element_on_the_same_page).
179
-
180
-
This example applies the [`rehype-accessible-emojis`](https://www.npmjs.com/package/rehype-accessible-emojis) plugin to `.mdx` files. To customize plugin inheritance from your Markdown config or Astro's defaults, [see the `extendPlugins` option](#extendplugins).
0 commit comments