Using Markdown Plugins in Astro

Astro uses Remark to render your Markdown which makes it possible to tap into its rich plugin ecosystem ↗. Here, we will learn how to use these plugins on your Astro site.

Let’s start by initializing a project:

npm init astro -- --template blog

Astro config

In the Astro config, add markdownOptions. Astro comes with a few plugins by default. When we want to add a new plugin, we need to list default plugins in the config. Later, you can remove the plugins that you don’t need:

import { defineConfig } from 'astro/config';

export default defineConfig({
  renderers: [],
  markdownOptions: {
    render: [
      '@astrojs/markdown-remark',
      {
        remarkPlugins: ['remark-gfm', 'remark-smartypants'],
        rehypePlugins: ['rehype-slug'],
      },
    ],
  },
});

Adding a plugin

Let’s now add a new plugin. I will use remark-toc ↗ as an example.

First, install the plugin:

npm i -D remark-toc

Second, update the config to include the plugin:

import { defineConfig } from 'astro/config';

export default defineConfig({
  renderers: [],
  markdownOptions: {
    render: [
      '@astrojs/markdown-remark',
      {
        remarkPlugins: [
          // Other remark plugins…
          'remark-toc',
        ],
        // Rehype plugins…
      },
    ],
  },
});

Using the plugin

Now let’s use the plugin. Add a few headings to the pages/posts/index.md file:

<Cool name={frontmatter.name} href="https://twitter.com/n_moore" client:load />

This is so cool!

Do variables work {frontmatter.value \* 2}?

## TOC

## Plants

## Animals

### Cats

### Dogs

``

This should make the plugin generate a table of contents.

Plugin configuration

You can also configurate plugins. Replace a string with a two-item array in the config, and then pass the options inside curly braces:

import { defineConfig } from 'astro/config';

export default defineConfig({
  markdown: {
    render: [
      '@astrojs/markdown-remark',
      {
        remarkPlugins: [
          // Other remark plugins
          ['remark-toc', { ordered: true }],
        ],
        // Rehype plugins
      },
    ],
  },
});

This will make the plugin generate the table of contents as an ordered list.