Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

docs: elaborate on the usage of MDX plugins #5766

Merged
merged 11 commits into from
Oct 29, 2021
Original file line number Diff line number Diff line change
Expand Up @@ -5,9 +5,15 @@ description: Using MDX plugins to expand Docusaurus Markdown functionalities
slug: /markdown-features/plugins
---

You can expand the MDX functionalities, using plugins.
The fragment files written in Docusaurus are using the MDX format see [this link](https://mdxjs.com/getting-started/) for more details about MDX. MDX itself can be easily extended with additional capabilities of translating the input text into HTML. Docusaurus content plugins support out of the box both [Remark](https://github.com/remarkjs/remark) and [Rehype](https://github.com/rehypejs/rehype) plugins that work with MDX.
Josh-Cena marked this conversation as resolved.
Show resolved Hide resolved

Docusaurus content plugins support both [Remark](https://github.com/remarkjs/remark) and [Rehype](https://github.com/rehypejs/rehype) plugins that work with MDX.
However sometimes it is not enough and you might want to use some advanced features as provided in [this extensive list of plugins for remark](https://github.com/rehypejs/rehype/blob/main/doc/plugins.md#list-of-plugins) or [another one for rehype](https://github.com/rehypejs/rehype/blob/main/doc/plugins.md#list-of-plugins). The plugins on this list usually provide easier, shorter or more specialized ways of creating the HTML content. There are really useful if you want to for instance: override the defaults in terms of markdown to HTML conversion, add some new checks or support some specialized syntax specific to your content (like mathml support or picturing graphs or sheet music generation).
Josh-Cena marked this conversation as resolved.
Show resolved Hide resolved

## What are remark and rehype

Remark is a markdown processor used to parse it into the structured tree that can be used programmatically to transform it or compile it into output format. Complete introduction to remark can be found [here](https://github.com/remarkjs/remark).

Rehype is a similar suite of plugins working on the HTML files, capable of transforming, minifying, it. Complete introduction to rehype can be found [here](https://github.com/rehypejs/rehype).
cerkiewny marked this conversation as resolved.
Show resolved Hide resolved

## Configuring plugins {#configuring-plugins}

Expand Down Expand Up @@ -76,3 +82,9 @@ module.exports = {
```

See more information in the [MDX documentation](https://mdxjs.com/advanced/plugins).

## Creating own rehype or remark plugins

In order to create own plugins follow those instructions for [remark](https://github.com/remarkjs/remark/blob/main/doc/plugins.md#creating-plugins) or [rehype](https://github.com/remarkjs/remark/blob/main/doc/plugins.md#creating-plugins).

You can also take a look at docusaurus own [plugins](https://github.com/facebook/docusaurus/tree/main/packages/docusaurus-mdx-loader/src/remark) as a source of inspiration on how to write them and what are the good usecases.
cerkiewny marked this conversation as resolved.
Show resolved Hide resolved