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.