Remark and rehype plugins (#562)

* remark plugins

* remove unused dependency

* enable codeblocks

* backward compatibility with remark-code-titles

* add support for rehype plugins

* add proper types for plugins

* fixes after review

- connect plugins by name
- make plugins configurable
- connect gfm and footnotes if no plugins provided from config
- add more plugins to example

* update and rename example

* add documentation for markdown plugins

* chore: rename with-markdown-plugins example

* chore: restructure dependencies

* feat: add back smartypants, fix mdx expressions

* chore: remove log

* test: add markdown plugin tests

* chore: add changeset

* docs: update markdown doc

Co-authored-by: Nate Moore <nate@skypack.dev>

1 files changed, 43 insertions, 4 deletions

diff --git a/docs/guides/markdown-content.md b/docs/guides/markdown-content.md
index b00312034..00dbd7f87 100644
--- a/docs/guides/markdown-content.md
+++ b/docs/guides/markdown-content.md
@@ -4,12 +4,51 @@ title: Markdown Content
 ---
 
 Astro comes with out-of-the-box Markdown support powered by the expansive [remark](https://remark.js.org/) ecosystem.
+## Remark and Rehype Plugins
+
+In addition to [custom components inside the `<Markdown>` component](#markdown-component), Astro comes with [GitHub-flavored Markdown](https://github.github.com/gfm/) support, [Footnotes](https://github.com/remarkjs/remark-footnotes) syntax, [Smartypants](https://github.com/silvenon/remark-smartypants), and syntax highlighting via [Prism](https://prismjs.com/) pre-enabled.
+
+Also, Astro supports third-party plugins for Markdown. You can provide your plugins in `astro.config.mjs`.
+
+> **Note** Enabling custom `remarkPlugins` or `rehypePlugins` removes Astro's built-in support for [GitHub-flavored Markdown](https://github.github.com/gfm/) support, [Footnotes](https://github.com/remarkjs/remark-footnotes) syntax, [Smartypants](https://github.com/silvenon/remark-smartypants). You must explicitly add these plugins to your `astro.config.mjs` file, if desired.
+
+## Add a markdown plugin in Astro
+
+If you want to add a plugin, you need to install the npm package dependency in your project and then update the `markdownOptions.remarkPlugins` or `markdownOptions.rehypePlugins` depends on what plugin you want to have:
+
+```js
+// astro.config.js
+export default {
+  markdownOptions: {
+    remarkPlugins: [
+      // Add a Remark plugin that you want to enable for your project.
+      // If you need to provide options for the plugin, you can use an array and put the options as the second item.
+      // 'remark-slug',
+      // ['remark-autolink-headings', { behavior: 'prepend'}],
+    ]
+    rehypePlugins: [
+      // Add a Rehype plugin that you want to enable for your project.
+      // If you need to provide options for the plugin, you can use an array and put the options as the second item.
+      // 'rehype-slug',
+      // ['rehype-autolink-headings', { behavior: 'prepend'}],
+    ]
+  },
+};
+```
 
-### Remark Plugins
-
-**This is the first draft of Markdown support!** While we plan to support user-provided `remark` plugins soon, our hope is that you won't need `remark` plugins at all!
+You can provide names of the plugins as well as import them:
 
-In addition to [custom components inside the `<Markdown>` component](https://github.com/snowpackjs/astro/blob/main/docs/markdown.md#markdown-component), Astro comes with [Github-flavored Markdown](https://github.github.com/gfm/) support, [Footnotes](https://github.com/remarkjs/remark-footnotes) syntax, [Smartypants](https://github.com/silvenon/remark-smartypants), and syntax highlighting via [Prism](https://prismjs.com/) pre-enabled. These features are likely to be configurable in the future.
+```js
+// astro.config.js
+export default {
+  markdownOptions: {
+    remarkPlugins: [
+      import('remark-slug'),
+      [import('remark-autolink-headings'), { behavior: 'prepend' }],
+    ],
+  },
+};
+```
 
 ### Markdown Pages