Skip to content

Commit 0a2805d

Browse files
sarah11918sarah11918
authored
Merge branch 'main' into edit/injected-frontmatter-new-default
2 parents e221a23 + c065903 commit 0a2805d

File tree

5 files changed

+155
-175
lines changed

5 files changed

+155
-175
lines changed

‎src/pages/en/guides/integrations-guide/mdx.mdx

Lines changed: 70 additions & 87 deletions
Original file line numberDiff line numberDiff line change
@@ -90,117 +90,100 @@ Visit the [MDX docs](https://mdxjs.com/docs/what-is-mdx/) to learn about using s
9090

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

93-
You can extend how your MDX is rendered by adding remark, rehype and recma plugins.
93+
You can configure how your MDX is rendered with the following options:
9494

95-
* [`extendPlugins`](https://github.com/withastro/astro/tree/main/packages/integrations/mdx/#extendplugins)
96-
* [`remarkRehype`](https://github.com/withastro/astro/tree/main/packages/integrations/mdx/#remarkrehype)
97-
* [`remarkPlugins`](https://github.com/withastro/astro/tree/main/packages/integrations/mdx/#remarkplugins)
98-
* [`rehypePlugins`](https://github.com/withastro/astro/tree/main/packages/integrations/mdx/#rehypeplugins)
95+
* [Options inherited from Markdown config](https://github.com/withastro/astro/tree/main/packages/integrations/mdx/#options-inherited-from-markdown-config)
96+
* [`extendMarkdownConfig`](https://github.com/withastro/astro/tree/main/packages/integrations/mdx/#extendmarkdownconfig)
9997
* [`recmaPlugins`](https://github.com/withastro/astro/tree/main/packages/integrations/mdx/#recmaplugins)
10098

101-
### `extendPlugins`
99+
### Options inherited from Markdown config
102100

103-
You can customize how MDX files inherit your project’s existing Markdown configuration using the `extendPlugins` option.
101+
All [`markdown` configuration options](/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](https://github.com/withastro/astro/tree/main/packages/integrations/mdx/#extendmarkdownconfig) to modify this).
104102

105-
#### `markdown` (default)
103+
:::note
104+
There is no separate MDX configuration for [including pages marked as draft in the 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.
105+
:::
106106

107-
Astro's MDX files will inherit all [`markdown` options](/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.
108-
109-
Any additional plugins you apply in your MDX config will be applied *after* your configured Markdown plugins.
110-
111-
#### `astroDefaults`
112-
113-
Astro's MDX files will apply only [Astro's default plugins](https://github.com/withastro/astro/tree/main/packages/integrations/mdx/en/reference/configuration-reference/#markdownextenddefaultplugins), without inheriting the rest of your Markdown config.
114-
115-
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:
116-
117-
```js "extendPlugins: 'astroDefaults'"
118-
// astro.config.mjs
119-
import remarkToc from 'remark-toc';
120-
121-
export default {
122-
markdown: {
123-
remarkPlugins: [/** ignored */]
124-
},
125-
integrations: [mdx({
126-
remarkPlugins: [remarkToc],
127-
// Astro defaults applied
128-
extendPlugins: 'astroDefaults',
129-
})],
130-
}
131-
```
132-
133-
#### `false`
134-
135-
Astro's MDX files will not inherit any [`markdown` options](/en/reference/configuration-reference/#markdown-options), nor will any Astro Markdown defaults be applied:
136-
137-
```js "extendPlugins: false"
107+
```ts
138108
// astro.config.mjs
109+
import { defineConfig } from 'astro/config';
110+
import mdx from '@astrojs/mdx';
139111
import remarkToc from 'remark-toc';
112+
import rehypeMinifyHtml from 'rehype-minify-html';
140113

141-
export default {
142-
integrations: [mdx({
143-
remarkPlugins: [remarkToc],
144-
// Astro defaults not applied
145-
extendPlugins: false,
146-
})],
147-
}
114+
export default defineConfig({
115+
integrations: [
116+
mdx({
117+
syntaxHighlight: 'shiki',
118+
shikiConfig: { theme: 'dracula' },
119+
remarkPlugins: [remarkToc],
120+
rehypePlugins: [rehypeMinifyHtml],
121+
remarkRehype: { footnoteLabel: 'Footnotes' },
122+
gfm: false,
123+
})
124+
]
125+
})
148126
```
149127

150-
### `remarkRehype`
151-
152-
Markdown content is transformed into HTML through remark-rehype which has [a number of options](https://github.com/remarkjs/remark-rehype#options).
128+
:::caution
129+
MDX does not support passing remark and rehype plugins as a string. You should install, import, and apply the plugin function instead.
130+
:::
153131

154-
You can set remark-rehype options in your config file:
155-
156-
```js
157-
// astro.config.mjs
158-
export default {
159-
integrations: [mdx({
160-
remarkRehype: {
161-
footnoteLabel: 'Catatan kaki',
162-
footnoteBackLabel: 'Kembali ke konten',
163-
},
164-
})],
165-
};
166-
```
132+
📚 See the [Markdown Options reference](/en/reference/configuration-reference/#markdown-options) for a complete list of options.
167133

168-
This inherits the configuration of [`markdown.remarkRehype`](/en/reference/configuration-reference/#markdownremarkrehype). This behavior can be changed by configuring `extendPlugins`.
134+
### `extendMarkdownConfig`
169135

170-
### `remarkPlugins`
136+
* **Type:** `boolean`
137+
* **Default:** `true`
171138

172-
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.
139+
MDX will extend [your project's existing Markdown configuration](/en/reference/configuration-reference/#markdown-options) by default. To override individual options, you can specify their equivalent in your MDX configuration.
173140

174-
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](https://github.com/withastro/astro/tree/main/packages/integrations/mdx/#extendplugins).
141+
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:
175142

176-
```js
143+
```ts
177144
// astro.config.mjs
178-
import remarkToc from 'remark-toc';
145+
import { defineConfig } from 'astro/config';
146+
import mdx from '@astrojs/mdx';
179147

180-
export default {
181-
integrations: [mdx({
182-
remarkPlugins: [remarkToc],
183-
})],
184-
}
148+
export default defineConfig({
149+
markdown: {
150+
syntaxHighlight: 'prism',
151+
remarkPlugins: [remarkPlugin1],
152+
gfm: true,
153+
},
154+
integrations: [
155+
mdx({
156+
// `syntaxHighlight` inherited from Markdown
157+
158+
// Markdown `remarkPlugins` ignored,
159+
// only `remarkPlugin2` applied.
160+
remarkPlugins: [remarkPlugin2],
161+
// `gfm` overridden to `false`
162+
gfm: false,
163+
})
164+
]
165+
});
185166
```
186167

187-
### `rehypePlugins`
168+
You may also need to disable `markdown` config extension in MDX. For this, set `extendMarkdownConfig` to `false`:
188169

189-
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.
190-
191-
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).
192-
193-
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](https://github.com/withastro/astro/tree/main/packages/integrations/mdx/#extendplugins).
194-
195-
```js
170+
```ts
196171
// astro.config.mjs
197-
import rehypeAccessibleEmojis from 'rehype-accessible-emojis';
172+
import { defineConfig } from 'astro/config';
173+
import mdx from '@astrojs/mdx';
198174

199-
export default {
200-
integrations: [mdx({
201-
rehypePlugins: [rehypeAccessibleEmojis],
202-
})],
203-
}
175+
export default defineConfig({
176+
markdown: {
177+
remarkPlugins: [remarkPlugin1],
178+
},
179+
integrations: [
180+
mdx({
181+
// Markdown config now ignored
182+
extendMarkdownConfig: false,
183+
// No `remarkPlugins` applied
184+
})
185+
]
186+
});
204187
```
205188

206189
### `recmaPlugins`

‎src/pages/en/guides/markdown-content.mdx

Lines changed: 55 additions & 17 deletions
Original file line numberDiff line numberDiff line change
@@ -422,7 +422,7 @@ Custom components defined and exported in an MDX file must be imported and then
422422

423423
Markdown support in Astro is powered by [remark](https://remark.js.org/), a powerful parsing and processing tool with an active ecosystem. Other Markdown parsers like Pandoc and markdown-it are not currently supported.
424424

425-
Astro applies the [GitHub-flavored Markdown](https://github.com/remarkjs/remark-gfm) and [Smartypants](https://github.com/silvenon/remark-smartypants) plugins by default. This brings some niceties like generating clickable links from text and formatting quotes for readability.
425+
Astro applies the [GitHub-flavored Markdown](https://github.com/remarkjs/remark-gfm) plugin by default. This brings some niceties like generating clickable links from text.
426426

427427
You can customize how remark parses your Markdown in `astro.config.mjs`. See the full list of [Markdown configuration options](/en/reference/configuration-reference/#markdown-options).
428428

@@ -432,15 +432,7 @@ Astro supports adding third-party [remark](https://github.com/remarkjs/remark) a
432432

433433
We encourage you to browse [awesome-remark](https://github.com/remarkjs/awesome-remark) and [awesome-rehype](https://github.com/rehypejs/awesome-rehype) for popular plugins! See each plugin's own README for specific installation instructions.
434434

435-
:::tip
436-
When adding your own plugins, Astro's default plugins are removed. You can preserve these defaults with the [`markdown.extendDefaultPlugins` flag](/en/reference/configuration-reference/#markdownextenddefaultplugins).
437-
:::
438-
439-
By default, Astro's MDX integration inherits all remark and rehype plugins from your Astro config `markdown` options. To change this behavior, configure [`extendPlugins`](/en/guides/integrations-guide/mdx/#extendplugins) in your `mdx` integration.
440-
441-
Any additional plugins you apply in your MDX config will be applied *after* your configured Markdown plugins, and will apply only to `.mdx` files.
442-
443-
This example applies [`remark-toc`](https://github.com/remarkjs/remark-toc) to Markdown *and* MDX, and [`rehype-accessible-emojis`](https://www.npmjs.com/package/rehype-accessible-emojis) to MDX only, while preserving Astro's default plugins:
435+
This example applies [`remark-toc`](https://github.com/remarkjs/remark-toc) and [`rehype-accessible-emojis`](https://www.npmjs.com/package/rehype-accessible-emojis) to both Markdown and MDX files:
444436

445437
```js title="astro.config.mjs"
446438
import { defineConfig } from 'astro/config';
@@ -450,14 +442,8 @@ import { rehypeAccessibleEmojis } from 'rehype-accessible-emojis';
450442
export default {
451443
markdown: {
452444
// Applied to .md and .mdx files
453-
remarkPlugins: [remarkToc],
454-
// Preserves remark-gfm and remark-smartypants
455-
extendDefaultPlugins: true,
445+
remarkPlugins: [remarkToc, rehypeAccessibleEmojis],
456446
},
457-
integrations: [mdx({
458-
// Applied to .mdx files only
459-
rehypePlugins: [rehypeAccessibleEmojis],
460-
})],
461447
}
462448
```
463449

@@ -590,6 +576,58 @@ const { minutesRead } = Astro.props.frontmatter;
590576
</html>
591577
```
592578

579+
### Extending Markdown config from MDX
580+
581+
Astro's MDX integration will extend [your project's existing Markdown configuration](/en/reference/configuration-reference/#markdown-options) by default. To override individual options, you can specify their equivalent in your MDX configuration.
582+
583+
The following example disables GitHub-Flavored Markdown and applies a different set of remark plugins for MDX files:
584+
585+
```ts
586+
// astro.config.mjs
587+
import { defineConfig } froAm 'astro/config';
588+
import mdx from '@astrojs/mdx';
589+
590+
export default defineConfig({
591+
markdown: {
592+
syntaxHighlight: 'prism',
593+
remarkPlugins: [remarkPlugin1],
594+
gfm: true,
595+
},
596+
integrations: [
597+
mdx({
598+
// `syntaxHighlight` inherited from Markdown
599+
600+
// Markdown `remarkPlugins` ignored,
601+
// only `remarkPlugin2` applied.
602+
remarkPlugins: [remarkPlugin2],
603+
// `gfm` overridden to `false`
604+
gfm: false,
605+
})
606+
]
607+
});
608+
```
609+
610+
To avoid extending your Markdown config from MDX, set [the `extendMarkdownConfig` option](/en/guides/integrations-guide/mdx/#extendmarkdownconfig) (enabled by default) to `false`:
611+
612+
```ts
613+
// astro.config.mjs
614+
import { defineConfig } from 'astro/config';
615+
import mdx from '@astrojs/mdx';
616+
617+
export default defineConfig({
618+
markdown: {
619+
remarkPlugins: [remarkPlugin],
620+
},
621+
integrations: [
622+
mdx({
623+
// Markdown config now ignored
624+
extendMarkdownConfig: false,
625+
// No `remarkPlugins` applied
626+
})
627+
]
628+
});
629+
```
630+
593631
### Syntax Highlighting
594632

595633
Astro comes with built-in support for [Shiki](https://shiki.matsu.io/) and [Prism](https://prismjs.com/). This provides syntax highlighting for:

0 commit comments

Comments
 (0)