diff options
Diffstat (limited to 'packages/integrations/mdx/README.md')
| -rw-r--r-- | packages/integrations/mdx/README.md | 156 |
1 files changed, 70 insertions, 86 deletions
diff --git a/packages/integrations/mdx/README.md b/packages/integrations/mdx/README.md index 6b62dc308..8267d80de 100644 --- a/packages/integrations/mdx/README.md +++ b/packages/integrations/mdx/README.md @@ -78,116 +78,100 @@ Visit the [MDX docs](https://mdxjs.com/docs/what-is-mdx/) to learn about using s Once the MDX integration is installed, no configuration is necessary to use `.mdx` files in your Astro project. -You can extend how your MDX is rendered by adding remark, rehype and recma plugins. +You can configure how your MDX is rendered with the following options: -- [`extendPlugins`](#extendplugins) -- [`remarkRehype`](#remarkrehype) -- [`remarkPlugins`](#remarkplugins) -- [`rehypePlugins`](#rehypeplugins) +- [Options inherited from Markdown config](#options-inherited-from-markdown-config) +- [`extendMarkdownConfig`](#extendmarkdownconfig) - [`recmaPlugins`](#recmaplugins) -### `extendPlugins` +### Options inherited from Markdown config -You can customize how MDX files inherit your project’s existing Markdown configuration using the `extendPlugins` option. +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). -#### `markdown` (default) +:::note +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. +::: -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. - -Any additional plugins you apply in your MDX config will be applied *after* your configured Markdown plugins. - -#### `astroDefaults` - -Astro's MDX files will apply only [Astro's default plugins](/en/reference/configuration-reference/#markdownextenddefaultplugins), without inheriting the rest of your Markdown config. - -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: - -```js "extendPlugins: 'astroDefaults'" +```ts // 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 { - markdown: { - remarkPlugins: [/** ignored */] - }, - integrations: [mdx({ - remarkPlugins: [remarkToc], - // Astro defaults applied - extendPlugins: 'astroDefaults', - })], -} +export default defineConfig({ + integrations: [ + mdx({ + syntaxHighlight: 'shiki', + shikiConfig: { theme: 'dracula' }, + remarkPlugins: [remarkToc], + rehypePlugins: [rehypeMinifyHtml], + remarkRehype: { footnoteLabel: 'Footnotes' }, + gfm: false, + }) + ] +}) ``` -#### `false` +:::caution +MDX does not support passing remark and rehype plugins as a string. You should install, import, and apply the plugin function instead. +::: -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: +📚 See the [Markdown Options reference](https://docs.astro.build/en/reference/configuration-reference/#markdown-options) for a complete list of options. -```js "extendPlugins: false" -// astro.config.mjs -import remarkToc from 'remark-toc'; - -export default { - integrations: [mdx({ - remarkPlugins: [remarkToc], - // Astro defaults not applied - extendPlugins: false, - })], -} -``` +### `extendMarkdownConfig` -### `remarkRehype` +- **Type:** `boolean` +- **Default:** `true` -Markdown content is transformed into HTML through remark-rehype which has [a number of options](https://github.com/remarkjs/remark-rehype#options). +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. -You can set remark-rehype options in your config file: +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: -```js +```ts // astro.config.mjs -export default { - integrations: [mdx({ - remarkRehype: { - footnoteLabel: 'Catatan kaki', - footnoteBackLabel: 'Kembali ke konten', - }, - })], -}; -``` -This inherits the configuration of [`markdown.remarkRehype`](https://docs.astro.build/en/reference/configuration-reference/#markdownremarkrehype). This behavior can be changed by configuring `extendPlugins`. - -### `remarkPlugins` - -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. - -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). - -```js -// astro.config.mjs -import remarkToc from 'remark-toc'; +import { defineConfig } from 'astro/config'; +import mdx from '@astrojs/mdx'; -export default { - integrations: [mdx({ - remarkPlugins: [remarkToc], - })], -} +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, + }) + ] +}); ``` -### `rehypePlugins` - - 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. +You may also need to disable `markdown` config extension in MDX. For this, set `extendMarkdownConfig` to `false`: -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). - -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). - -```js +```ts // astro.config.mjs -import rehypeAccessibleEmojis from 'rehype-accessible-emojis'; +import { defineConfig } from 'astro/config'; +import mdx from '@astrojs/mdx'; -export default { - integrations: [mdx({ - rehypePlugins: [rehypeAccessibleEmojis], - })], -} +export default defineConfig({ + markdown: { + remarkPlugins: [remarkPlugin1], + }, + integrations: [ + mdx({ + // Markdown config now ignored + extendMarkdownConfig: false, + // No `remarkPlugins` applied + }) + ] +}); ``` ### `recmaPlugins` |