Skip to content

Commit

Permalink
Merge branch 'main' into edit/injected-frontmatter-new-default
Browse files Browse the repository at this point in the history
  • Loading branch information
@sarah11918
sarah11918 authored Jan 3, 2023
2 parents e221a23 + c065903 commit 0a2805d
Show file tree
Hide file tree
Showing 5 changed files with 155 additions and 175 deletions.
157 changes: 70 additions & 87 deletions src/pages/en/guides/integrations-guide/mdx.mdx
View file
Original file line number Diff line number Diff line change
Expand Up @@ -90,117 +90,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`](https://github.com/withastro/astro/tree/main/packages/integrations/mdx/#extendplugins)
* [`remarkRehype`](https://github.com/withastro/astro/tree/main/packages/integrations/mdx/#remarkrehype)
* [`remarkPlugins`](https://github.com/withastro/astro/tree/main/packages/integrations/mdx/#remarkplugins)
* [`rehypePlugins`](https://github.com/withastro/astro/tree/main/packages/integrations/mdx/#rehypeplugins)
* [Options inherited from Markdown config](https://github.com/withastro/astro/tree/main/packages/integrations/mdx/#options-inherited-from-markdown-config)
* [`extendMarkdownConfig`](https://github.com/withastro/astro/tree/main/packages/integrations/mdx/#extendmarkdownconfig)
* [`recmaPlugins`](https://github.com/withastro/astro/tree/main/packages/integrations/mdx/#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](/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).

#### `markdown` (default)
:::note
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.
:::

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.

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](https://github.com/withastro/astro/tree/main/packages/integrations/mdx/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'"
// astro.config.mjs
import remarkToc from 'remark-toc';

export default {
markdown: {
remarkPlugins: [/** ignored */]
},
integrations: [mdx({
remarkPlugins: [remarkToc],
// Astro defaults applied
extendPlugins: 'astroDefaults',
})],
}
```

#### `false`

Astro's MDX files will not inherit any [`markdown` options](/en/reference/configuration-reference/#markdown-options), nor will any Astro Markdown defaults be applied:

```js "extendPlugins: false"
```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 {
integrations: [mdx({
remarkPlugins: [remarkToc],
// Astro defaults not applied
extendPlugins: false,
})],
}
export default defineConfig({
integrations: [
mdx({
syntaxHighlight: 'shiki',
shikiConfig: { theme: 'dracula' },
remarkPlugins: [remarkToc],
rehypePlugins: [rehypeMinifyHtml],
remarkRehype: { footnoteLabel: 'Footnotes' },
gfm: false,
})
]
})
```

### `remarkRehype`

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

You can set remark-rehype options in your config file:

```js
// astro.config.mjs
export default {
integrations: [mdx({
remarkRehype: {
footnoteLabel: 'Catatan kaki',
footnoteBackLabel: 'Kembali ke konten',
},
})],
};
```
📚 See the [Markdown Options reference](/en/reference/configuration-reference/#markdown-options) for a complete list of options.

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

### `remarkPlugins`
* **Type:** `boolean`
* **Default:** `true`

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

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).
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
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`
You may also need to disable `markdown` config extension in MDX. For this, set `extendMarkdownConfig` to `false`:

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.

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](https://github.com/withastro/astro/tree/main/packages/integrations/mdx/#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`
Expand Down
72 changes: 55 additions & 17 deletions src/pages/en/guides/markdown-content.mdx
View file
Original file line number Diff line number Diff line change
Expand Up @@ -422,7 +422,7 @@ Custom components defined and exported in an MDX file must be imported and then

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.

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

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

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

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.

:::tip
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).
:::

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.

Any additional plugins you apply in your MDX config will be applied *after* your configured Markdown plugins, and will apply only to `.mdx` files.

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

```js title="astro.config.mjs"
import { defineConfig } from 'astro/config';
Expand All @@ -450,14 +442,8 @@ import { rehypeAccessibleEmojis } from 'rehype-accessible-emojis';
export default {
markdown: {
// Applied to .md and .mdx files
remarkPlugins: [remarkToc],
// Preserves remark-gfm and remark-smartypants
extendDefaultPlugins: true,
remarkPlugins: [remarkToc, rehypeAccessibleEmojis],
},
integrations: [mdx({
// Applied to .mdx files only
rehypePlugins: [rehypeAccessibleEmojis],
})],
}
```

Expand Down Expand Up @@ -590,6 +576,58 @@ const { minutesRead } = Astro.props.frontmatter;
</html>
```

### Extending Markdown config from MDX

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.

The following example disables GitHub-Flavored Markdown and applies a different set of remark plugins for MDX files:

```ts
// astro.config.mjs
import { defineConfig } froAm '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,
})
]
});
```

To avoid extending your Markdown config from MDX, set [the `extendMarkdownConfig` option](/en/guides/integrations-guide/mdx/#extendmarkdownconfig) (enabled by default) to `false`:

```ts
// astro.config.mjs
import { defineConfig } from 'astro/config';
import mdx from '@astrojs/mdx';

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

### Syntax Highlighting

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

0 comments on commit 0a2805d

Please sign in to comment.